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 four parts: <literal>torus</literal>,
  60    <literal>fieldmap</literal>, <literal>cclmap</literal>
  61    and <literal>log</literal>.
  62   </para>
  63   <refsect2><title>torus</title>
  64   <para>
  65    The <literal>torus</literal> element specifies target profiles
  66    and takes the following content:
  67   </para>
  68   <variablelist>
  69    <varlistentry>
  70     <term>attribute <literal>url</literal></term>
  71     <listitem>
  72      <para>
  73       URL of Web service to be used to fetch target profile
  74       for a given database (udb). The special sequence
  75       <literal>%db</literal> of the URL is replaced by the
  76       actual database specified as part of Search.
  77      </para>
  78     </listitem>
  79    </varlistentry>
  80    <varlistentry>
  81     <term>attribute <literal>proxy</literal></term>
  82     <listitem>
  83      <para>
  84       HTTP proxy to bse used for fetching target profiles.
  85      </para>
  86     </listitem>
  87    </varlistentry>
  88    <varlistentry>
  89     <term>attribute <literal>xsldir</literal></term>
  90     <listitem>
  91      <para>
  92       Directory that is searched for XSL stylesheets. Stylesheets
  93       are specified in the target profile by the
  94       <literal>transform</literal> element.
  95      </para>
  96     </listitem>
  97    </varlistentry>
  98    <varlistentry>
  99     <term>attribute <literal>element_transform</literal></term>
 100     <listitem>
 101      <para>
 102       Specifies the element that triggers retrieval and transform using
 103       the parameters elementSet, recordEncoding, requestSyntax, transform
 104       from the target profile. Default value
 105       is "pz2", due to the fact that for historical reasons the
 106       common format is that used in Pazpar2.
 107      </para>
 108     </listitem>
 109    </varlistentry>
 110    <varlistentry>
 111     <term>attribute <literal>element_raw</literal></term>
 112     <listitem>
 113      <para>
 114       Specifies an element that triggers retrieval using the
 115       parameters elementSet, recordEncoding, requestSyntax from the
 116       target profile. Same actions as for element_transform, but without
 117       the XSL transform. Useful for debugging.
 118       The default value is "raw".
 119      </para>
 120     </listitem>
 121    </varlistentry>
 122    <varlistentry>
 123     <term>element <literal>records</literal></term>
 124     <listitem>
 125      <para>
 126       Local target profiles. This element may includes zero or
 127       more <literal>record</literal> elements (one per target
 128       profile). See section TARGET PROFILE.
 129      </para>
 130     </listitem>
 131    </varlistentry>
 132   </variablelist>
 133   </refsect2>
 134   <refsect2>
 135    <title>fieldmap</title>
 136    <para>
 137     The <literal>fieldmap</literal> may be specified zero or more times and
 138     specifies the map from CQL fields to CCL fields and takes the
 139     following content:
 140    </para>
 141    <variablelist>
 142     <varlistentry>
 143      <term>attribute <literal>cql</literal></term>
 144      <listitem>
 145       <para>
 146        CQL field that we are mapping "from".
 147       </para>
 148      </listitem>
 149     </varlistentry>
 150     <varlistentry>
 151      <term>attribute <literal>ccl</literal></term>
 152      <listitem>
 153       <para>
 154        CCL field that we are mapping "to".
 155       </para>
 156      </listitem>
 157     </varlistentry>
 158    </variablelist>
 159   </refsect2>
 160   <refsect2>
 161    <title>cclmap</title>
 162    <para>
 163     The third part of the configuration consists of zero or more
 164     <literal>cclmap</literal> elements that specifies
 165     <emphasis>base</emphasis> CCL profile to be used for all targets.
 166     This configuration, thus, will be combined with cclmap-definitions
 167     from the target profile.
 168    </para>
 169    </refsect2>
 170    <refsect2>
 171     <title>log</title>
 172     <para>
 173      The <literal>log</literal> element controls logging for the
 174      ZOOM filter.
 175     </para>
 176     <variablelist>
 177      <varlistentry>
 178       <term>attribute <literal>apdu</literal></term>
 179       <listitem>
 180        <para>
 181         If the value of apdu is "true", then protocol packages
 182         (APDUs and HTTP packages) from the ZOOM filter will be
 183         logged to the yaz_log system. A value of "false" will
 184         not perform logging of protocol packages (the default
 185         behavior).
 186        </para>
 187       </listitem>
 188      </varlistentry>
 189     </variablelist>
 190    </refsect2>
 191  </refsect1>
 192  <refsect1>
 193   <title>QUERY HANDLING</title>
 194   <para>
 195    The ZOOM filter accepts three query types: RPN(Type-1), CCL and
 196    CQL.
 197   </para>
 198   <para>
 199    Queries are converted in two separate steps. In the first step
 200    the input query is converted to RPN/Type-1. This is always
 201    the common internal format between step 1 and step 2.
 202    In step 2 the query is converted to the native query type of the target.
 203   </para>
 204   <para>
 205    Step 1: for RPN, the query is passed unmodified to the target.
 206   </para>
 207   <para>
 208    Step 1: for CCL, the query is converted to RPN via
 209    <literal>cclmap</literal> elements part of the target profile.
 210   </para>
 211   <para>
 212    Step 1: For CQL, the query is converted to CCL. The mappings of
 213    CQL fields to CCL fields are handled by <literal>fieldmap</literal>
 214    elements as part of the target profile. The resulting query, CCL,
 215    is the converted to RPN using the schema mentioned earlier (via
 216    <literal>cclmap</literal>).
 217   </para>
 218   <para>
 219    Step 2: If the target is Z39.50-based, it is passed verbatim (RPN).
 220    If the target is SRU-based, the RPN will be converted to CQL.
 221    If the target is SOLR-based, the RPN will be converted to SOLR's query
 222    type.
 223   </para>
 224  </refsect1>
 225
 226  <refsect1>
 227   <title>SORTING</title>
 228   <para>
 229
 230   </para>
 231  </refsect1>
 232
 233  <refsect1>
 234   <title>TARGET PROFILE</title>
 235   <para>
 236    The following elements are honored by the ZOOM module of Metaproxy.
 237    Note that unknown elements are silently ignored. There are several
 238    elements in use that makes no sense to the ZOOM module.
 239   </para>
 240   <variablelist>
 241    <varlistentry>
 242     <term>authentication</term><listitem>
 243     <para>
 244      Authentication parameters to be sent to the target. For
 245      Z39.50 targets, this will be sent as part of the
 246      Init Request.
 247     </para>
 248     <para>
 249      If this value is omitted or empty, not authentication information
 250      is simply omitted.
 251     </para>
 252    </listitem>
 253    </varlistentry>
 254
 255    <varlistentry>
 256     <term>piggyback</term><listitem>
 257     <para>
 258      A value of 1/true is a hint to the ZOOM module that this Z39.50
 259      target supports piggyback searches, ie Search Response with
 260      records. Any other value (false) will prevent the ZOOM module
 261      to make use of piggyback (all records part of Present Response).
 262     </para>
 263    </listitem>
 264    </varlistentry>
 265
 266    <varlistentry>
 267     <term>queryEncoding</term><listitem>
 268     <para>
 269      If this value is defined, all queries will be converted
 270      to this encoding. This should be used for all Z39.50 targets that
 271      do not use UTF-8 for query terms.
 272     </para>
 273    </listitem>
 274    </varlistentry>
 275
 276    <varlistentry>
 277     <term>udb</term><listitem>
 278     <para>
 279      This value is required and specifies the unique database for
 280      this profile . All target profiles should hold a unique database.
 281     </para>
 282    </listitem>
 283    </varlistentry>
 284
 285    <varlistentry>
 286     <term>cclmap_*</term><listitem>
 287     <para>
 288      This value specifies CCL field (qualifier) definition for some
 289      field. For Z39.50 targets this most likely will specify the
 290      mapping to a numeric use attribute + a structure attribute.
 291      For SRU targets, the use attribute should be string based, in
 292      order to make the RPN to CQL conversion work properly (step 2).
 293     </para>
 294    </listitem>
 295    </varlistentry>
 296
 297    <varlistentry>
 298     <term>elementSet</term><listitem>
 299     <para>
 300      Specifies the elementSet to be sent to the target if record
 301      transform is enabled (not to be confused' with the record_transform
 302      module). The record transform is enabled only if the client uses
 303      record syntax = XML and a element set determined by
 304      the <literal>element_transform</literal> /
 305      <literal>element_raw</literal> from the configuration.
 306      By default that is the element sets <literal>pz2</literal>
 307      and <literal>raw</literal>.
 308      If record transform is not enabled, this setting is
 309      not used and the element set specified by the client
 310      is passed verbatim.
 311     </para>
 312    </listitem>
 313    </varlistentry>
 314
 315    <varlistentry>
 316     <term>recordEncoding</term><listitem>
 317     <para>
 318      Specifies the character encoding of records that are returned
 319      by the target. This is primarily used for targets were records
 320      are not UTF-8 encoded already. This setting is only used
 321      if the record transform is enabled (see description of elementSet).
 322     </para>
 323    </listitem>
 324    </varlistentry>
 325
 326    <varlistentry>
 327     <term>requestSyntax</term><listitem>
 328     <para>
 329      Specifies the record syntax to be specified for the target
 330      if record transform is enabled; see description of elementSet.
 331      If record transform is not enabled, the record syntax of the
 332      client is passed verbatim to the target.
 333     </para>
 334    </listitem>
 335    </varlistentry>
 336
 337    <varlistentry>
 338     <term>sru</term><listitem>
 339     <para>
 340      If this setting is set, it specifies that the target is web service
 341      based and must be one of : <literal>get</literal>,
 342      <literal>post</literal>, <literal>soap</literal>
 343      or <literal>solr</literal>.
 344     </para>
 345    </listitem>
 346    </varlistentry>
 347
 348    <varlistentry>
 349     <term>transform</term><listitem>
 350     <para>
 351      Specifies a XSL stylesheet filename to be used if record
 352      transform is anabled; see desciprion of elementSet.
 353      The XSL transform is only used if the element set is set to the
 354      value of <literal>element_transform</literal> in the configuration.
 355     </para>
 356    </listitem>
 357    </varlistentry>
 358
 359    <varlistentry>
 360     <term>zurl</term><listitem>
 361     <para>
 362      This is setting is mandatory and specifies the ZURL of the
 363      target in the form of host/database. The HTTP method should
 364      not be provide as this is guessed from the "sru" attribute value.
 365     </para>
 366    </listitem>
 367    </varlistentry>
 368   </variablelist>
 369  </refsect1>
 370  <refsect1>
 371   <title>SCHEMA</title>
 372   <literallayout><xi:include
 373   xi:href="../xml/schema/filter_zoom.rnc"
 374   xi:parse="text"
 375   xmlns:xi="http://www.w3.org/2001/XInclude" />
 376   </literallayout>
 377  </refsect1>
 378
 379  <refsect1>
 380   <title>EXAMPLES</title>
 381   <para>
 382    The following configuration illustrates most of the
 383    facilities:
 384    <screen><![CDATA[
 385     <filter type="zoom">
 386       <torus
 387          url="http://torus.indexdata.com/src/records/?query=udb%3D%db"
 388          proxy="localhost:3128"
 389          />
 390       <fieldmap cql="cql.anywhere"/>
 391       <fieldmap cql="cql.serverChoice"/>
 392       <fieldmap cql="dc.creator" ccl="au"/>
 393       <fieldmap cql="dc.title" ccl="ti"/>
 394       <fieldmap cql="dc.subject" ccl="su"/>
 395
 396       <cclmap>
 397         <qual name="ocn">
 398           <attr type="u" value="12"/>
 399           <attr type="s" value="107"/>
 400         </qual>
 401       </cclmap>
 402       <log apdu="true"/>
 403     </filter>
 404 ]]>
 405    </screen>
 406   </para>
 407
 408  </refsect1>
 409
 410  <refsect1>
 411   <title>SEE ALSO</title>
 412   <para>
 413    <citerefentry>
 414     <refentrytitle>metaproxy</refentrytitle>
 415     <manvolnum>1</manvolnum>
 416    </citerefentry>
 417   </para>
 418   <para>
 419    <citerefentry>
 420     <refentrytitle>virt_db</refentrytitle>
 421     <manvolnum>3mp</manvolnum>
 422    </citerefentry>
 423   </para>
 424  </refsect1>
 425
 426  &copyright;
 427 </refentry>
 428
 429 <!-- Keep this comment at the end of the file
 430 Local variables:
 431 mode: nxml
 432 nxml-child-indent: 1
 433 End:
 434 -->