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.
135 <refsect2 id="fieldmap">
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".
161 <refsect2 id="cclmap_base">
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 <link linkend="cclmap"><literal>cclmap</literal></link> elements part of
243 the target profile as well as
244 <link linkend="cclmap_base">base CCL maps</link>.
247 Step 1: For CQL, the query is converted to CCL. The mappings of
248 CQL fields to CCL fields are handled by
249 <link linkend="fieldmap"><literal>fieldmap</literal></link>
250 elements as part of the target profile. The resulting query, CCL,
251 is the converted to RPN using the schema mentioned earlier (via
252 <literal>cclmap</literal>).
255 Step 2: If the target is Z39.50-based, it is passed verbatim (RPN).
256 If the target is SRU-based, the RPN will be converted to CQL.
257 If the target is SOLR-based, the RPN will be converted to SOLR's query
263 <title>SORTING</title>
265 The ZOOM module actively handle CQL sorting - using the SORTBY parameter
266 which was introduced in SRU version 1.2. The conversion from SORTBY clause
267 to native sort for some target is driven by the two parameters:
268 <link linkend="sortStrategy"><literal>sortStrategy</literal></link>
269 and <link linkend="sortmap"><literal>sortmap_</literal><replaceable>field</replaceable></link>.
272 If a sort field that does not have an equivalent
273 <literal>sortmap_</literal>-mapping is passed un-modified through the
274 conversion. It doesn't throw a diagnostic.
279 <title>TARGET PROFILE</title>
281 The ZOOM module is driven by a number of settings that specifies how
282 to handle each target.
283 Note that unknown elements are silently <emphasis>ignored</emphasis>.
286 The elements, in alphabetical order, are:
290 <term>authentication</term><listitem>
292 Authentication parameters to be sent to the target. For
293 Z39.50 targets, this will be sent as part of the
297 If this value is omitted or empty no authentication information is sent.
302 <varlistentry id="cclmap">
303 <term>cclmap_<replaceable>field</replaceable></term><listitem>
305 This value specifies CCL field (qualifier) definition for some
306 field. For Z39.50 targets this most likely will specify the
307 mapping to a numeric use attribute + a structure attribute.
308 For SRU targets, the use attribute should be string based, in
309 order to make the RPN to CQL conversion work properly (step 2).
315 <term>cfAuth</term><listitem>
317 When cfAuth is defined, its value will be used as authentication
318 to backend target and authentication setting will be specified
319 as part of a database. This is like a "proxy" for authentication and
320 is used for Connector Framework based targets.
326 <term>cfProxy</term><listitem>
328 Specifies HTTP proxy for the target in the form
329 <replaceable>host</replaceable>:<replaceable>port</replaceable>.
335 <term>cfSubDb</term><listitem>
337 Specifies sub database for a Connector Framework based target.
342 <varlistentry id="contentConnector">
343 <term>contentConnector</term><listitem>
345 Specifies a database for content-based proxy'ing.
351 <term>elementSet</term><listitem>
353 Specifies the elementSet to be sent to the target if record
354 transform is enabled (not to be confused' with the record_transform
355 module). The record transform is enabled only if the client uses
356 record syntax = XML and a element set determined by
357 the <literal>element_transform</literal> /
358 <literal>element_raw</literal> from the configuration.
359 By default that is the element sets <literal>pz2</literal>
360 and <literal>raw</literal>.
361 If record transform is not enabled, this setting is
362 not used and the element set specified by the client
369 <term>literalTransform</term><listitem>
371 Specifies a XSL stylesheet to be used if record
372 transform is anabled; see description of elementSet.
373 The XSL transform is only used if the element set is set to the
374 value of <literal>element_transform</literal> in the configuration.
377 The value of literalTransform is the XSL - string encoded.
383 <term>piggyback</term><listitem>
385 A value of 1/true is a hint to the ZOOM module that this Z39.50
386 target supports piggyback searches, ie Search Response with
387 records. Any other value (false) will prevent the ZOOM module
388 to make use of piggyback (all records part of Present Response).
394 <term>queryEncoding</term><listitem>
396 If this value is defined, all queries will be converted
397 to this encoding. This should be used for all Z39.50 targets that
398 do not use UTF-8 for query terms.
404 <term>recordEncoding</term><listitem>
406 Specifies the character encoding of records that are returned
407 by the target. This is primarily used for targets were records
408 are not UTF-8 encoded already. This setting is only used
409 if the record transform is enabled (see description of elementSet).
415 <term>requestSyntax</term><listitem>
417 Specifies the record syntax to be specified for the target
418 if record transform is enabled; see description of elementSet.
419 If record transform is not enabled, the record syntax of the
420 client is passed verbatim to the target.
425 <varlistentry id="sortmap">
426 <term>sortmap_<replaceable>field</replaceable></term><listitem>
428 This value the native field for a target. The form of the value is
429 given by <link linkend="sortStrategy">sortStrategy</link>.
434 <varlistentry id="sortStrategy">
435 <term>sortStrategy</term><listitem>
437 Specifies sort strategy for a target. One of:
438 <literal>z3950</literal>, <literal>type7</literal>,
439 <literal>cql</literal>, <literal>sru11</literal> or
440 <literal>embed</literal>. The <literal>embed</literal> chooses type-7
441 or CQL sortby depending on whether Type-1 or CQL is
442 actually sent to the target.
448 <term>sru</term><listitem>
450 If this setting is set, it specifies that the target is web service
451 based and must be one of : <literal>get</literal>,
452 <literal>post</literal>, <literal>soap</literal>
453 or <literal>solr</literal>.
459 <term>transform</term><listitem>
461 Specifies a XSL stylesheet filename to be used if record
462 transform is anabled; see description of elementSet.
463 The XSL transform is only used if the element set is set to the
464 value of <literal>element_transform</literal> in the configuration.
470 <term>udb</term><listitem>
472 This value is required and specifies the unique database for
473 this profile . All target profiles should hold a unique database.
478 <varlistentry id="urlRecipe">
479 <term>urlRecipe</term><listitem>
481 The value of this field is a string that generates a dynamic link
482 based on record content. If the resulting string is non-zero in length
483 a new field, <literal>metadata</literal> with attribute
484 <literal>type="generated-url"</literal>.
485 The contents of this field is the result of the URL recipe conversion.
486 The urlRecipe value may refer to an existing metadata element by
487 ${field[pattern/result/flags]}, which will take content
488 of field and perform a regular expression conversion using the pattern
489 given. For example: <literal>${md-title[\s+/+/g]}</literal> takes
490 metadadata element <literal>title</literal> and converts one or more
491 spaces to a plus character.
494 If the <link linkend="contentConnector">contentConnector</link>
495 setting also defined, the resulting value is
496 augmented with a session string as well as the content proxy server.
502 <term>zurl</term><listitem>
504 This is setting is mandatory and specifies the ZURL of the
505 target in the form of host/database. The HTTP method should
506 not be provided as this is guessed from the "sru" attribute value.
513 <title>SCHEMA</title>
514 <literallayout><xi:include
515 xi:href="../xml/schema/filter_zoom.rnc"
517 xmlns:xi="http://www.w3.org/2001/XInclude" />
522 <title>EXAMPLES</title>
524 The following configuration illustrates most of the
529 url="http://torus.indexdata.com/src/records/?query=udb%3D%db"
530 proxy="localhost:3128"
532 <fieldmap cql="cql.anywhere"/>
533 <fieldmap cql="cql.serverChoice"/>
534 <fieldmap cql="dc.creator" ccl="au"/>
535 <fieldmap cql="dc.title" ccl="ti"/>
536 <fieldmap cql="dc.subject" ccl="su"/>
540 <attr type="u" value="12"/>
541 <attr type="s" value="107"/>
553 <title>SEE ALSO</title>
556 <refentrytitle>metaproxy</refentrytitle>
557 <manvolnum>1</manvolnum>
562 <refentrytitle>virt_db</refentrytitle>
563 <manvolnum>3mp</manvolnum>
571 <!-- Keep this comment at the end of the file