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>TARGET PROFILE</title>
 221    <para>
 222      The following elements are honored by the ZOOM module of Metaproxy.
 223      Note that unknown elements are silently ignored. There are several
 224      elements in use that makes no sense to the ZOOM module.
 225    </para>
 226    <variablelist>
 227      <varlistentry>
 228        <term>authentication</term><listitem>
 229          <para>
 230            Authentication parameters to be sent to the target. For
 231            Z39.50 targets, this will be sent as part of the
 232            Init Request.
 233          </para>
 234          <para>
 235            If this value is omitted or empty, not authentication information
 236            is simply omitted.
 237          </para>
 238        </listitem>
 239      </varlistentry>
 240
 241      <varlistentry>
 242        <term>piggyback</term><listitem>
 243          <para>
 244            A value of 1/true is a hint to the ZOOM module that this Z39.50
 245            target supports piggyback searches, ie Search Response with
 246            records. Any other value (false) will prevent the ZOOM module
 247            to make use of piggyback (all records part of Present Response).
 248          </para>
 249        </listitem>
 250      </varlistentry>
 251
 252      <varlistentry>
 253        <term>queryEncoding</term><listitem>
 254          <para>
 255            If this value is defined, all queries will be converted
 256            to this encoding. This should be used for all Z39.50 targets that
 257            do not use UTF-8 for query terms.
 258          </para>
 259        </listitem>
 260      </varlistentry>
 261
 262      <varlistentry>
 263        <term>udb</term><listitem>
 264          <para>
 265            This value is required and specifies the unique database for
 266            this profile . All target profiles should hold a unique database.
 267          </para>
 268        </listitem>
 269      </varlistentry>
 270
 271      <varlistentry>
 272        <term>cclmap_*</term><listitem>
 273          <para>
 274            This value specifies CCL field (qualifier) definition for some
 275            field. For Z39.50 targets this most likely will specify the
 276            mapping to a numeric use attribute + a structure attribute.
 277            For SRU targets, the use attribute should be string based, in
 278            order to make the RPN to CQL conversion work properly (step 2).
 279          </para>
 280        </listitem>
 281      </varlistentry>
 282
 283      <varlistentry>
 284        <term>elementSet</term><listitem>
 285          <para>
 286            Specifies the elementSet to be sent to the target if record
 287            transform is enabled (not to be confused' with the record_transform
 288            module). The record transform is enabled only if the client uses
 289            record syntax = XML and a element set determined by
 290            the <literal>element_transform</literal> /
 291            <literal>element_raw</literal> from the configuration.
 292            By default that is the element sets <literal>pz2</literal>
 293            and <literal>raw</literal>.
 294            If record transform is not enabled, this setting is
 295            not used and the element set specified by the client
 296            is passed verbatim.
 297          </para>
 298        </listitem>
 299      </varlistentry>
 300
 301      <varlistentry>
 302        <term>recordEncoding</term><listitem>
 303          <para>
 304            Specifies the character encoding of records that are returned
 305            by the target. This is primarily used for targets were records
 306            are not UTF-8 encoded already. This setting is only used
 307            if the record transform is enabled (see description of elementSet).
 308          </para>
 309        </listitem>
 310      </varlistentry>
 311
 312      <varlistentry>
 313        <term>requestSyntax</term><listitem>
 314          <para>
 315            Specifies the record syntax to be specified for the target
 316            if record transform is enabled; see description of elementSet.
 317            If record transform is not enabled, the record syntax of the
 318            client is passed verbatim to the target.
 319          </para>
 320        </listitem>
 321      </varlistentry>
 322
 323      <varlistentry>
 324        <term>sru</term><listitem>
 325          <para>
 326            If this setting is set, it specifies that the target is web service
 327            based and must be one of : <literal>get</literal>,
 328            <literal>post</literal>, <literal>soap</literal>
 329            or <literal>solr</literal>.
 330          </para>
 331        </listitem>
 332      </varlistentry>
 333
 334      <varlistentry>
 335        <term>transform</term><listitem>
 336          <para>
 337            Specifies a XSL stylesheet filename to be used if record
 338            transform is anabled; see desciprion of elementSet.
 339            The XSL transform is only used if the element set is set to the
 340            value of <literal>element_transform</literal> in the configuration.
 341          </para>
 342        </listitem>
 343      </varlistentry>
 344
 345      <varlistentry>
 346        <term>zurl</term><listitem>
 347          <para>
 348            This is setting is mandatory and specifies the ZURL of the
 349            target in the form of host/database. The HTTP method should
 350            not be provide as this is guessed from the "sru" attribute value.
 351          </para>
 352        </listitem>
 353      </varlistentry>
 354    </variablelist>
 355  </refsect1>
 356  <refsect1><title>SCHEMA</title>
 357    <literallayout><xi:include
 358                      xi:href="../xml/schema/filter_zoom.rnc"
 359                      xi:parse="text"
 360                      xmlns:xi="http://www.w3.org/2001/XInclude" />
 361    </literallayout>
 362  </refsect1>
 363
 364  <refsect1><title>EXAMPLES</title>
 365   <para>
 366    The following configuration illustrates most of the
 367    facilities:
 368    <screen><![CDATA[
 369     <filter type="zoom">
 370       <torus
 371          url="http://torus.indexdata.com/src/records/?query=udb%3D%db"
 372          proxy="localhost:3128"
 373          />
 374       <fieldmap cql="cql.anywhere"/>
 375       <fieldmap cql="cql.serverChoice"/>
 376       <fieldmap cql="dc.creator" ccl="au"/>
 377       <fieldmap cql="dc.title" ccl="ti"/>
 378       <fieldmap cql="dc.subject" ccl="su"/>
 379
 380       <cclmap>
 381         <qual name="ocn">
 382           <attr type="u" value="12"/>
 383           <attr type="s" value="107"/>
 384         </qual>
 385       </cclmap>
 386       <log apdu="true"/>
 387     </filter>
 388 ]]>
 389    </screen>
 390   </para>
 391
 392  </refsect1>
 393
 394  <refsect1><title>SEE ALSO</title>
 395   <para>
 396    <citerefentry>
 397     <refentrytitle>metaproxy</refentrytitle>
 398     <manvolnum>1</manvolnum>
 399    </citerefentry>
 400   </para>
 401   <para>
 402    <citerefentry>
 403     <refentrytitle>virt_db</refentrytitle>
 404     <manvolnum>3mp</manvolnum>
 405    </citerefentry>
 406   </para>
 407  </refsect1>
 408
 409  &copyright;
 410 </refentry>
 411
 412 <!-- Keep this comment at the end of the file
 413 Local variables:
 414 mode: sgml
 415 sgml-omittag:t
 416 sgml-shorttag:t
 417 sgml-minimize-attributes:nil
 418 sgml-always-quote-attributes:t
 419 sgml-indent-step:1
 420 sgml-indent-data:t
 421 sgml-parent-document:nil
 422 sgml-local-catalogs: nil
 423 sgml-namecase-general:t
 424 End:
 425 -->