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