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 four parts: <literal>torus</literal>,
58 <literal>fieldmap</literal>, <literal>cclmap</literal>
59 and <literal>log</literal>.
61 <refsect2><title>torus</title>
63 The <literal>torus</literal> element specifies target profiles
64 and takes the following content:
68 <term>attribute <literal>url</literal></term>
71 URL of Web service to be used to fetch target profile
72 for a given database (udb). The special sequence
73 <literal>%db</literal> of the URL is replaced by the
74 actual database specified as part of Search.
79 <term>attribute <literal>proxy</literal></term>
82 HTTP proxy to bse used for fetching target profiles.
87 <term>attribute <literal>xsldir</literal></term>
90 Directory that is searched for XSL stylesheets. Stylesheets
91 are specified in the target profile by the
92 <literal>transform</literal> element.
97 <term>attribute <literal>element_transform</literal></term>
100 Specifies the element that triggers retrieval and transform using
101 the parameters elementSet, recordEncoding, requestSyntax, transform
102 from the target profile. Default value
103 is "pz2", due to the fact that for historical reasons the
104 common format is that used in Pazpar2.
109 <term>attribute <literal>element_raw</literal></term>
112 Specifies an element that triggers retrieval using the
113 parameters elementSet, recordEncoding, requestSyntax from the
114 target profile. Same actions as for element_transform, but without
115 the XSL transform. Useful for debugging.
116 The default value is "raw".
121 <term>element <literal>records</literal></term>
124 Local target profiles. This element may includes zero or
125 more <literal>record</literal> elements (one per target
126 profile). See section TARGET PROFILE.
132 <refsect2><title>fieldmap</title>
134 The <literal>fieldmap</literal> may be specified zero or more times and
135 specifies the map from CQL fields to CCL fields and takes the
140 <term>attribute <literal>cql</literal></term>
143 CQL field that we are mapping "from".
148 <term>attribute <literal>ccl</literal></term>
151 CCL field that we are mapping "to".
157 <refsect2><title>cclmap</title>
159 The third part of the configuration consists of zero or more
160 <literal>cclmap</literal> elements that specifies
161 <emphasis>base</emphasis> CCL profile to be used for all targets.
162 This configuration, thus, will be combined with cclmap-definitions
163 from the target profile.
166 <refsect2><title>log</title>
168 The <literal>log</literal> element controls logging for the
173 <term>attribute <literal>apdu</literal></term>
176 If the value of apdu is "true", then protocol packages
177 (APDUs and HTTP packages) from the ZOOM filter will be
178 logged to the yaz_log system. A value of "false" will
179 not perform logging of protocol packages (the default
187 <refsect1><title>QUERY HANDLING</title>
189 The ZOOM filter accepts three query types: RPN(Type-1), CCL and
193 Queries are converted in two separate steps. In the first step
194 the input query is converted to RPN/Type-1. This is always
195 the common internal format between step 1 and step 2.
196 In step 2 the query is converted to the native query type of the target.
199 Step 1: for RPN, the query is passed unmodified to the target.
202 Step 1: for CCL, the query is converted to RPN via
203 <literal>cclmap</literal> elements part of the target profile.
206 Step 1: For CQL, the query is converted to CCL. The mappings of
207 CQL fields to CCL fields are handled by <literal>fieldmap</literal>
208 elements as part of the target profile. The resulting query, CCL,
209 is the converted to RPN using the schema mentioned earlier (via
210 <literal>cclmap</literal>).
213 Step 2: If the target is Z39.50-based, it is passed verbatim (RPN).
214 If the target is SRU-based, the RPN will be converted to CQL.
215 If the target is SOLR-based, the RPN will be converted to SOLR's query
220 <refsect1><title>TARGET PROFILE</title>
222 The following elements are honored by the ZOOM module of Metaproxy.
223 Note that unknown elements are silently ignored. There are several
224 elements in use that makes no sense to the ZOOM module.
228 <term>authentication</term><listitem>
230 Authentication parameters to be sent to the target. For
231 Z39.50 targets, this will be sent as part of the
235 If this value is omitted or empty, not authentication information
242 <term>piggyback</term><listitem>
244 A value of 1/true is a hint to the ZOOM module that this Z39.50
245 target supports piggyback searches, ie Search Response with
246 records. Any other value (false) will prevent the ZOOM module
247 to make use of piggyback (all records part of Present Response).
253 <term>queryEncoding</term><listitem>
255 If this value is defined, all queries will be converted
256 to this encoding. This should be used for all Z39.50 targets that
257 do not use UTF-8 for query terms.
263 <term>udb</term><listitem>
265 This value is required and specifies the unique database for
266 this profile . All target profiles should hold a unique database.
272 <term>cclmap_*</term><listitem>
274 This value specifies CCL field (qualifier) definition for some
275 field. For Z39.50 targets this most likely will specify the
276 mapping to a numeric use attribute + a structure attribute.
277 For SRU targets, the use attribute should be string based, in
278 order to make the RPN to CQL conversion work properly (step 2).
284 <term>elementSet</term><listitem>
286 Specifies the elementSet to be sent to the target if record
287 transform is enabled (not to be confused' with the record_transform
288 module). The record transform is enabled only if the client uses
289 record syntax = XML and a element set determined by
290 the <literal>element_transform</literal> /
291 <literal>element_raw</literal> from the configuration.
292 By default that is the element sets <literal>pz2</literal>
293 and <literal>raw</literal>.
294 If record transform is not enabled, this setting is
295 not used and the element set specified by the client
302 <term>recordEncoding</term><listitem>
304 Specifies the character encoding of records that are returned
305 by the target. This is primarily used for targets were records
306 are not UTF-8 encoded already. This setting is only used
307 if the record transform is enabled (see description of elementSet).
313 <term>requestSyntax</term><listitem>
315 Specifies the record syntax to be specified for the target
316 if record transform is enabled; see description of elementSet.
317 If record transform is not enabled, the record syntax of the
318 client is passed verbatim to the target.
324 <term>sru</term><listitem>
326 If this setting is set, it specifies that the target is web service
327 based and must be one of : <literal>get</literal>,
328 <literal>post</literal>, <literal>soap</literal>
329 or <literal>solr</literal>.
335 <term>transform</term><listitem>
337 Specifies a XSL stylesheet filename to be used if record
338 transform is anabled; see desciprion of elementSet.
339 The XSL transform is only used if the element set is set to the
340 value of <literal>element_transform</literal> in the configuration.
346 <term>zurl</term><listitem>
348 This is setting is mandatory and specifies the ZURL of the
349 target in the form of host/database. The HTTP method should
350 not be provide as this is guessed from the "sru" attribute value.
356 <refsect1><title>SCHEMA</title>
357 <literallayout><xi:include
358 xi:href="../xml/schema/filter_zoom.rnc"
360 xmlns:xi="http://www.w3.org/2001/XInclude" />
364 <refsect1><title>EXAMPLES</title>
366 The following configuration illustrates most of the
371 url="http://torus.indexdata.com/src/records/?query=udb%3D%db"
372 proxy="localhost:3128"
374 <fieldmap cql="cql.anywhere"/>
375 <fieldmap cql="cql.serverChoice"/>
376 <fieldmap cql="dc.creator" ccl="au"/>
377 <fieldmap cql="dc.title" ccl="ti"/>
378 <fieldmap cql="dc.subject" ccl="su"/>
382 <attr type="u" value="12"/>
383 <attr type="s" value="107"/>
394 <refsect1><title>SEE ALSO</title>
397 <refentrytitle>metaproxy</refentrytitle>
398 <manvolnum>1</manvolnum>
403 <refentrytitle>virt_db</refentrytitle>
404 <manvolnum>3mp</manvolnum>
412 <!-- Keep this comment at the end of the file
417 sgml-minimize-attributes:nil
418 sgml-always-quote-attributes:t
421 sgml-parent-document:nil
422 sgml-local-catalogs: nil
423 sgml-namecase-general:t