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.
80 The special sequence <literal>%realm</literal> is replaced by value
81 of attribute <literal>realm</literal> or by realm DATABASE argument.
86 <term>attribute <literal>realm</literal></term>
89 The default realm value. Used for %realm in URL, unless
90 specified in DATABASE argument.
95 <term>attribute <literal>proxy</literal></term>
98 HTTP proxy to bse used for fetching target profiles.
103 <term>attribute <literal>xsldir</literal></term>
106 Directory that is searched for XSL stylesheets. Stylesheets
107 are specified in the target profile by the
108 <literal>transform</literal> element.
113 <term>attribute <literal>element_transform</literal></term>
116 Specifies the element that triggers retrieval and transform using
117 the parameters elementSet, recordEncoding, requestSyntax, transform
118 from the target profile. Default value
119 is "pz2", due to the fact that for historical reasons the
120 common format is that used in Pazpar2.
125 <term>attribute <literal>element_raw</literal></term>
128 Specifies an element that triggers retrieval using the
129 parameters elementSet, recordEncoding, requestSyntax from the
130 target profile. Same actions as for element_transform, but without
131 the XSL transform. Useful for debugging.
132 The default value is "raw".
137 <term>element <literal>records</literal></term>
140 Local target profiles. This element may includes zero or
141 more <literal>record</literal> elements (one per target
142 profile). See section TARGET PROFILE.
148 <refsect2 id="fieldmap">
149 <title>fieldmap</title>
151 The <literal>fieldmap</literal> may be specified zero or more times and
152 specifies the map from CQL fields to CCL fields and takes the
157 <term>attribute <literal>cql</literal></term>
160 CQL field that we are mapping "from".
165 <term>attribute <literal>ccl</literal></term>
168 CCL field that we are mapping "to".
174 <refsect2 id="cclmap_base">
175 <title>cclmap</title>
177 The third part of the configuration consists of zero or more
178 <literal>cclmap</literal> elements that specifies
179 <emphasis>base</emphasis> CCL profile to be used for all targets.
180 This configuration, thus, will be combined with cclmap-definitions
181 from the target profile.
185 <title>contentProxy</title>
187 The <literal>contentProxy</literal> element controls content proxy'in.
189 is optional and must only be defined if content proxy'ing is enabled.
193 <term>attribute <literal>server</literal></term>
196 Specifies the content proxy host. The host is of the form
197 host[:port]. That is without a method (such as HTTP) and optional
203 <term>attribute <literal>tmp_file</literal></term>
206 Specifies a filename of a session file for content proxy'ing. The
207 file should be an absolute filename that includes
208 <literal>XXXXXX</literal> which is replaced by a unique filename
209 using the mkstemp(3) system call. The default value of this
210 setting is <literal>/tmp/cf.XXXXXX.p</literal>.
219 The <literal>log</literal> element controls logging for the
224 <term>attribute <literal>apdu</literal></term>
227 If the value of apdu is "true", then protocol packages
228 (APDUs and HTTP packages) from the ZOOM filter will be
229 logged to the yaz_log system. A value of "false" will
230 not perform logging of protocol packages (the default
239 <title>QUERY HANDLING</title>
241 The ZOOM filter accepts three query types: RPN(Type-1), CCL and
245 Queries are converted in two separate steps. In the first step
246 the input query is converted to RPN/Type-1. This is always
247 the common internal format between step 1 and step 2.
248 In step 2 the query is converted to the native query type of the target.
251 Step 1: for RPN, the query is passed un-modified to the target.
254 Step 1: for CCL, the query is converted to RPN via
255 <link linkend="cclmap"><literal>cclmap</literal></link> elements part of
256 the target profile as well as
257 <link linkend="cclmap_base">base CCL maps</link>.
260 Step 1: For CQL, the query is converted to CCL. The mappings of
261 CQL fields to CCL fields are handled by
262 <link linkend="fieldmap"><literal>fieldmap</literal></link>
263 elements as part of the target profile. The resulting query, CCL,
264 is the converted to RPN using the schema mentioned earlier (via
265 <literal>cclmap</literal>).
268 Step 2: If the target is Z39.50-based, it is passed verbatim (RPN).
269 If the target is SRU-based, the RPN will be converted to CQL.
270 If the target is SOLR-based, the RPN will be converted to SOLR's query
276 <title>SORTING</title>
278 The ZOOM module actively handle CQL sorting - using the SORTBY parameter
279 which was introduced in SRU version 1.2. The conversion from SORTBY clause
280 to native sort for some target is driven by the two parameters:
281 <link linkend="sortStrategy"><literal>sortStrategy</literal></link>
282 and <link linkend="sortmap"><literal>sortmap_</literal><replaceable>field</replaceable></link>.
285 If a sort field that does not have an equivalent
286 <literal>sortmap_</literal>-mapping is passed un-modified through the
287 conversion. It doesn't throw a diagnostic.
292 <title>TARGET PROFILE</title>
294 The ZOOM module is driven by a number of settings that specifies how
295 to handle each target.
296 Note that unknown elements are silently <emphasis>ignored</emphasis>.
299 The elements, in alphabetical order, are:
303 <term>authentication</term><listitem>
305 Authentication parameters to be sent to the target. For
306 Z39.50 targets, this will be sent as part of the
310 If this value is omitted or empty no authentication information is sent.
315 <varlistentry id="cclmap">
316 <term>cclmap_<replaceable>field</replaceable></term><listitem>
318 This value specifies CCL field (qualifier) definition for some
319 field. For Z39.50 targets this most likely will specify the
320 mapping to a numeric use attribute + a structure attribute.
321 For SRU targets, the use attribute should be string based, in
322 order to make the RPN to CQL conversion work properly (step 2).
328 <term>cfAuth</term><listitem>
330 When cfAuth is defined, its value will be used as authentication
331 to backend target and authentication setting will be specified
332 as part of a database. This is like a "proxy" for authentication and
333 is used for Connector Framework based targets.
339 <term>cfProxy</term><listitem>
341 Specifies HTTP proxy for the target in the form
342 <replaceable>host</replaceable>:<replaceable>port</replaceable>.
348 <term>cfSubDB</term><listitem>
350 Specifies sub database for a Connector Framework based target.
355 <varlistentry id="contentConnector">
356 <term>contentConnector</term><listitem>
358 Specifies a database for content-based proxy'ing.
364 <term>elementSet</term><listitem>
366 Specifies the elementSet to be sent to the target if record
367 transform is enabled (not to be confused' with the record_transform
368 module). The record transform is enabled only if the client uses
369 record syntax = XML and a element set determined by
370 the <literal>element_transform</literal> /
371 <literal>element_raw</literal> from the configuration.
372 By default that is the element sets <literal>pz2</literal>
373 and <literal>raw</literal>.
374 If record transform is not enabled, this setting is
375 not used and the element set specified by the client
382 <term>literalTransform</term><listitem>
384 Specifies a XSL stylesheet to be used if record
385 transform is anabled; see description of elementSet.
386 The XSL transform is only used if the element set is set to the
387 value of <literal>element_transform</literal> in the configuration.
390 The value of literalTransform is the XSL - string encoded.
396 <term>piggyback</term><listitem>
398 A value of 1/true is a hint to the ZOOM module that this Z39.50
399 target supports piggyback searches, ie Search Response with
400 records. Any other value (false) will prevent the ZOOM module
401 to make use of piggyback (all records part of Present Response).
407 <term>queryEncoding</term><listitem>
409 If this value is defined, all queries will be converted
410 to this encoding. This should be used for all Z39.50 targets that
411 do not use UTF-8 for query terms.
417 <term>recordEncoding</term><listitem>
419 Specifies the character encoding of records that are returned
420 by the target. This is primarily used for targets were records
421 are not UTF-8 encoded already. This setting is only used
422 if the record transform is enabled (see description of elementSet).
428 <term>requestSyntax</term><listitem>
430 Specifies the record syntax to be specified for the target
431 if record transform is enabled; see description of elementSet.
432 If record transform is not enabled, the record syntax of the
433 client is passed verbatim to the target.
438 <varlistentry id="sortmap">
439 <term>sortmap_<replaceable>field</replaceable></term><listitem>
441 This value the native field for a target. The form of the value is
442 given by <link linkend="sortStrategy">sortStrategy</link>.
447 <varlistentry id="sortStrategy">
448 <term>sortStrategy</term><listitem>
450 Specifies sort strategy for a target. One of:
451 <literal>z3950</literal>, <literal>type7</literal>,
452 <literal>cql</literal>, <literal>sru11</literal> or
453 <literal>embed</literal>. The <literal>embed</literal> chooses type-7
454 or CQL sortby depending on whether Type-1 or CQL is
455 actually sent to the target.
461 <term>sru</term><listitem>
463 If this setting is set, it specifies that the target is web service
464 based and must be one of : <literal>get</literal>,
465 <literal>post</literal>, <literal>soap</literal>
466 or <literal>solr</literal>.
472 <term>transform</term><listitem>
474 Specifies a XSL stylesheet filename to be used if record
475 transform is anabled; see description of elementSet.
476 The XSL transform is only used if the element set is set to the
477 value of <literal>element_transform</literal> in the configuration.
483 <term>udb</term><listitem>
485 This value is required and specifies the unique database for
486 this profile . All target profiles should hold a unique database.
491 <varlistentry id="urlRecipe">
492 <term>urlRecipe</term><listitem>
494 The value of this field is a string that generates a dynamic link
495 based on record content. If the resulting string is non-zero in length
496 a new field, <literal>metadata</literal> with attribute
497 <literal>type="generated-url"</literal>.
498 The contents of this field is the result of the URL recipe conversion.
499 The urlRecipe value may refer to an existing metadata element by
500 ${field[pattern/result/flags]}, which will take content
501 of field and perform a regular expression conversion using the pattern
502 given. For example: <literal>${md-title[\s+/+/g]}</literal> takes
503 metadadata element <literal>title</literal> and converts one or more
504 spaces to a plus character.
507 If the <link linkend="contentConnector">contentConnector</link>
508 setting also defined, the resulting value is
509 augmented with a session string as well as the content proxy server.
515 <term>zurl</term><listitem>
517 This is setting is mandatory and specifies the ZURL of the
518 target in the form of host/database. The HTTP method should
519 not be provided as this is guessed from the "sru" attribute value.
526 <title>DATABASE parameters</title>
528 Extra information may be carried in the Z39.50 Datbase or SRU path,
529 such as authentication to be passed to backend etc. Some of
530 the parameters override TARGET profile values. The format is
533 udb,parm1=value1&parm2=value2&...
536 Where udb is the unique database recognised by the backend and parm1,
537 value1, .. are parameters to be passed. The following describes the
538 supported parameters.
545 Specifies user to be passed to backend. If this parameters is
546 omitted, the user will be taken from TARGET profile setting
547 <literal>authentication</literal>.
552 <term>password</term>
555 Specifies password to be passed to backend. If this parameters is
556 omitted, the password will be taken from TARGET profile setting
557 <literal>authentication</literal>.
565 Specifies proxy to be for backend. If this parameters is
566 omitted, the proxy will be taken from TARGET profile setting
567 <literal>cfProxy</literal>.
572 <term>cproxysession</term>
575 Session ID for content proxy. This parameter is, generally,
576 not used by anything but the content proxy itself.
584 Session realm to be used for this target, changed the resulting
585 URL to be used for getting a target profile, by changing the
586 value that gets substituted for the %realm string.
594 All parameters that has prefix x, dash are passed verbatim
602 <title>SCHEMA</title>
603 <literallayout><xi:include
604 xi:href="../xml/schema/filter_zoom.rnc"
606 xmlns:xi="http://www.w3.org/2001/XInclude" />
611 <title>EXAMPLES</title>
613 The following configuration illustrates most of the
618 url="http://torus.indexdata.com/src/records/?query=udb%3D%db"
619 proxy="localhost:3128"
621 <fieldmap cql="cql.anywhere"/>
622 <fieldmap cql="cql.serverChoice"/>
623 <fieldmap cql="dc.creator" ccl="au"/>
624 <fieldmap cql="dc.title" ccl="ti"/>
625 <fieldmap cql="dc.subject" ccl="su"/>
629 <attr type="u" value="12"/>
630 <attr type="s" value="107"/>
642 <title>SEE ALSO</title>
645 <refentrytitle>metaproxy</refentrytitle>
646 <manvolnum>1</manvolnum>
651 <refentrytitle>virt_db</refentrytitle>
652 <manvolnum>3mp</manvolnum>
660 <!-- Keep this comment at the end of the file