Minor documentation updates.
[metaproxy-moved-to-github.git] / doc / zoom.xml
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">
5      %idcommon;
6 ]>
7 <refentry id="ref-zoom">
8  <refentryinfo>
9   <productname>Metaproxy</productname>
10   <info><orgname>Index Data</orgname></info>
11  </refentryinfo>
12  
13  <refmeta>
14   <refentrytitle>zoom</refentrytitle>
15   <manvolnum>3mp</manvolnum>
16   <refmiscinfo class="manual">Metaproxy Module</refmiscinfo>
17  </refmeta>
18  
19  <refnamediv>
20   <refname>zoom</refname>
21   <refpurpose>Metaproxy ZOOM Module</refpurpose>
22  </refnamediv>
23  
24  <refsect1>
25   <title>DESCRIPTION</title>
26   <para>
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 .
31   </para>
32   
33   <para>
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.
38   </para>
39
40   <para>
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
44   </para>
45
46   <para>
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.
52   </para>
53
54  </refsect1>
55
56  <refsect1>
57   <title>CONFIGURATION</title>
58   <para>
59    The configuration consists of six parts: <literal>torus</literal>,
60    <literal>fieldmap</literal>, <literal>cclmap</literal>,
61    <literal>contentProxy</literal>, <literal>log</literal>
62    and <literal>zoom</literal>.
63   </para>
64   <refsect2>
65    <title>torus</title>
66    <para>
67     The <literal>torus</literal> element specifies target profiles
68     and takes the following content:
69    </para>
70    <variablelist>
71     <varlistentry>
72      <term>attribute <literal>url</literal></term>
73      <listitem>
74       <para>
75        URL of Web service to be used when fetch target profiles from
76        a remote service (Torus normally).
77       </para>
78       <para>
79        The sequence <literal>%query</literal> is replaced with a CQL
80        query for the Torus search.
81       </para>
82       <para>
83        The special sequence <literal>%realm</literal> is replaced by value
84        of attribute <literal>realm</literal> or by realm DATABASE argument.
85       </para>
86       <para>
87        The special sequence <literal>%db</literal> is replaced with
88        a single database while searching. Note that this sequence
89        is no longer needed, because the <literal>%query</literal> can already
90        query for a single database by using CQL query
91        <literal>udb==...</literal>.
92       </para>
93      </listitem>
94     </varlistentry>
95     <varlistentry>
96      <term>attribute <literal>content_url</literal></term>
97      <listitem>
98       <para>
99        URL of Web service to be used to fetch target profile
100        for a given database (udb) of type content. Semantics otherwise like
101        <literal>url</literal> attribute above.
102       </para>
103      </listitem>
104     </varlistentry>
105     <varlistentry>
106       <term>attribute <literal>realm</literal></term>
107       <listitem>
108         <para>
109          The default realm value. Used for %realm in URL, unless
110          specified in DATABASE argument.
111         </para>
112       </listitem>
113     </varlistentry>
114     <varlistentry>
115      <term>attribute <literal>proxy</literal></term>
116      <listitem>
117       <para>
118        HTTP proxy to bse used for fetching target profiles.
119       </para>
120      </listitem>
121     </varlistentry>
122     <varlistentry>
123      <term>attribute <literal>xsldir</literal></term>
124      <listitem>
125       <para>
126        Directory that is searched for XSL stylesheets. Stylesheets
127        are specified in the target profile by the
128        <literal>transform</literal> element.
129       </para>
130      </listitem>
131     </varlistentry>
132     <varlistentry>
133      <term>attribute <literal>element_transform</literal></term>
134      <listitem>
135       <para>
136        Specifies the element that triggers retrieval and transform using
137        the parameters elementSet, recordEncoding, requestSyntax, transform
138        from the target profile. Default value
139        is "pz2", due to the fact that for historical reasons the
140        common format is that used in Pazpar2.
141       </para>
142      </listitem>
143     </varlistentry>
144     <varlistentry>
145      <term>attribute <literal>element_raw</literal></term>
146      <listitem>
147       <para>
148        Specifies an element that triggers retrieval using the
149        parameters elementSet, recordEncoding, requestSyntax from the
150        target profile. Same actions as for element_transform, but without
151        the XSL transform. Useful for debugging.
152        The default value is "raw".
153       </para>
154      </listitem>
155     </varlistentry>
156     <varlistentry>
157      <term>attribute <literal>explain_xsl</literal></term>
158      <listitem>
159       <para>
160        Specifies a stylesheet that converts one or more Torus records
161        to ZeeExplain records. The content of recordData is assumed to be
162        holding each Explain record.
163       </para>
164      </listitem>
165     </varlistentry>
166     <varlistentry>
167      <term>attribute <literal>record_xsl</literal></term>
168      <listitem>
169       <para>
170        Specifies a stylesheet that converts retrieval records after
171        transform/literal operations.
172       </para>
173       <para>
174        When Metaproxy creates a content proxy session, the XSL parameter
175        <literal>cproxyhost</literal> is passed to the transform. 
176       </para>
177      </listitem>
178     </varlistentry>
179     <varlistentry>
180      <term>element <literal>records</literal></term>
181      <listitem>
182       <para>
183        Local target profiles. This element may includes zero or
184        more <literal>record</literal> elements (one per target
185        profile). See section TARGET PROFILE.
186       </para>
187      </listitem>
188     </varlistentry>
189    </variablelist>
190   </refsect2>
191   <refsect2 id="fieldmap">
192    <title>fieldmap</title>
193    <para>
194     The <literal>fieldmap</literal> may be specified zero or more times and
195     specifies the map from CQL fields to CCL fields and takes the
196     following content:
197    </para>
198    <variablelist>
199     <varlistentry>
200      <term>attribute <literal>cql</literal></term>
201      <listitem>
202       <para>
203        CQL field that we are mapping "from".
204       </para>
205      </listitem>
206     </varlistentry>
207     <varlistentry>
208      <term>attribute <literal>ccl</literal></term>
209      <listitem>
210       <para>
211        CCL field that we are mapping "to".
212       </para>
213      </listitem>
214     </varlistentry>
215    </variablelist>
216   </refsect2>
217   <refsect2 id="cclmap_base">
218    <title>cclmap</title>
219    <para>
220     The third part of the configuration consists of zero or more
221     <literal>cclmap</literal> elements that specifies
222     <emphasis>base</emphasis> CCL profile to be used for all targets.
223     This configuration, thus, will be combined with cclmap-definitions
224     from the target profile.
225    </para>
226   </refsect2>
227   <refsect2>
228    <title>contentProxy</title>
229    <para>
230     The <literal>contentProxy</literal> element controls content proxy'in.
231     This section
232     is optional and must only be defined if content proxy'ing is enabled.
233    </para>
234    <variablelist>
235     <varlistentry>
236      <term>attribute <literal>server</literal></term>
237      <listitem>
238       <para>
239        Specifies the content proxy host. The host is of the form
240        host[:port]. That is without a method (such as HTTP) and optional
241        port number.
242       </para>
243      </listitem>
244     </varlistentry>
245     <varlistentry>
246      <term>attribute <literal>tmp_file</literal></term>
247      <listitem>
248       <para>
249        Specifies a filename of a session file for content proxy'ing. The
250        file should be an absolute filename that includes
251        <literal>XXXXXX</literal> which is replaced by a unique filename
252        using the mkstemp(3) system call. The default value of this
253        setting is <literal>/tmp/cf.XXXXXX.p</literal>.
254       </para>
255      </listitem>
256     </varlistentry>
257    </variablelist>
258   </refsect2>
259   <refsect2>
260    <title>log</title>
261    <para>
262     The <literal>log</literal> element controls logging for the
263     ZOOM filter.
264    </para>
265    <variablelist>
266     <varlistentry>
267      <term>attribute <literal>apdu</literal></term>
268      <listitem>
269       <para>
270        If the value of apdu is "true", then protocol packages
271        (APDUs and HTTP packages) from the ZOOM filter will be
272        logged to the yaz_log system. A value of "false" will
273        not perform logging of protocol packages (the default
274        behavior).
275       </para>
276      </listitem>
277     </varlistentry>
278    </variablelist>
279   </refsect2>
280
281   <refsect2>
282    <title>zoom</title>
283    <para>
284     The <literal>zoom</literal> element controls settings for the
285     ZOOM.
286    </para>
287    <variablelist>
288     <varlistentry>
289      <term>attribute <literal>timeout</literal></term>
290      <listitem>
291       <para>
292        Is an integer that specifies, in seconds, how long an operation
293        may take before ZOOM gives up. Default value is 40.
294       </para>
295      </listitem>
296     </varlistentry>
297    </variablelist>
298   </refsect2>
299
300  </refsect1>
301  <refsect1>
302   <title>QUERY HANDLING</title>
303   <para>
304    The ZOOM filter accepts three query types: RPN(Type-1), CCL and
305    CQL.
306   </para>
307   <para>
308    Queries are converted in two separate steps. In the first step
309    the input query is converted to RPN/Type-1. This is always
310    the common internal format between step 1 and step 2.
311    In step 2 the query is converted to the native query type of the target.
312   </para>
313   <para>
314    Step 1: for RPN, the query is passed un-modified to the target.
315   </para>
316   <para>
317    Step 1: for CCL, the query is converted to RPN via
318    <link linkend="cclmap"><literal>cclmap</literal></link> elements part of
319    the target profile as well as 
320    <link linkend="cclmap_base">base CCL maps</link>.
321   </para>
322   <para>
323    Step 1: For CQL, the query is converted to CCL. The mappings of
324    CQL fields to CCL fields are handled by
325    <link linkend="fieldmap"><literal>fieldmap</literal></link>
326    elements as part of the target profile. The resulting query, CCL,
327    is the converted to RPN using the schema mentioned earlier (via
328    <literal>cclmap</literal>).
329   </para>
330   <para>
331    Step 2: If the target is Z39.50-based, it is passed verbatim (RPN).
332    If the target is SRU-based, the RPN will be converted to CQL.
333    If the target is SOLR-based, the RPN will be converted to SOLR's query
334    type.
335   </para>
336  </refsect1>
337  
338  <refsect1>
339   <title>SORTING</title>
340   <para>
341    The ZOOM module actively handle CQL sorting - using the SORTBY parameter
342    which was introduced in SRU version 1.2. The conversion from SORTBY clause
343    to native sort for some target is driven by the two parameters: 
344    <link linkend="sortStrategy"><literal>sortStrategy</literal></link>
345    and <link linkend="sortmap"><literal>sortmap_</literal><replaceable>field</replaceable></link>.
346   </para>
347   <para>
348    If a sort field that does not have an equivalent
349    <literal>sortmap_</literal>-mapping is passed un-modified through the
350    conversion. It doesn't throw a diagnostic.
351   </para>
352  </refsect1>
353  
354  <refsect1>
355   <title>TARGET PROFILE</title>
356   <para>
357    The ZOOM module is driven by a number of settings that specifies how
358    to handle each target.
359    Note that unknown elements are silently <emphasis>ignored</emphasis>.
360   </para>
361   <para>
362    The elements, in alphabetical order, are:
363   </para>
364   <variablelist>
365    <varlistentry>
366     <term id="zoom-torus-authentication">authentication</term><listitem>
367     <para>
368      Authentication parameters to be sent to the target. For
369      Z39.50 targets, this will be sent as part of the
370      Init Request. Authentication consists of two components: username
371      and password, separated by a slash.
372     </para>
373     <para>
374      If this value is omitted or empty no authentication information is sent.
375     </para>
376    </listitem>
377    </varlistentry>
378    
379    <varlistentry id="cclmap">
380     <term>cclmap_<replaceable>field</replaceable></term><listitem>
381     <para>
382      This value specifies CCL field (qualifier) definition for some
383      field. For Z39.50 targets this most likely will specify the
384      mapping to a numeric use attribute + a structure attribute.
385      For SRU targets, the use attribute should be string based, in
386      order to make the RPN to CQL conversion work properly (step 2).
387     </para>
388    </listitem>
389    </varlistentry>
390    
391    <varlistentry>
392     <term>cfAuth</term><listitem>
393     <para>
394      When cfAuth is defined, its value will be used as authentication
395      to backend target and authentication setting will be specified
396      as part of a database. This is like a "proxy" for authentication and
397      is used for Connector Framework based targets.
398     </para>
399    </listitem>
400    </varlistentry>
401
402    <varlistentry>
403     <term id="zoom-torus-cfproxy">cfProxy</term><listitem>
404     <para>
405      Specifies HTTP proxy for the target in the form
406      <replaceable>host</replaceable>:<replaceable>port</replaceable>.
407     </para>
408    </listitem>
409    </varlistentry>
410
411    <varlistentry>
412     <term>cfSubDB</term><listitem>
413     <para>
414      Specifies sub database for a Connector Framework based target.
415     </para>
416    </listitem>
417    </varlistentry>
418
419    <varlistentry id="zoom-torus-contentConnector">
420     <term>contentConnector</term><listitem>
421     <para>
422      Specifies a database for content-based proxy'ing.
423     </para>
424    </listitem>
425    </varlistentry>
426
427    <varlistentry>
428     <term>elementSet</term><listitem>
429     <para>
430      Specifies the elementSet to be sent to the target if record
431      transform is enabled (not to be confused' with the record_transform
432      module). The record transform is enabled only if the client uses
433      record syntax = XML and a element set determined by
434      the <literal>element_transform</literal> /
435      <literal>element_raw</literal> from the configuration.
436      By default that is the element sets <literal>pz2</literal>
437      and <literal>raw</literal>.
438      If record transform is not enabled, this setting is 
439      not used and the element set specified by the client
440      is passed verbatim.
441     </para>
442    </listitem>
443    </varlistentry>
444
445    <varlistentry>
446     <term>literalTransform</term><listitem>
447     <para>
448      Specifies a XSL stylesheet to be used if record
449      transform is anabled; see description of elementSet.
450      The XSL transform is only used if the element set is set to the
451      value of <literal>element_transform</literal> in the configuration.
452     </para>
453     <para>
454      The value of literalTransform is the XSL - string encoded.
455     </para>
456    </listitem>
457    </varlistentry>
458    
459    <varlistentry>
460     <term>piggyback</term><listitem>
461     <para>
462      A value of 1/true is a hint to the ZOOM module that this Z39.50
463      target supports piggyback searches, ie Search Response with
464      records. Any other value (false) will prevent the ZOOM module
465      to make use of piggyback (all records part of Present Response).
466     </para>
467    </listitem>
468    </varlistentry>
469    
470    <varlistentry>
471     <term>queryEncoding</term><listitem>
472     <para>
473      If this value is defined, all queries will be converted
474      to this encoding. This should be used for all Z39.50 targets that
475      do not use UTF-8 for query terms.
476     </para>
477    </listitem>
478    </varlistentry>
479    
480    <varlistentry>
481     <term>recordEncoding</term><listitem>
482     <para>
483      Specifies the character encoding of records that are returned
484      by the target. This is primarily used for targets were records
485      are not UTF-8 encoded already. This setting is only used
486      if the record transform is enabled (see description of elementSet).
487     </para>
488    </listitem>
489    </varlistentry>
490
491    <varlistentry>
492     <term>requestSyntax</term><listitem>
493     <para>
494      Specifies the record syntax to be specified for the target
495      if record transform is enabled; see description of elementSet.
496      If record transform is not enabled, the record syntax of the
497      client is passed verbatim to the target.
498     </para>
499    </listitem>
500    </varlistentry>
501
502    <varlistentry id="sortmap">
503     <term>sortmap_<replaceable>field</replaceable></term><listitem>
504     <para>
505      This value the native field for a target. The form of the value is
506      given by <link linkend="sortStrategy">sortStrategy</link>.
507     </para>
508    </listitem>
509    </varlistentry>
510    
511    <varlistentry id="sortStrategy">
512     <term>sortStrategy</term><listitem>
513     <para>
514      Specifies sort strategy for a target. One of:
515      <literal>z3950</literal>, <literal>type7</literal>,
516      <literal>cql</literal>, <literal>sru11</literal> or
517      <literal>embed</literal>. The <literal>embed</literal> chooses type-7
518      or CQL sortby depending on whether Type-1 or CQL is
519      actually sent to the target.
520     </para>
521    </listitem>
522    </varlistentry>
523    
524    <varlistentry>
525     <term>sru</term><listitem>
526     <para>
527      If this setting is set, it specifies that the target is web service
528      based and must be one of : <literal>get</literal>,
529      <literal>post</literal>, <literal>soap</literal>
530      or <literal>solr</literal>.
531     </para>
532    </listitem>
533    </varlistentry>
534
535    <varlistentry>
536     <term>sruVersion</term><listitem>
537     <para>
538      Specifies the SRU version to use. It unset, version 1.2 will be
539      used. Some servers do not support this version, in which case
540      version 1.1 or even 1.0 could be set it.
541     </para>
542    </listitem>
543    </varlistentry>
544
545    <varlistentry>
546     <term>transform</term><listitem>
547     <para>
548      Specifies a XSL stylesheet filename to be used if record
549      transform is anabled; see description of elementSet.
550      The XSL transform is only used if the element set is set to the
551      value of <literal>element_transform</literal> in the configuration.
552     </para>
553    </listitem>
554    </varlistentry>
555
556    <varlistentry>
557     <term>udb</term><listitem>
558     <para>
559      This value is required and specifies the unique database for
560      this profile . All target profiles should hold a unique database.
561     </para>
562    </listitem>
563    </varlistentry>
564
565    <varlistentry id="urlRecipe">
566     <term>urlRecipe</term><listitem>
567     <para>
568      The value of this field is a string that generates a dynamic link
569      based on record content. If the resulting string is non-zero in length
570      a new field, <literal>metadata</literal> with attribute 
571      <literal>type="generated-url"</literal> is generated.
572      The contents of this field is the result of the URL recipe conversion.
573      The urlRecipe value may refer to an existing metadata element by
574      ${field[pattern/result/flags]}, which will take content
575      of field and perform a regular expression conversion using the pattern
576      given. For example: <literal>${md-title[\s+/+/g]}</literal> takes
577      metadata element <literal>title</literal> and converts one or more
578      spaces to a plus character.
579     </para>
580    </listitem>
581    </varlistentry>
582    
583    <varlistentry>
584     <term>zurl</term><listitem>
585     <para>
586      This is setting is mandatory and specifies the ZURL of the
587      target in the form of host/database. The HTTP method should
588      not be provided as this is guessed from the "sru" attribute value.
589     </para>
590    </listitem>
591    </varlistentry>
592   </variablelist>
593  </refsect1>
594  <refsect1>
595   <title>DATABASE parameters</title>
596   <para>
597    Extra information may be carried in the Z39.50 Database or SRU path,
598    such as authentication to be passed to backend etc. Some of
599    the parameters override TARGET profile values. The format is
600   </para>
601   <para>
602    udb,parm1=value1&amp;parm2=value2&amp;...
603   </para>
604   <para>
605    Where udb is the unique database recognised by the backend and parm1,
606    value1, .. are parameters to be passed. The following describes the
607    supported parameters. Like form values in HTTP the parameters and
608    values are URL encoded. The separator, though, between udb and parameters
609    is a comma rather than a question mark. What follows question mark are
610    HTTP arguments (in this case SRU arguments).
611   </para>
612   <variablelist>  
613    <varlistentry>
614     <term>user</term>
615     <listitem>
616      <para>
617       Specifies user to be passed to backend. If this parameter is
618       omitted, the user will be taken from TARGET profile setting
619       <link linkend="zoom-torus-authentication">
620        <literal>authentication</literal>
621       </link>
622       .
623      </para>
624     </listitem>
625    </varlistentry>
626    <varlistentry>
627     <term>password</term>
628     <listitem>
629      <para>
630       Specifies password to be passed to backend. If this parameters is
631       omitted, the password will be taken from TARGET profile setting
632       <link linkend="zoom-torus-authentication">
633        <literal>authentication</literal>
634       </link>
635       .
636      </para>
637     </listitem>
638    </varlistentry>
639    <varlistentry>
640     <term>proxy</term>
641     <listitem>
642      <para>
643       Specifies one or more proxies for backend. If this parameter is
644       omitted, the proxy will be taken from TARGET profile setting
645       <link linkend="zoom-torus-cfproxy">
646        <literal>cfProxy</literal></link>.
647        The parameter is a list of  comma-separated  host:port entries.
648        Bost host and port must be given for each proxy.
649      </para>
650     </listitem>
651    </varlistentry>
652    <varlistentry>
653     <term>cproxysession</term>
654     <listitem>
655      <para>
656       Session ID for content proxy. This parameter is, generally,
657       not used by anything but the content proxy itself.
658      </para>
659     </listitem>
660    </varlistentry>
661    <varlistentry>
662     <term>nocproxy</term>
663     <listitem>
664      <para>
665       If this parameter is specified, content-proyxing is disabled
666       for the search.
667      </para>
668     </listitem>
669    </varlistentry>
670    <varlistentry>
671     <term>realm</term>
672     <listitem>
673      <para>
674       Session realm to be used for this target, changed the resulting
675       URL to be used for getting a target profile, by changing the
676       value that gets substituted for the %realm string.
677      </para>
678     </listitem>
679    </varlistentry>
680    <varlistentry>
681     <term>x-parm</term>
682     <listitem>
683      <para>
684       All parameters that has prefix x, dash are passed verbatim
685       to the backend.
686      </para>
687     </listitem>
688    </varlistentry>
689   </variablelist>  
690  </refsect1>
691  <refsect1>
692   <title>SCHEMA</title>
693   <literallayout><xi:include
694   xi:href="../xml/schema/filter_zoom.rnc"
695   xi:parse="text"  
696   xmlns:xi="http://www.w3.org/2001/XInclude" />
697   </literallayout>
698  </refsect1>
699  
700  <refsect1>
701   <title>EXAMPLES</title>
702   <para>
703    The following configuration illustrates most of the
704    facilities:
705    <screen><![CDATA[
706     <filter type="zoom">
707       <torus
708          url="http://torus.indexdata.com/src/records/?query=%query"
709          proxy="localhost:3128"
710          />
711       <fieldmap cql="cql.anywhere"/>
712       <fieldmap cql="cql.serverChoice"/>
713       <fieldmap cql="dc.creator" ccl="au"/>
714       <fieldmap cql="dc.title" ccl="ti"/>
715       <fieldmap cql="dc.subject" ccl="su"/>
716       
717       <cclmap>
718         <qual name="ocn">
719           <attr type="u" value="12"/>
720           <attr type="s" value="107"/>
721         </qual>
722       </cclmap>
723       <log apdu="true"/>
724       <zoom timeout="40"/>
725     </filter>
726 ]]>
727    </screen>
728   </para>
729   
730  </refsect1> 
731  
732  <refsect1>
733   <title>SEE ALSO</title>
734   <para>
735    <citerefentry>
736     <refentrytitle>metaproxy</refentrytitle>
737     <manvolnum>1</manvolnum>
738    </citerefentry>
739   </para>
740   <para>
741    <citerefentry>
742     <refentrytitle>virt_db</refentrytitle>
743     <manvolnum>3mp</manvolnum>
744    </citerefentry>
745   </para>
746  </refsect1>
747  
748  &copyright;
749 </refentry>
750
751 <!-- Keep this comment at the end of the file
752 Local variables:
753 mode: nxml
754 nxml-child-indent: 1
755 End:
756 -->