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