1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
2 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
3 <!ENTITY copyright SYSTEM "copyright.xml">
4 <!ENTITY % idcommon SYSTEM "common/common.ent">
7 <refentry id="ref-zoom">
9 <productname>Metaproxy</productname>
10 <info><orgname>Index Data</orgname></info>
14 <refentrytitle>zoom</refentrytitle>
15 <manvolnum>3mp</manvolnum>
16 <refmiscinfo class="manual">Metaproxy Module</refmiscinfo>
20 <refname>zoom</refname>
21 <refpurpose>Metaproxy ZOOM Module</refpurpose>
24 <refsect1><title>DESCRIPTION</title>
26 This filter implements a generic client based on
27 <ulink url="&url.yaz.zoom;">ZOOM</ulink> of YAZ.
28 The client implements the protocols that ZOOM C does: Z39.50, SRU
29 (GET, POST, SOAP) and SOLR .
33 This filter only deals with Z39.50 on input. The following services
34 are supported: init, search, present and close. The backend target
35 is selected based on the database as part search and
36 <emphasis>not</emphasis> as part of init.
40 This filter is an alternative to the z3950_client filter but also
41 shares properties of the virt_db - in that the target is selected
42 for a specific database
46 The ZOOM filter relies on a target profile description, which is
47 XML based. It picks the profile for a given database from a web service
48 or it may be locally given for each unique database (AKA virtual database
49 in virt_db). Target profiles are directly and indrectly given as part
50 of the <literal>torus</literal> element in the configuration.
55 <refsect1><title>CONFIGURATION</title>
57 The configuration consists of three parts: <literal>torus</literal>,
58 <literal>fieldmap</literal> and <literal>cclmap</literal>.
61 The <literal>torus</literal> element specifies target profiles
62 and takes the following content:
65 <varlistentry><term>attribute <literal>url</literal></term><listitem><para>
66 URL of Web service to be used to fetch target profile
67 for a given database (udb). The special sequence
68 <literal>%db</literal> of the URL is replaced by the
69 actual database specified as part of Search.
73 <varlistentry><term>attribute <literal>xsldir</literal></term><listitem><para>
74 Directory that is searched for XSL stylesheets. Stylesheets
75 are specified in the target profile by the
76 <literal>transform</literal> element.
80 <varlistentry><term>element <literal>records</literal></term><listitem><para>
81 Local target profiles. This element may includes zero or
82 more <literal>record</literal> elements (one per target
83 profile). See section TARGET PROFILE.
89 The <literal>fieldmap</literal> may be specified zero or more times and
90 specifies the map from CQL fields to CCL fields and takes the
94 <varlistentry><term>attribute <literal>cql</literal></term><listitem><para>
99 <varlistentry><term>attribute <literal>ccl</literal></term><listitem><para>
106 The final part of the configuration consists of zero or more
107 <literal>cclmap</literal> elements that specifies a <emphais>base</emphais>
108 CCL profile to be used for all targets. This configuration, thus, will
109 be combined with cclmap-definitions from the target profile.
112 <refsect1><title>QUERIES</title>
114 The ZOOM filter accepts three query types: RPN(Type-1), CCL and
118 Queries are converted in two separate steps. In the first step
119 the input query is converted to RPN/Type-1. This is always
120 the common internal format between step 1 and step 2.
121 In step 2 the query is converted to the native query type of the target.
124 Step 1: for RPN, the query is passed unmodified to the target.
127 Step 1: for CCL, the query is converted to RPN via
128 <literal>cclmap</literal> elements part of the target profile.
131 Step 1: For CQL, the query is converted to CCL. The mappings of
132 CQL fields to CCL fields are handled by <literal>fieldmap</literal>
133 elements as part of the target profile. The resulting query, CCL,
134 is the converted to RPN using the schema mentioned earlier (via
135 <literal>cclmap</literal>).
138 Step 2: If the target is Z39.50-based, it is passed verbatim (RPN).
139 If the target is SRU-based, the RPN will be converted to CQL.
140 If the target is SOLR-based, the RPN will be converted to SOLR's query
145 <refsect1><title>TARGET PROFILE</title>
147 The following elements are honored by the ZOOM module of Metaproxy.
148 Note that unknown elements are silently ignored. There are several
149 elements in use that makes no sense to the ZOOM module.
153 <term>authentication</term><listitem>
155 Authentication parameters to be sent to the target. For
156 Z39.50 targets, this will be sent as part of the
160 If this value is omitted or empty, not authentication information
167 <term>piggyback</term><listitem>
169 A value of 1/true is a hint to the ZOOM module that this Z39.50
170 target supports piggyback searches, ie Search Response with
171 records. Any other value (false) will prevent the ZOOM module
172 to make use of piggyback (all records part of Present Response).
178 <term>queryEncoding</term><listitem>
180 If this value is defined, all queries will be converted
181 to this encoding. This should be used for all Z39.50 targets that
182 do not use UTF-8 for query terms.
188 <term>udb</term><listitem>
190 This value is required and specifies the unique database for
191 this profile . All target profiles should hold a unique database.
197 <term>cclmap_*</term><listitem>
199 This value specifies CCL field (qualifier) definition for some
200 field. For Z39.50 targets this most likely will specify the
201 mapping to a numeric use attribute + a structure attribute.
202 For SRU targets, the use attribute should be string based, in
203 order to make the RPN to CQL conversion work properly (step 2).
209 <term>elementSet</term><listitem>
211 Specifies the elementSet to be sent to the target if record
212 transform is enabled (not to be used with the record_transform
213 module). The record transform is enabled only if the client uses
214 record syntax = XML and element set =
215 <literal>pz2</literal>. If record transform is not enabled, this
216 setting is not used and the element set specified by the client
223 <term>recordEncoding</term><listitem>
225 Specifies the character encoding of records that are returned
226 by the target. This is primarily used for targets were records
227 are not UTF-8 encoded already. This setting is only used
228 if the record transform is enabled (see description of elementSet).
234 <term>requestSyntax</term><listitem>
236 Specifies the record syntax to be specified for the target
237 if record transform is enabled; see description of elementSet.
238 If record transform is not enabled, the record syntax of the
239 client is passed verbatim to the target.
245 <term>sru</term><listitem>
247 If this setting is set, it specifies that the target is web service
248 based and must be one of : <literal>get</literal>,
249 <literal>post</literal>, <literal>soap</literal>
250 or <literal>solr</literal>.
256 <term>transform</term><listitem>
258 Specifies a XSL stylesheet filename to be used if record
259 transform is anabled; see desciprion of elementSet.
265 <term>zurl</term><listitem>
267 This is setting is mandatory and specifies the ZURL of the
268 targetin the form of host/database.
274 <refsect1><title>SCHEMA</title>
275 <literallayout><xi:include
276 xi:href="../xml/schema/filter_zoom.rnc"
278 xmlns:xi="http://www.w3.org/2001/XInclude" />
282 <refsect1><title>EXAMPLES</title>
284 The following configuration illustrates most of the
289 url="http://torus.indexdata.com/src/records/?query=udb%3D%db"
292 <fieldmap cql="cql.anywhere"/>
293 <fieldmap cql="cql.serverChoice"/>
294 <fieldmap cql="dc.creator" ccl="au"/>
295 <fieldmap cql="dc.title" ccl="ti"/>
296 <fieldmap cql="dc.subject" ccl="su"/>
300 <attr type="u" value="12"/>
301 <attr type="s" value="107"/>
311 <refsect1><title>SEE ALSO</title>
314 <refentrytitle>metaproxy</refentrytitle>
315 <manvolnum>1</manvolnum>
320 <refentrytitle>virt_db</refentrytitle>
321 <manvolnum>3mp</manvolnum>
329 <!-- Keep this comment at the end of the file
334 sgml-minimize-attributes:nil
335 sgml-always-quote-attributes:t
338 sgml-parent-document:nil
339 sgml-local-catalogs: nil
340 sgml-namecase-general:t