8797de14330dff3bfe33002dcc81d17c2974bb9b
[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 five parts: <literal>torus</literal>,
60    <literal>fieldmap</literal>, <literal>cclmap</literal>,
61    <literal>contentProxy</literal> and <literal>log</literal>.
62   </para>
63   <refsect2>
64    <title>torus</title>
65    <para>
66     The <literal>torus</literal> element specifies target profiles
67     and takes the following content:
68    </para>
69    <variablelist>
70     <varlistentry>
71      <term>attribute <literal>url</literal></term>
72      <listitem>
73       <para>
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.
78       </para>
79       <para>
80        The special sequence <literal>%realm</literal> is replaced by value
81        of attribute <literal>realm</literal> or by realm DATABASE argument.
82       </para>
83      </listitem>
84     </varlistentry>
85     <varlistentry>
86       <term>attribute <literal>realm</literal></term>
87       <listitem>
88         <para>
89          The default realm value. Used for %realm in URL, unless
90          specified in DATABASE argument.
91         </para>
92       </listitem>
93     </varlistentry>
94     <varlistentry>
95      <term>attribute <literal>proxy</literal></term>
96      <listitem>
97       <para>
98        HTTP proxy to bse used for fetching target profiles.
99       </para>
100      </listitem>
101     </varlistentry>
102     <varlistentry>
103      <term>attribute <literal>xsldir</literal></term>
104      <listitem>
105       <para>
106        Directory that is searched for XSL stylesheets. Stylesheets
107        are specified in the target profile by the
108        <literal>transform</literal> element.
109       </para>
110      </listitem>
111     </varlistentry>
112     <varlistentry>
113      <term>attribute <literal>element_transform</literal></term>
114      <listitem>
115       <para>
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.
121       </para>
122      </listitem>
123     </varlistentry>
124     <varlistentry>
125      <term>attribute <literal>element_raw</literal></term>
126      <listitem>
127       <para>
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".
133       </para>
134      </listitem>
135     </varlistentry>
136     <varlistentry>
137      <term>element <literal>records</literal></term>
138      <listitem>
139       <para>
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.
143       </para>
144      </listitem>
145     </varlistentry>
146    </variablelist>
147   </refsect2>
148   <refsect2 id="fieldmap">
149    <title>fieldmap</title>
150    <para>
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
153     following content:
154    </para>
155    <variablelist>
156     <varlistentry>
157      <term>attribute <literal>cql</literal></term>
158      <listitem>
159       <para>
160        CQL field that we are mapping "from".
161       </para>
162      </listitem>
163     </varlistentry>
164     <varlistentry>
165      <term>attribute <literal>ccl</literal></term>
166      <listitem>
167       <para>
168        CCL field that we are mapping "to".
169       </para>
170      </listitem>
171     </varlistentry>
172    </variablelist>
173   </refsect2>
174   <refsect2 id="cclmap_base">
175    <title>cclmap</title>
176    <para>
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.
182    </para>
183   </refsect2>
184   <refsect2>
185    <title>contentProxy</title>
186    <para>
187     The <literal>contentProxy</literal> element controls content proxy'in.
188     This section
189     is optional and must only be defined if content proxy'ing is enabled.
190    </para>
191    <variablelist>
192     <varlistentry>
193      <term>attribute <literal>server</literal></term>
194      <listitem>
195       <para>
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
198        port number.
199       </para>
200      </listitem>
201     </varlistentry>
202     <varlistentry>
203      <term>attribute <literal>tmp_file</literal></term>
204      <listitem>
205       <para>
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>.
211       </para>
212      </listitem>
213     </varlistentry>
214    </variablelist>
215   </refsect2>
216   <refsect2>
217    <title>log</title>
218    <para>
219     The <literal>log</literal> element controls logging for the
220     ZOOM filter.
221    </para>
222    <variablelist>
223     <varlistentry>
224      <term>attribute <literal>apdu</literal></term>
225      <listitem>
226       <para>
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
231        behavior).
232       </para>
233      </listitem>
234     </varlistentry>
235    </variablelist>
236   </refsect2>
237  </refsect1>
238  <refsect1>
239   <title>QUERY HANDLING</title>
240   <para>
241    The ZOOM filter accepts three query types: RPN(Type-1), CCL and
242    CQL.
243   </para>
244   <para>
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.
249   </para>
250   <para>
251    Step 1: for RPN, the query is passed un-modified to the target.
252   </para>
253   <para>
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>.
258   </para>
259   <para>
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>).
266   </para>
267   <para>
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
271    type.
272   </para>
273  </refsect1>
274  
275  <refsect1>
276   <title>SORTING</title>
277   <para>
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>.
283   </para>
284   <para>
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.
288   </para>
289  </refsect1>
290  
291  <refsect1>
292   <title>TARGET PROFILE</title>
293   <para>
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>.
297   </para>
298   <para>
299    The elements, in alphabetical order, are:
300   </para>
301   <variablelist>
302    <varlistentry>
303     <term id="zoom-torus-authentication">authentication</term><listitem>
304     <para>
305      Authentication parameters to be sent to the target. For
306      Z39.50 targets, this will be sent as part of the
307      Init Request. Authentication consists of two components: username
308      and password, separated by a slash.
309     </para>
310     <para>
311      If this value is omitted or empty no authentication information is sent.
312     </para>
313    </listitem>
314    </varlistentry>
315    
316    <varlistentry id="cclmap">
317     <term>cclmap_<replaceable>field</replaceable></term><listitem>
318     <para>
319      This value specifies CCL field (qualifier) definition for some
320      field. For Z39.50 targets this most likely will specify the
321      mapping to a numeric use attribute + a structure attribute.
322      For SRU targets, the use attribute should be string based, in
323      order to make the RPN to CQL conversion work properly (step 2).
324     </para>
325    </listitem>
326    </varlistentry>
327    
328    <varlistentry>
329     <term>cfAuth</term><listitem>
330     <para>
331      When cfAuth is defined, its value will be used as authentication
332      to backend target and authentication setting will be specified
333      as part of a database. This is like a "proxy" for authentication and
334      is used for Connector Framework based targets.
335     </para>
336    </listitem>
337    </varlistentry>
338
339    <varlistentry>
340     <term id="zoom-torus-cfproxy">cfProxy</term><listitem>
341     <para>
342      Specifies HTTP proxy for the target in the form
343      <replaceable>host</replaceable>:<replaceable>port</replaceable>.
344     </para>
345    </listitem>
346    </varlistentry>
347
348    <varlistentry>
349     <term>cfSubDB</term><listitem>
350     <para>
351      Specifies sub database for a Connector Framework based target.
352     </para>
353    </listitem>
354    </varlistentry>
355
356    <varlistentry id="zoom-torus-contentConnector">
357     <term>contentConnector</term><listitem>
358     <para>
359      Specifies a database for content-based proxy'ing.
360     </para>
361    </listitem>
362    </varlistentry>
363
364    <varlistentry>
365     <term>elementSet</term><listitem>
366     <para>
367      Specifies the elementSet to be sent to the target if record
368      transform is enabled (not to be confused' with the record_transform
369      module). The record transform is enabled only if the client uses
370      record syntax = XML and a element set determined by
371      the <literal>element_transform</literal> /
372      <literal>element_raw</literal> from the configuration.
373      By default that is the element sets <literal>pz2</literal>
374      and <literal>raw</literal>.
375      If record transform is not enabled, this setting is 
376      not used and the element set specified by the client
377      is passed verbatim.
378     </para>
379    </listitem>
380    </varlistentry>
381
382    <varlistentry>
383     <term>literalTransform</term><listitem>
384     <para>
385      Specifies a XSL stylesheet to be used if record
386      transform is anabled; see description of elementSet.
387      The XSL transform is only used if the element set is set to the
388      value of <literal>element_transform</literal> in the configuration.
389     </para>
390     <para>
391      The value of literalTransform is the XSL - string encoded.
392     </para>
393    </listitem>
394    </varlistentry>
395    
396    <varlistentry>
397     <term>piggyback</term><listitem>
398     <para>
399      A value of 1/true is a hint to the ZOOM module that this Z39.50
400      target supports piggyback searches, ie Search Response with
401      records. Any other value (false) will prevent the ZOOM module
402      to make use of piggyback (all records part of Present Response).
403     </para>
404    </listitem>
405    </varlistentry>
406    
407    <varlistentry>
408     <term>queryEncoding</term><listitem>
409     <para>
410      If this value is defined, all queries will be converted
411      to this encoding. This should be used for all Z39.50 targets that
412      do not use UTF-8 for query terms.
413     </para>
414    </listitem>
415    </varlistentry>
416    
417    <varlistentry>
418     <term>recordEncoding</term><listitem>
419     <para>
420      Specifies the character encoding of records that are returned
421      by the target. This is primarily used for targets were records
422      are not UTF-8 encoded already. This setting is only used
423      if the record transform is enabled (see description of elementSet).
424     </para>
425    </listitem>
426    </varlistentry>
427
428    <varlistentry>
429     <term>requestSyntax</term><listitem>
430     <para>
431      Specifies the record syntax to be specified for the target
432      if record transform is enabled; see description of elementSet.
433      If record transform is not enabled, the record syntax of the
434      client is passed verbatim to the target.
435     </para>
436    </listitem>
437    </varlistentry>
438
439    <varlistentry id="sortmap">
440     <term>sortmap_<replaceable>field</replaceable></term><listitem>
441     <para>
442      This value the native field for a target. The form of the value is
443      given by <link linkend="sortStrategy">sortStrategy</link>.
444     </para>
445    </listitem>
446    </varlistentry>
447    
448    <varlistentry id="sortStrategy">
449     <term>sortStrategy</term><listitem>
450     <para>
451      Specifies sort strategy for a target. One of:
452      <literal>z3950</literal>, <literal>type7</literal>,
453      <literal>cql</literal>, <literal>sru11</literal> or
454      <literal>embed</literal>. The <literal>embed</literal> chooses type-7
455      or CQL sortby depending on whether Type-1 or CQL is
456      actually sent to the target.
457     </para>
458    </listitem>
459    </varlistentry>
460    
461    <varlistentry>
462     <term>sru</term><listitem>
463     <para>
464      If this setting is set, it specifies that the target is web service
465      based and must be one of : <literal>get</literal>,
466      <literal>post</literal>, <literal>soap</literal>
467      or <literal>solr</literal>.
468     </para>
469    </listitem>
470    </varlistentry>
471
472    <varlistentry>
473     <term>transform</term><listitem>
474     <para>
475      Specifies a XSL stylesheet filename to be used if record
476      transform is anabled; see description of elementSet.
477      The XSL transform is only used if the element set is set to the
478      value of <literal>element_transform</literal> in the configuration.
479     </para>
480    </listitem>
481    </varlistentry>
482
483    <varlistentry>
484     <term>udb</term><listitem>
485     <para>
486      This value is required and specifies the unique database for
487      this profile . All target profiles should hold a unique database.
488     </para>
489    </listitem>
490    </varlistentry>
491
492    <varlistentry id="urlRecipe">
493     <term>urlRecipe</term><listitem>
494     <para>
495      The value of this field is a string that generates a dynamic link
496      based on record content. If the resulting string is non-zero in length
497      a new field, <literal>metadata</literal> with attribute 
498      <literal>type="generated-url"</literal>.
499      The contents of this field is the result of the URL recipe conversion.
500      The urlRecipe value may refer to an existing metadata element by
501      ${field[pattern/result/flags]}, which will take content
502      of field and perform a regular expression conversion using the pattern
503      given. For example: <literal>${md-title[\s+/+/g]}</literal> takes
504      metadadata element <literal>title</literal> and converts one or more
505      spaces to a plus character.
506     </para>
507     <para>
508      If the <link linkend="zoom-torus-contentConnector">contentConnector</link>
509      setting also defined, the resulting value is
510      augmented with a session string as well as the content proxy server.
511     </para>
512    </listitem>
513    </varlistentry>
514    
515    <varlistentry>
516     <term>zurl</term><listitem>
517     <para>
518      This is setting is mandatory and specifies the ZURL of the
519      target in the form of host/database. The HTTP method should
520      not be provided as this is guessed from the "sru" attribute value.
521     </para>
522    </listitem>
523    </varlistentry>
524   </variablelist>
525  </refsect1>
526  <refsect1>
527   <title>DATABASE parameters</title>
528   <para>
529    Extra information may be carried in the Z39.50 Database or SRU path,
530    such as authentication to be passed to backend etc. Some of
531    the parameters override TARGET profile values. The format is
532   </para>
533   <para>
534    udb,parm1=value1&amp;parm2=value2&amp;...
535   </para>
536   <para>
537    Where udb is the unique database recognised by the backend and parm1,
538    value1, .. are parameters to be passed. The following describes the
539    supported parameters. Like form values in HTTP the parameters and
540    values are URL encoded. The separator, though, between udb and parameters
541    is a comma rather than a question mark. What follows question mark are
542    HTTP arguments (in this case SRU arguments).
543   </para>
544   <variablelist>  
545    <varlistentry>
546     <term>user</term>
547     <listitem>
548      <para>
549       Specifies user to be passed to backend. If this parameter is
550       omitted, the user will be taken from TARGET profile setting
551       <link linkend="zoom-torus-authentication">
552        <literal>authentication</literal>
553       </link>
554       .
555      </para>
556     </listitem>
557    </varlistentry>
558    <varlistentry>
559     <term>password</term>
560     <listitem>
561      <para>
562       Specifies password to be passed to backend. If this parameters is
563       omitted, the password will be taken from TARGET profile setting
564       <link linkend="zoom-torus-authentication">
565        <literal>authentication</literal>
566       </link>
567       .
568      </para>
569     </listitem>
570    </varlistentry>
571    <varlistentry>
572     <term>proxy</term>
573     <listitem>
574      <para>
575       Specifies proxy to be for backend. If this parameters is
576       omitted, the proxy will be taken from TARGET profile setting
577       <link linkend="zoom-torus-cfproxy">
578        <literal>cfProxy</literal>
579       </link>
580       .
581      </para>
582     </listitem>
583    </varlistentry>
584    <varlistentry>
585     <term>cproxysession</term>
586     <listitem>
587      <para>
588       Session ID for content proxy. This parameter is, generally,
589       not used by anything but the content proxy itself.
590      </para>
591     </listitem>
592    </varlistentry>
593    <varlistentry>
594     <term>realm</term>
595     <listitem>
596      <para>
597       Session realm to be used for this target, changed the resulting
598       URL to be used for getting a target profile, by changing the
599       value that gets substituted for the %realm string.
600      </para>
601     </listitem>
602    </varlistentry>
603    <varlistentry>
604     <term>x-parm</term>
605     <listitem>
606      <para>
607       All parameters that has prefix x, dash are passed verbatim
608       to the backend.
609      </para>
610     </listitem>
611    </varlistentry>
612   </variablelist>  
613  </refsect1>
614  <refsect1>
615   <title>SCHEMA</title>
616   <literallayout><xi:include
617   xi:href="../xml/schema/filter_zoom.rnc"
618   xi:parse="text"  
619   xmlns:xi="http://www.w3.org/2001/XInclude" />
620   </literallayout>
621  </refsect1>
622  
623  <refsect1>
624   <title>EXAMPLES</title>
625   <para>
626    The following configuration illustrates most of the
627    facilities:
628    <screen><![CDATA[
629     <filter type="zoom">
630       <torus
631          url="http://torus.indexdata.com/src/records/?query=udb%3D%db"
632          proxy="localhost:3128"
633          />
634       <fieldmap cql="cql.anywhere"/>
635       <fieldmap cql="cql.serverChoice"/>
636       <fieldmap cql="dc.creator" ccl="au"/>
637       <fieldmap cql="dc.title" ccl="ti"/>
638       <fieldmap cql="dc.subject" ccl="su"/>
639       
640       <cclmap>
641         <qual name="ocn">
642           <attr type="u" value="12"/>
643           <attr type="s" value="107"/>
644         </qual>
645       </cclmap>
646       <log apdu="true"/>
647     </filter>
648 ]]>
649    </screen>
650   </para>
651   
652  </refsect1> 
653  
654  <refsect1>
655   <title>SEE ALSO</title>
656   <para>
657    <citerefentry>
658     <refentrytitle>metaproxy</refentrytitle>
659     <manvolnum>1</manvolnum>
660    </citerefentry>
661   </para>
662   <para>
663    <citerefentry>
664     <refentrytitle>virt_db</refentrytitle>
665     <manvolnum>3mp</manvolnum>
666    </citerefentry>
667   </para>
668  </refsect1>
669  
670  &copyright;
671 </refentry>
672
673 <!-- Keep this comment at the end of the file
674 Local variables:
675 mode: nxml
676 nxml-child-indent: 1
677 End:
678 -->