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