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>
 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>
 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    <literal>cclmap</literal> elements part of the target profile.
 243   </para>
 244   <para>
 245    Step 1: For CQL, the query is converted to CCL. The mappings of
 246    CQL fields to CCL fields are handled by <literal>fieldmap</literal>
 247    elements as part of the target profile. The resulting query, CCL,
 248    is the converted to RPN using the schema mentioned earlier (via
 249    <literal>cclmap</literal>).
 250   </para>
 251   <para>
 252    Step 2: If the target is Z39.50-based, it is passed verbatim (RPN).
 253    If the target is SRU-based, the RPN will be converted to CQL.
 254    If the target is SOLR-based, the RPN will be converted to SOLR's query
 255    type.
 256   </para>
 257  </refsect1>
 258
 259  <refsect1>
 260   <title>SORTING</title>
 261   <para>
 262    The ZOOM module actively handle CQL sorting - using the SORTBY parameter
 263    which was introduced in SRU version 1.2. The conversion from SORTBY clause
 264    to native sort for some target is driven by the two parameters:
 265    <literal>sortStrategy</literal>
 266    and <literal>sortmap_</literal><replaceable>field</replaceable>.
 267   </para>
 268   <para>
 269    If a sort field that does not have an equivalent
 270    <literal>sortmap_</literal>-mapping is passed un-modified through the
 271    conversion. It doesn't throw a diagnostic.
 272   </para>
 273  </refsect1>
 274
 275  <refsect1>
 276   <title>TARGET PROFILE</title>
 277   <para>
 278    The ZOOM module is driven by a number of settings that specifies how
 279    to handle each target.
 280    Note that unknown elements are silently <emphasis>ignored</emphasis>.
 281   </para>
 282   <para>
 283    The elements, in alphabetical order, are:
 284   </para>
 285   <variablelist>
 286    <varlistentry>
 287     <term>authentication</term><listitem>
 288     <para>
 289      Authentication parameters to be sent to the target. For
 290      Z39.50 targets, this will be sent as part of the
 291      Init Request.
 292     </para>
 293     <para>
 294      If this value is omitted or empty no authentication information is sent.
 295     </para>
 296    </listitem>
 297    </varlistentry>
 298
 299    <varlistentry>
 300     <term>cclmap_*</term><listitem>
 301     <para>
 302      This value specifies CCL field (qualifier) definition for some
 303      field. For Z39.50 targets this most likely will specify the
 304      mapping to a numeric use attribute + a structure attribute.
 305      For SRU targets, the use attribute should be string based, in
 306      order to make the RPN to CQL conversion work properly (step 2).
 307     </para>
 308    </listitem>
 309    </varlistentry>
 310
 311    <varlistentry>
 312     <term>cfAuth</term><listitem>
 313     <para>
 314      When cfAuth is defined, its value will be used as authentication
 315      to backend target and authentication setting will be specified
 316      as part of a database. This is like a "proxy" for authentication and
 317      is used for Connector Framework based targets.
 318     </para>
 319    </listitem>
 320    </varlistentry>
 321
 322    <varlistentry>
 323     <term>cfProxy</term><listitem>
 324     <para>
 325      Specifies HTTP proxy for the target in the form
 326      <replaceable>host</replaceable>:<replaceable>port</replaceable>.
 327     </para>
 328    </listitem>
 329    </varlistentry>
 330
 331    <varlistentry>
 332     <term>cfSubDb</term><listitem>
 333     <para>
 334      Specifies sub database for a Connector Framework based target.
 335     </para>
 336    </listitem>
 337    </varlistentry>
 338
 339    <varlistentry>
 340     <term>contentConnector</term><listitem>
 341     <para>
 342      Specifies a database for content-based proxy'ing.
 343     </para>
 344    </listitem>
 345    </varlistentry>
 346
 347    <varlistentry>
 348     <term>elementSet</term><listitem>
 349     <para>
 350      Specifies the elementSet to be sent to the target if record
 351      transform is enabled (not to be confused' with the record_transform
 352      module). The record transform is enabled only if the client uses
 353      record syntax = XML and a element set determined by
 354      the <literal>element_transform</literal> /
 355      <literal>element_raw</literal> from the configuration.
 356      By default that is the element sets <literal>pz2</literal>
 357      and <literal>raw</literal>.
 358      If record transform is not enabled, this setting is
 359      not used and the element set specified by the client
 360      is passed verbatim.
 361     </para>
 362    </listitem>
 363    </varlistentry>
 364
 365    <varlistentry>
 366     <term>literalTransform</term><listitem>
 367     <para>
 368      Specifies a XSL stylesheet to be used if record
 369      transform is anabled; see description of elementSet.
 370      The XSL transform is only used if the element set is set to the
 371      value of <literal>element_transform</literal> in the configuration.
 372     </para>
 373     <para>
 374      The value of literalTransform is the XSL - string encoded.
 375     </para>
 376    </listitem>
 377    </varlistentry>
 378
 379    <varlistentry>
 380     <term>piggyback</term><listitem>
 381     <para>
 382      A value of 1/true is a hint to the ZOOM module that this Z39.50
 383      target supports piggyback searches, ie Search Response with
 384      records. Any other value (false) will prevent the ZOOM module
 385      to make use of piggyback (all records part of Present Response).
 386     </para>
 387    </listitem>
 388    </varlistentry>
 389
 390    <varlistentry>
 391     <term>queryEncoding</term><listitem>
 392     <para>
 393      If this value is defined, all queries will be converted
 394      to this encoding. This should be used for all Z39.50 targets that
 395      do not use UTF-8 for query terms.
 396     </para>
 397    </listitem>
 398    </varlistentry>
 399
 400    <varlistentry>
 401     <term>recordEncoding</term><listitem>
 402     <para>
 403      Specifies the character encoding of records that are returned
 404      by the target. This is primarily used for targets were records
 405      are not UTF-8 encoded already. This setting is only used
 406      if the record transform is enabled (see description of elementSet).
 407     </para>
 408    </listitem>
 409    </varlistentry>
 410
 411    <varlistentry>
 412     <term>requestSyntax</term><listitem>
 413     <para>
 414      Specifies the record syntax to be specified for the target
 415      if record transform is enabled; see description of elementSet.
 416      If record transform is not enabled, the record syntax of the
 417      client is passed verbatim to the target.
 418     </para>
 419    </listitem>
 420    </varlistentry>
 421
 422    <varlistentry>
 423     <term>sortmap_</term><listitem>
 424     <para>
 425      This value the native field for a target.
 426     </para>
 427    </listitem>
 428    </varlistentry>
 429
 430    <varlistentry>
 431     <term>sortStrategy</term><listitem>
 432     <para>
 433      Specifies sort strategy for a target. One of:
 434      <literal>z3950</literal>, <literal>type7</literal>,
 435      <literal>cql</literal>, <literal>sru11</literal> or
 436      <literal>embed</literal>. The <literal>embed</literal> chooses type-7
 437      or CQL sortby depending on whether Type-1 or CQL is
 438      actually sent to the target.
 439     </para>
 440    </listitem>
 441    </varlistentry>
 442
 443    <varlistentry>
 444     <term>sru</term><listitem>
 445     <para>
 446      If this setting is set, it specifies that the target is web service
 447      based and must be one of : <literal>get</literal>,
 448      <literal>post</literal>, <literal>soap</literal>
 449      or <literal>solr</literal>.
 450     </para>
 451    </listitem>
 452    </varlistentry>
 453
 454    <varlistentry>
 455     <term>transform</term><listitem>
 456     <para>
 457      Specifies a XSL stylesheet filename to be used if record
 458      transform is anabled; see description of elementSet.
 459      The XSL transform is only used if the element set is set to the
 460      value of <literal>element_transform</literal> in the configuration.
 461     </para>
 462    </listitem>
 463    </varlistentry>
 464
 465    <varlistentry>
 466     <term>udb</term><listitem>
 467     <para>
 468      This value is required and specifies the unique database for
 469      this profile . All target profiles should hold a unique database.
 470     </para>
 471    </listitem>
 472    </varlistentry>
 473
 474    <varlistentry>
 475     <term>urlRecipe</term><listitem>
 476     <para>
 477      The value of this field is a string that generates a dynamic link
 478      based on content. If the resulting string is non-zero in length
 479      a new field, <literal>metadata</literal> with attribute
 480      type=generated-url. The contents of this field is the result of the
 481      URL recipe conversion. The urlRecipe value may refer to an existing
 482      metadata element by ${field[pattern/result/flags]}, which will take content
 483      of field and perform a regular expression conversion using the pattern
 484      given. For example: <literal>${md-title[\s+/+/g]}</literal> takes
 485      metadadata element <literal>title</literal> and converts one or more
 486      spaces to a plus character.
 487     </para>
 488     <para>
 489      If the contentConnector setting is defined the resulting value is
 490      agmented with a session string as well as the content proxy server.
 491     </para>
 492    </listitem>
 493    </varlistentry>
 494
 495    <varlistentry>
 496     <term>zurl</term><listitem>
 497     <para>
 498      This is setting is mandatory and specifies the ZURL of the
 499      target in the form of host/database. The HTTP method should
 500      not be provide as this is guessed from the "sru" attribute value.
 501     </para>
 502    </listitem>
 503    </varlistentry>
 504   </variablelist>
 505  </refsect1>
 506  <refsect1>
 507   <title>SCHEMA</title>
 508   <literallayout><xi:include
 509   xi:href="../xml/schema/filter_zoom.rnc"
 510   xi:parse="text"
 511   xmlns:xi="http://www.w3.org/2001/XInclude" />
 512   </literallayout>
 513  </refsect1>
 514
 515  <refsect1>
 516   <title>EXAMPLES</title>
 517   <para>
 518    The following configuration illustrates most of the
 519    facilities:
 520    <screen><![CDATA[
 521     <filter type="zoom">
 522       <torus
 523          url="http://torus.indexdata.com/src/records/?query=udb%3D%db"
 524          proxy="localhost:3128"
 525          />
 526       <fieldmap cql="cql.anywhere"/>
 527       <fieldmap cql="cql.serverChoice"/>
 528       <fieldmap cql="dc.creator" ccl="au"/>
 529       <fieldmap cql="dc.title" ccl="ti"/>
 530       <fieldmap cql="dc.subject" ccl="su"/>
 531
 532       <cclmap>
 533         <qual name="ocn">
 534           <attr type="u" value="12"/>
 535           <attr type="s" value="107"/>
 536         </qual>
 537       </cclmap>
 538       <log apdu="true"/>
 539     </filter>
 540 ]]>
 541    </screen>
 542   </para>
 543
 544  </refsect1>
 545
 546  <refsect1>
 547   <title>SEE ALSO</title>
 548   <para>
 549    <citerefentry>
 550     <refentrytitle>metaproxy</refentrytitle>
 551     <manvolnum>1</manvolnum>
 552    </citerefentry>
 553   </para>
 554   <para>
 555    <citerefentry>
 556     <refentrytitle>virt_db</refentrytitle>
 557     <manvolnum>3mp</manvolnum>
 558    </citerefentry>
 559   </para>
 560  </refsect1>
 561
 562  &copyright;
 563 </refentry>
 564
 565 <!-- Keep this comment at the end of the file
 566 Local variables:
 567 mode: nxml
 568 nxml-child-indent: 1
 569 End:
 570 -->