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>
25 <title>DESCRIPTION</title>
27 This filter implements a generic client based on
28 <ulink url="&url.yaz.zoom;">ZOOM</ulink> of YAZ.
29 The client implements the protocols that ZOOM C does: Z39.50, SRU
30 (GET, POST, SOAP) and SOLR .
34 This filter only deals with Z39.50 on input. The following services
35 are supported: init, search, present and close. The backend target
36 is selected based on the database as part search and
37 <emphasis>not</emphasis> as part of init.
41 This filter is an alternative to the z3950_client filter but also
42 shares properties of the virt_db - in that the target is selected
43 for a specific database
47 The ZOOM filter relies on a target profile description, which is
48 XML based. It picks the profile for a given database from a web service
49 or it may be locally given for each unique database (AKA virtual database
50 in virt_db). Target profiles are directly and indrectly given as part
51 of the <literal>torus</literal> element in the configuration.
57 <title>CONFIGURATION</title>
59 The configuration consists of five parts: <literal>torus</literal>,
60 <literal>fieldmap</literal>, <literal>cclmap</literal>,
61 <literal>contentProxy</literal> and <literal>log</literal>.
66 The <literal>torus</literal> element specifies target profiles
67 and takes the following content:
71 <term>attribute <literal>url</literal></term>
74 URL of Web service to be used to fetch target profile
75 for a given database (udb). The special sequence
76 <literal>%db</literal> of the URL is replaced by the
77 actual database specified as part of Search.
82 <term>attribute <literal>proxy</literal></term>
85 HTTP proxy to bse used for fetching target profiles.
90 <term>attribute <literal>xsldir</literal></term>
93 Directory that is searched for XSL stylesheets. Stylesheets
94 are specified in the target profile by the
95 <literal>transform</literal> element.
100 <term>attribute <literal>element_transform</literal></term>
103 Specifies the element that triggers retrieval and transform using
104 the parameters elementSet, recordEncoding, requestSyntax, transform
105 from the target profile. Default value
106 is "pz2", due to the fact that for historical reasons the
107 common format is that used in Pazpar2.
112 <term>attribute <literal>element_raw</literal></term>
115 Specifies an element that triggers retrieval using the
116 parameters elementSet, recordEncoding, requestSyntax from the
117 target profile. Same actions as for element_transform, but without
118 the XSL transform. Useful for debugging.
119 The default value is "raw".
124 <term>element <literal>records</literal></term>
127 Local target profiles. This element may includes zero or
128 more <literal>record</literal> elements (one per target
129 profile). See section TARGET PROFILE.
136 <title>fieldmap</title>
138 The <literal>fieldmap</literal> may be specified zero or more times and
139 specifies the map from CQL fields to CCL fields and takes the
144 <term>attribute <literal>cql</literal></term>
147 CQL field that we are mapping "from".
152 <term>attribute <literal>ccl</literal></term>
155 CCL field that we are mapping "to".
162 <title>cclmap</title>
164 The third part of the configuration consists of zero or more
165 <literal>cclmap</literal> elements that specifies
166 <emphasis>base</emphasis> CCL profile to be used for all targets.
167 This configuration, thus, will be combined with cclmap-definitions
168 from the target profile.
172 <title>contentProxy</title>
174 The <literal>contentProxy</literal> element controls content proxy'in.
176 is optional and must only be defined if content proxy'ing is enabled.
180 <term>attribute <literal>server</literal></term>
183 Specifies the content proxy host. The host is of the form
184 host[:port]. That is without a method (such as HTTP) and optional
190 <term>attribute <literal>tmp_file</literal></term>
193 Specifies a filename of a session file for content proxy'ing. The
194 file should be an absolute filename that includes
195 <literal>XXXXXX</literal> which is replaced by a unique filename
196 using the mkstemp(3) system call. The default value of this
197 setting is <literal>/tmp/cf.XXXXXX.p</literal>.
206 The <literal>log</literal> element controls logging for the
211 <term>attribute <literal>apdu</literal></term>
214 If the value of apdu is "true", then protocol packages
215 (APDUs and HTTP packages) from the ZOOM filter will be
216 logged to the yaz_log system. A value of "false" will
217 not perform logging of protocol packages (the default
226 <title>QUERY HANDLING</title>
228 The ZOOM filter accepts three query types: RPN(Type-1), CCL and
232 Queries are converted in two separate steps. In the first step
233 the input query is converted to RPN/Type-1. This is always
234 the common internal format between step 1 and step 2.
235 In step 2 the query is converted to the native query type of the target.
238 Step 1: for RPN, the query is passed un-modified to the target.
241 Step 1: for CCL, the query is converted to RPN via
242 <literal>cclmap</literal> elements part of the target profile.
245 Step 1: For CQL, the query is converted to CCL. The mappings of
246 CQL fields to CCL fields are handled by <literal>fieldmap</literal>
247 elements as part of the target profile. The resulting query, CCL,
248 is the converted to RPN using the schema mentioned earlier (via
249 <literal>cclmap</literal>).
252 Step 2: If the target is Z39.50-based, it is passed verbatim (RPN).
253 If the target is SRU-based, the RPN will be converted to CQL.
254 If the target is SOLR-based, the RPN will be converted to SOLR's query
260 <title>SORTING</title>
262 The ZOOM module actively handle CQL sorting - using the SORTBY parameter
263 which was introduced in SRU version 1.2. The conversion from SORTBY clause
264 to native sort for some target is driven by the two parameters:
265 <literal>sortStrategy</literal>
266 and <literal>sortmap_</literal><replaceable>field</replaceable>.
269 If a sort field that does not have an equivalent
270 <literal>sortmap_</literal>-mapping is passed un-modified through the
271 conversion. It doesn't throw a diagnostic.
276 <title>TARGET PROFILE</title>
278 The ZOOM module is driven by a number of settings that specifies how
279 to handle each target.
280 Note that unknown elements are silently <emphasis>ignored</emphasis>.
283 The elements, in alphabetical order, are:
287 <term>authentication</term><listitem>
289 Authentication parameters to be sent to the target. For
290 Z39.50 targets, this will be sent as part of the
294 If this value is omitted or empty no authentication information is sent.
300 <term>cclmap_*</term><listitem>
302 This value specifies CCL field (qualifier) definition for some
303 field. For Z39.50 targets this most likely will specify the
304 mapping to a numeric use attribute + a structure attribute.
305 For SRU targets, the use attribute should be string based, in
306 order to make the RPN to CQL conversion work properly (step 2).
312 <term>cfAuth</term><listitem>
314 When cfAuth is defined, its value will be used as authentication
315 to backend target and authentication setting will be specified
316 as part of a database. This is like a "proxy" for authentication and
317 is used for Connector Framework based targets.
323 <term>cfProxy</term><listitem>
325 Specifies HTTP proxy for the target in the form
326 <replaceable>host</replaceable>:<replaceable>port</replaceable>.
332 <term>cfSubDb</term><listitem>
334 Specifies sub database for a Connector Framework based target.
340 <term>contentConnector</term><listitem>
342 Specifies a database for content-based proxy'ing.
348 <term>elementSet</term><listitem>
350 Specifies the elementSet to be sent to the target if record
351 transform is enabled (not to be confused' with the record_transform
352 module). The record transform is enabled only if the client uses
353 record syntax = XML and a element set determined by
354 the <literal>element_transform</literal> /
355 <literal>element_raw</literal> from the configuration.
356 By default that is the element sets <literal>pz2</literal>
357 and <literal>raw</literal>.
358 If record transform is not enabled, this setting is
359 not used and the element set specified by the client
366 <term>literalTransform</term><listitem>
368 Specifies a XSL stylesheet to be used if record
369 transform is anabled; see description of elementSet.
370 The XSL transform is only used if the element set is set to the
371 value of <literal>element_transform</literal> in the configuration.
374 The value of literalTransform is the XSL - string encoded.
380 <term>piggyback</term><listitem>
382 A value of 1/true is a hint to the ZOOM module that this Z39.50
383 target supports piggyback searches, ie Search Response with
384 records. Any other value (false) will prevent the ZOOM module
385 to make use of piggyback (all records part of Present Response).
391 <term>queryEncoding</term><listitem>
393 If this value is defined, all queries will be converted
394 to this encoding. This should be used for all Z39.50 targets that
395 do not use UTF-8 for query terms.
401 <term>recordEncoding</term><listitem>
403 Specifies the character encoding of records that are returned
404 by the target. This is primarily used for targets were records
405 are not UTF-8 encoded already. This setting is only used
406 if the record transform is enabled (see description of elementSet).
412 <term>requestSyntax</term><listitem>
414 Specifies the record syntax to be specified for the target
415 if record transform is enabled; see description of elementSet.
416 If record transform is not enabled, the record syntax of the
417 client is passed verbatim to the target.
423 <term>sortmap_</term><listitem>
425 This value the native field for a target.
431 <term>sortStrategy</term><listitem>
433 Specifies sort strategy for a target. One of:
434 <literal>z3950</literal>, <literal>type7</literal>,
435 <literal>cql</literal>, <literal>sru11</literal> or
436 <literal>embed</literal>. The <literal>embed</literal> chooses type-7
437 or CQL sortby depending on whether Type-1 or CQL is
438 actually sent to the target.
444 <term>sru</term><listitem>
446 If this setting is set, it specifies that the target is web service
447 based and must be one of : <literal>get</literal>,
448 <literal>post</literal>, <literal>soap</literal>
449 or <literal>solr</literal>.
455 <term>transform</term><listitem>
457 Specifies a XSL stylesheet filename to be used if record
458 transform is anabled; see description of elementSet.
459 The XSL transform is only used if the element set is set to the
460 value of <literal>element_transform</literal> in the configuration.
466 <term>udb</term><listitem>
468 This value is required and specifies the unique database for
469 this profile . All target profiles should hold a unique database.
475 <term>urlRecipe</term><listitem>
477 The value of this field is a string that generates a dynamic link
478 based on content. If the resulting string is non-zero in length
479 a new field, <literal>metadata</literal> with attribute
480 type=generated-url. The contents of this field is the result of the
481 URL recipe conversion. The urlRecipe value may refer to an existing
482 metadata element by ${field[pattern/result/flags]}, which will take content
483 of field and perform a regular expression conversion using the pattern
484 given. For example: <literal>${md-title[\s+/+/g]}</literal> takes
485 metadadata element <literal>title</literal> and converts one or more
486 spaces to a plus character.
489 If the contentConnector setting is defined the resulting value is
490 agmented with a session string as well as the content proxy server.
496 <term>zurl</term><listitem>
498 This is setting is mandatory and specifies the ZURL of the
499 target in the form of host/database. The HTTP method should
500 not be provide as this is guessed from the "sru" attribute value.
507 <title>SCHEMA</title>
508 <literallayout><xi:include
509 xi:href="../xml/schema/filter_zoom.rnc"
511 xmlns:xi="http://www.w3.org/2001/XInclude" />
516 <title>EXAMPLES</title>
518 The following configuration illustrates most of the
523 url="http://torus.indexdata.com/src/records/?query=udb%3D%db"
524 proxy="localhost:3128"
526 <fieldmap cql="cql.anywhere"/>
527 <fieldmap cql="cql.serverChoice"/>
528 <fieldmap cql="dc.creator" ccl="au"/>
529 <fieldmap cql="dc.title" ccl="ti"/>
530 <fieldmap cql="dc.subject" ccl="su"/>
534 <attr type="u" value="12"/>
535 <attr type="s" value="107"/>
547 <title>SEE ALSO</title>
550 <refentrytitle>metaproxy</refentrytitle>
551 <manvolnum>1</manvolnum>
556 <refentrytitle>virt_db</refentrytitle>
557 <manvolnum>3mp</manvolnum>
565 <!-- Keep this comment at the end of the file