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      </listitem>
  80     </varlistentry>
  81     <varlistentry>
  82      <term>attribute <literal>proxy</literal></term>
  83      <listitem>
  84       <para>
  85        HTTP proxy to bse used for fetching target profiles.
  86       </para>
  87      </listitem>
  88     </varlistentry>
  89     <varlistentry>
  90      <term>attribute <literal>xsldir</literal></term>
  91      <listitem>
  92       <para>
  93        Directory that is searched for XSL stylesheets. Stylesheets
  94        are specified in the target profile by the
  95        <literal>transform</literal> element.
  96       </para>
  97      </listitem>
  98     </varlistentry>
  99     <varlistentry>
 100      <term>attribute <literal>element_transform</literal></term>
 101      <listitem>
 102       <para>
 103        Specifies the element that triggers retrieval and transform using
 104        the parameters elementSet, recordEncoding, requestSyntax, transform
 105        from the target profile. Default value
 106        is "pz2", due to the fact that for historical reasons the
 107        common format is that used in Pazpar2.
 108       </para>
 109      </listitem>
 110     </varlistentry>
 111     <varlistentry>
 112      <term>attribute <literal>element_raw</literal></term>
 113      <listitem>
 114       <para>
 115        Specifies an element that triggers retrieval using the
 116        parameters elementSet, recordEncoding, requestSyntax from the
 117        target profile. Same actions as for element_transform, but without
 118        the XSL transform. Useful for debugging.
 119        The default value is "raw".
 120       </para>
 121      </listitem>
 122     </varlistentry>
 123     <varlistentry>
 124      <term>element <literal>records</literal></term>
 125      <listitem>
 126       <para>
 127        Local target profiles. This element may includes zero or
 128        more <literal>record</literal> elements (one per target
 129        profile). See section TARGET PROFILE.
 130       </para>
 131      </listitem>
 132     </varlistentry>
 133    </variablelist>
 134   </refsect2>
 135   <refsect2 id="fieldmap">
 136    <title>fieldmap</title>
 137    <para>
 138     The <literal>fieldmap</literal> may be specified zero or more times and
 139     specifies the map from CQL fields to CCL fields and takes the
 140     following content:
 141    </para>
 142    <variablelist>
 143     <varlistentry>
 144      <term>attribute <literal>cql</literal></term>
 145      <listitem>
 146       <para>
 147        CQL field that we are mapping "from".
 148       </para>
 149      </listitem>
 150     </varlistentry>
 151     <varlistentry>
 152      <term>attribute <literal>ccl</literal></term>
 153      <listitem>
 154       <para>
 155        CCL field that we are mapping "to".
 156       </para>
 157      </listitem>
 158     </varlistentry>
 159    </variablelist>
 160   </refsect2>
 161   <refsect2 id="cclmap_base">
 162    <title>cclmap</title>
 163    <para>
 164     The third part of the configuration consists of zero or more
 165     <literal>cclmap</literal> elements that specifies
 166     <emphasis>base</emphasis> CCL profile to be used for all targets.
 167     This configuration, thus, will be combined with cclmap-definitions
 168     from the target profile.
 169    </para>
 170   </refsect2>
 171   <refsect2>
 172    <title>contentProxy</title>
 173    <para>
 174     The <literal>contentProxy</literal> element controls content proxy'in.
 175     This section
 176     is optional and must only be defined if content proxy'ing is enabled.
 177    </para>
 178    <variablelist>
 179     <varlistentry>
 180      <term>attribute <literal>server</literal></term>
 181      <listitem>
 182       <para>
 183        Specifies the content proxy host. The host is of the form
 184        host[:port]. That is without a method (such as HTTP) and optional
 185        port number.
 186       </para>
 187      </listitem>
 188     </varlistentry>
 189     <varlistentry>
 190      <term>attribute <literal>tmp_file</literal></term>
 191      <listitem>
 192       <para>
 193        Specifies a filename of a session file for content proxy'ing. The
 194        file should be an absolute filename that includes
 195        <literal>XXXXXX</literal> which is replaced by a unique filename
 196        using the mkstemp(3) system call. The default value of this
 197        setting is <literal>/tmp/cf.XXXXXX.p</literal>.
 198       </para>
 199      </listitem>
 200     </varlistentry>
 201    </variablelist>
 202   </refsect2>
 203   <refsect2>
 204    <title>log</title>
 205    <para>
 206     The <literal>log</literal> element controls logging for the
 207     ZOOM filter.
 208    </para>
 209    <variablelist>
 210     <varlistentry>
 211      <term>attribute <literal>apdu</literal></term>
 212      <listitem>
 213       <para>
 214        If the value of apdu is "true", then protocol packages
 215        (APDUs and HTTP packages) from the ZOOM filter will be
 216        logged to the yaz_log system. A value of "false" will
 217        not perform logging of protocol packages (the default
 218        behavior).
 219       </para>
 220      </listitem>
 221     </varlistentry>
 222    </variablelist>
 223   </refsect2>
 224  </refsect1>
 225  <refsect1>
 226   <title>QUERY HANDLING</title>
 227   <para>
 228    The ZOOM filter accepts three query types: RPN(Type-1), CCL and
 229    CQL.
 230   </para>
 231   <para>
 232    Queries are converted in two separate steps. In the first step
 233    the input query is converted to RPN/Type-1. This is always
 234    the common internal format between step 1 and step 2.
 235    In step 2 the query is converted to the native query type of the target.
 236   </para>
 237   <para>
 238    Step 1: for RPN, the query is passed un-modified to the target.
 239   </para>
 240   <para>
 241    Step 1: for CCL, the query is converted to RPN via
 242    <link linkend="cclmap"><literal>cclmap</literal></link> elements part of
 243    the target profile as well as
 244    <link linkend="cclmap_base">base CCL maps</link>.
 245   </para>
 246   <para>
 247    Step 1: For CQL, the query is converted to CCL. The mappings of
 248    CQL fields to CCL fields are handled by
 249    <link linkend="fieldmap"><literal>fieldmap</literal></link>
 250    elements as part of the target profile. The resulting query, CCL,
 251    is the converted to RPN using the schema mentioned earlier (via
 252    <literal>cclmap</literal>).
 253   </para>
 254   <para>
 255    Step 2: If the target is Z39.50-based, it is passed verbatim (RPN).
 256    If the target is SRU-based, the RPN will be converted to CQL.
 257    If the target is SOLR-based, the RPN will be converted to SOLR's query
 258    type.
 259   </para>
 260  </refsect1>
 261
 262  <refsect1>
 263   <title>SORTING</title>
 264   <para>
 265    The ZOOM module actively handle CQL sorting - using the SORTBY parameter
 266    which was introduced in SRU version 1.2. The conversion from SORTBY clause
 267    to native sort for some target is driven by the two parameters:
 268    <link linkend="sortStrategy"><literal>sortStrategy</literal></link>
 269    and <link linkend="sortmap"><literal>sortmap_</literal><replaceable>field</replaceable></link>.
 270   </para>
 271   <para>
 272    If a sort field that does not have an equivalent
 273    <literal>sortmap_</literal>-mapping is passed un-modified through the
 274    conversion. It doesn't throw a diagnostic.
 275   </para>
 276  </refsect1>
 277
 278  <refsect1>
 279   <title>TARGET PROFILE</title>
 280   <para>
 281    The ZOOM module is driven by a number of settings that specifies how
 282    to handle each target.
 283    Note that unknown elements are silently <emphasis>ignored</emphasis>.
 284   </para>
 285   <para>
 286    The elements, in alphabetical order, are:
 287   </para>
 288   <variablelist>
 289    <varlistentry>
 290     <term>authentication</term><listitem>
 291     <para>
 292      Authentication parameters to be sent to the target. For
 293      Z39.50 targets, this will be sent as part of the
 294      Init Request.
 295     </para>
 296     <para>
 297      If this value is omitted or empty no authentication information is sent.
 298     </para>
 299    </listitem>
 300    </varlistentry>
 301
 302    <varlistentry id="cclmap">
 303     <term>cclmap_<replaceable>field</replaceable></term><listitem>
 304     <para>
 305      This value specifies CCL field (qualifier) definition for some
 306      field. For Z39.50 targets this most likely will specify the
 307      mapping to a numeric use attribute + a structure attribute.
 308      For SRU targets, the use attribute should be string based, in
 309      order to make the RPN to CQL conversion work properly (step 2).
 310     </para>
 311    </listitem>
 312    </varlistentry>
 313
 314    <varlistentry>
 315     <term>cfAuth</term><listitem>
 316     <para>
 317      When cfAuth is defined, its value will be used as authentication
 318      to backend target and authentication setting will be specified
 319      as part of a database. This is like a "proxy" for authentication and
 320      is used for Connector Framework based targets.
 321     </para>
 322    </listitem>
 323    </varlistentry>
 324
 325    <varlistentry>
 326     <term>cfProxy</term><listitem>
 327     <para>
 328      Specifies HTTP proxy for the target in the form
 329      <replaceable>host</replaceable>:<replaceable>port</replaceable>.
 330     </para>
 331    </listitem>
 332    </varlistentry>
 333
 334    <varlistentry>
 335     <term>cfSubDB</term><listitem>
 336     <para>
 337      Specifies sub database for a Connector Framework based target.
 338     </para>
 339    </listitem>
 340    </varlistentry>
 341
 342    <varlistentry id="contentConnector">
 343     <term>contentConnector</term><listitem>
 344     <para>
 345      Specifies a database for content-based proxy'ing.
 346     </para>
 347    </listitem>
 348    </varlistentry>
 349
 350    <varlistentry>
 351     <term>elementSet</term><listitem>
 352     <para>
 353      Specifies the elementSet to be sent to the target if record
 354      transform is enabled (not to be confused' with the record_transform
 355      module). The record transform is enabled only if the client uses
 356      record syntax = XML and a element set determined by
 357      the <literal>element_transform</literal> /
 358      <literal>element_raw</literal> from the configuration.
 359      By default that is the element sets <literal>pz2</literal>
 360      and <literal>raw</literal>.
 361      If record transform is not enabled, this setting is
 362      not used and the element set specified by the client
 363      is passed verbatim.
 364     </para>
 365    </listitem>
 366    </varlistentry>
 367
 368    <varlistentry>
 369     <term>literalTransform</term><listitem>
 370     <para>
 371      Specifies a XSL stylesheet to be used if record
 372      transform is anabled; see description of elementSet.
 373      The XSL transform is only used if the element set is set to the
 374      value of <literal>element_transform</literal> in the configuration.
 375     </para>
 376     <para>
 377      The value of literalTransform is the XSL - string encoded.
 378     </para>
 379    </listitem>
 380    </varlistentry>
 381
 382    <varlistentry>
 383     <term>piggyback</term><listitem>
 384     <para>
 385      A value of 1/true is a hint to the ZOOM module that this Z39.50
 386      target supports piggyback searches, ie Search Response with
 387      records. Any other value (false) will prevent the ZOOM module
 388      to make use of piggyback (all records part of Present Response).
 389     </para>
 390    </listitem>
 391    </varlistentry>
 392
 393    <varlistentry>
 394     <term>queryEncoding</term><listitem>
 395     <para>
 396      If this value is defined, all queries will be converted
 397      to this encoding. This should be used for all Z39.50 targets that
 398      do not use UTF-8 for query terms.
 399     </para>
 400    </listitem>
 401    </varlistentry>
 402
 403    <varlistentry>
 404     <term>recordEncoding</term><listitem>
 405     <para>
 406      Specifies the character encoding of records that are returned
 407      by the target. This is primarily used for targets were records
 408      are not UTF-8 encoded already. This setting is only used
 409      if the record transform is enabled (see description of elementSet).
 410     </para>
 411    </listitem>
 412    </varlistentry>
 413
 414    <varlistentry>
 415     <term>requestSyntax</term><listitem>
 416     <para>
 417      Specifies the record syntax to be specified for the target
 418      if record transform is enabled; see description of elementSet.
 419      If record transform is not enabled, the record syntax of the
 420      client is passed verbatim to the target.
 421     </para>
 422    </listitem>
 423    </varlistentry>
 424
 425    <varlistentry id="sortmap">
 426     <term>sortmap_<replaceable>field</replaceable></term><listitem>
 427     <para>
 428      This value the native field for a target. The form of the value is
 429      given by <link linkend="sortStrategy">sortStrategy</link>.
 430     </para>
 431    </listitem>
 432    </varlistentry>
 433
 434    <varlistentry id="sortStrategy">
 435     <term>sortStrategy</term><listitem>
 436     <para>
 437      Specifies sort strategy for a target. One of:
 438      <literal>z3950</literal>, <literal>type7</literal>,
 439      <literal>cql</literal>, <literal>sru11</literal> or
 440      <literal>embed</literal>. The <literal>embed</literal> chooses type-7
 441      or CQL sortby depending on whether Type-1 or CQL is
 442      actually sent to the target.
 443     </para>
 444    </listitem>
 445    </varlistentry>
 446
 447    <varlistentry>
 448     <term>sru</term><listitem>
 449     <para>
 450      If this setting is set, it specifies that the target is web service
 451      based and must be one of : <literal>get</literal>,
 452      <literal>post</literal>, <literal>soap</literal>
 453      or <literal>solr</literal>.
 454     </para>
 455    </listitem>
 456    </varlistentry>
 457
 458    <varlistentry>
 459     <term>transform</term><listitem>
 460     <para>
 461      Specifies a XSL stylesheet filename to be used if record
 462      transform is anabled; see description of elementSet.
 463      The XSL transform is only used if the element set is set to the
 464      value of <literal>element_transform</literal> in the configuration.
 465     </para>
 466    </listitem>
 467    </varlistentry>
 468
 469    <varlistentry>
 470     <term>udb</term><listitem>
 471     <para>
 472      This value is required and specifies the unique database for
 473      this profile . All target profiles should hold a unique database.
 474     </para>
 475    </listitem>
 476    </varlistentry>
 477
 478    <varlistentry id="urlRecipe">
 479     <term>urlRecipe</term><listitem>
 480     <para>
 481      The value of this field is a string that generates a dynamic link
 482      based on record content. If the resulting string is non-zero in length
 483      a new field, <literal>metadata</literal> with attribute
 484      <literal>type="generated-url"</literal>.
 485      The contents of this field is the result of the URL recipe conversion.
 486      The urlRecipe value may refer to an existing metadata element by
 487      ${field[pattern/result/flags]}, which will take content
 488      of field and perform a regular expression conversion using the pattern
 489      given. For example: <literal>${md-title[\s+/+/g]}</literal> takes
 490      metadadata element <literal>title</literal> and converts one or more
 491      spaces to a plus character.
 492     </para>
 493     <para>
 494      If the <link linkend="contentConnector">contentConnector</link>
 495      setting also defined, the resulting value is
 496      augmented with a session string as well as the content proxy server.
 497     </para>
 498    </listitem>
 499    </varlistentry>
 500
 501    <varlistentry>
 502     <term>zurl</term><listitem>
 503     <para>
 504      This is setting is mandatory and specifies the ZURL of the
 505      target in the form of host/database. The HTTP method should
 506      not be provided as this is guessed from the "sru" attribute value.
 507     </para>
 508    </listitem>
 509    </varlistentry>
 510   </variablelist>
 511  </refsect1>
 512  <refsect1>
 513   <title>SCHEMA</title>
 514   <literallayout><xi:include
 515   xi:href="../xml/schema/filter_zoom.rnc"
 516   xi:parse="text"
 517   xmlns:xi="http://www.w3.org/2001/XInclude" />
 518   </literallayout>
 519  </refsect1>
 520
 521  <refsect1>
 522   <title>EXAMPLES</title>
 523   <para>
 524    The following configuration illustrates most of the
 525    facilities:
 526    <screen><![CDATA[
 527     <filter type="zoom">
 528       <torus
 529          url="http://torus.indexdata.com/src/records/?query=udb%3D%db"
 530          proxy="localhost:3128"
 531          />
 532       <fieldmap cql="cql.anywhere"/>
 533       <fieldmap cql="cql.serverChoice"/>
 534       <fieldmap cql="dc.creator" ccl="au"/>
 535       <fieldmap cql="dc.title" ccl="ti"/>
 536       <fieldmap cql="dc.subject" ccl="su"/>
 537
 538       <cclmap>
 539         <qual name="ocn">
 540           <attr type="u" value="12"/>
 541           <attr type="s" value="107"/>
 542         </qual>
 543       </cclmap>
 544       <log apdu="true"/>
 545     </filter>
 546 ]]>
 547    </screen>
 548   </para>
 549
 550  </refsect1>
 551
 552  <refsect1>
 553   <title>SEE ALSO</title>
 554   <para>
 555    <citerefentry>
 556     <refentrytitle>metaproxy</refentrytitle>
 557     <manvolnum>1</manvolnum>
 558    </citerefentry>
 559   </para>
 560   <para>
 561    <citerefentry>
 562     <refentrytitle>virt_db</refentrytitle>
 563     <manvolnum>3mp</manvolnum>
 564    </citerefentry>
 565   </para>
 566  </refsect1>
 567
 568  &copyright;
 569 </refentry>
 570
 571 <!-- Keep this comment at the end of the file
 572 Local variables:
 573 mode: nxml
 574 nxml-child-indent: 1
 575 End:
 576 -->