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>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.
 308     </para>
 309     <para>
 310      If this value is omitted or empty no authentication information is sent.
 311     </para>
 312    </listitem>
 313    </varlistentry>
 314
 315    <varlistentry id="cclmap">
 316     <term>cclmap_<replaceable>field</replaceable></term><listitem>
 317     <para>
 318      This value specifies CCL field (qualifier) definition for some
 319      field. For Z39.50 targets this most likely will specify the
 320      mapping to a numeric use attribute + a structure attribute.
 321      For SRU targets, the use attribute should be string based, in
 322      order to make the RPN to CQL conversion work properly (step 2).
 323     </para>
 324    </listitem>
 325    </varlistentry>
 326
 327    <varlistentry>
 328     <term>cfAuth</term><listitem>
 329     <para>
 330      When cfAuth is defined, its value will be used as authentication
 331      to backend target and authentication setting will be specified
 332      as part of a database. This is like a "proxy" for authentication and
 333      is used for Connector Framework based targets.
 334     </para>
 335    </listitem>
 336    </varlistentry>
 337
 338    <varlistentry>
 339     <term>cfProxy</term><listitem>
 340     <para>
 341      Specifies HTTP proxy for the target in the form
 342      <replaceable>host</replaceable>:<replaceable>port</replaceable>.
 343     </para>
 344    </listitem>
 345    </varlistentry>
 346
 347    <varlistentry>
 348     <term>cfSubDB</term><listitem>
 349     <para>
 350      Specifies sub database for a Connector Framework based target.
 351     </para>
 352    </listitem>
 353    </varlistentry>
 354
 355    <varlistentry id="contentConnector">
 356     <term>contentConnector</term><listitem>
 357     <para>
 358      Specifies a database for content-based proxy'ing.
 359     </para>
 360    </listitem>
 361    </varlistentry>
 362
 363    <varlistentry>
 364     <term>elementSet</term><listitem>
 365     <para>
 366      Specifies the elementSet to be sent to the target if record
 367      transform is enabled (not to be confused' with the record_transform
 368      module). The record transform is enabled only if the client uses
 369      record syntax = XML and a element set determined by
 370      the <literal>element_transform</literal> /
 371      <literal>element_raw</literal> from the configuration.
 372      By default that is the element sets <literal>pz2</literal>
 373      and <literal>raw</literal>.
 374      If record transform is not enabled, this setting is
 375      not used and the element set specified by the client
 376      is passed verbatim.
 377     </para>
 378    </listitem>
 379    </varlistentry>
 380
 381    <varlistentry>
 382     <term>literalTransform</term><listitem>
 383     <para>
 384      Specifies a XSL stylesheet to be used if record
 385      transform is anabled; see description of elementSet.
 386      The XSL transform is only used if the element set is set to the
 387      value of <literal>element_transform</literal> in the configuration.
 388     </para>
 389     <para>
 390      The value of literalTransform is the XSL - string encoded.
 391     </para>
 392    </listitem>
 393    </varlistentry>
 394
 395    <varlistentry>
 396     <term>piggyback</term><listitem>
 397     <para>
 398      A value of 1/true is a hint to the ZOOM module that this Z39.50
 399      target supports piggyback searches, ie Search Response with
 400      records. Any other value (false) will prevent the ZOOM module
 401      to make use of piggyback (all records part of Present Response).
 402     </para>
 403    </listitem>
 404    </varlistentry>
 405
 406    <varlistentry>
 407     <term>queryEncoding</term><listitem>
 408     <para>
 409      If this value is defined, all queries will be converted
 410      to this encoding. This should be used for all Z39.50 targets that
 411      do not use UTF-8 for query terms.
 412     </para>
 413    </listitem>
 414    </varlistentry>
 415
 416    <varlistentry>
 417     <term>recordEncoding</term><listitem>
 418     <para>
 419      Specifies the character encoding of records that are returned
 420      by the target. This is primarily used for targets were records
 421      are not UTF-8 encoded already. This setting is only used
 422      if the record transform is enabled (see description of elementSet).
 423     </para>
 424    </listitem>
 425    </varlistentry>
 426
 427    <varlistentry>
 428     <term>requestSyntax</term><listitem>
 429     <para>
 430      Specifies the record syntax to be specified for the target
 431      if record transform is enabled; see description of elementSet.
 432      If record transform is not enabled, the record syntax of the
 433      client is passed verbatim to the target.
 434     </para>
 435    </listitem>
 436    </varlistentry>
 437
 438    <varlistentry id="sortmap">
 439     <term>sortmap_<replaceable>field</replaceable></term><listitem>
 440     <para>
 441      This value the native field for a target. The form of the value is
 442      given by <link linkend="sortStrategy">sortStrategy</link>.
 443     </para>
 444    </listitem>
 445    </varlistentry>
 446
 447    <varlistentry id="sortStrategy">
 448     <term>sortStrategy</term><listitem>
 449     <para>
 450      Specifies sort strategy for a target. One of:
 451      <literal>z3950</literal>, <literal>type7</literal>,
 452      <literal>cql</literal>, <literal>sru11</literal> or
 453      <literal>embed</literal>. The <literal>embed</literal> chooses type-7
 454      or CQL sortby depending on whether Type-1 or CQL is
 455      actually sent to the target.
 456     </para>
 457    </listitem>
 458    </varlistentry>
 459
 460    <varlistentry>
 461     <term>sru</term><listitem>
 462     <para>
 463      If this setting is set, it specifies that the target is web service
 464      based and must be one of : <literal>get</literal>,
 465      <literal>post</literal>, <literal>soap</literal>
 466      or <literal>solr</literal>.
 467     </para>
 468    </listitem>
 469    </varlistentry>
 470
 471    <varlistentry>
 472     <term>transform</term><listitem>
 473     <para>
 474      Specifies a XSL stylesheet filename to be used if record
 475      transform is anabled; see description of elementSet.
 476      The XSL transform is only used if the element set is set to the
 477      value of <literal>element_transform</literal> in the configuration.
 478     </para>
 479    </listitem>
 480    </varlistentry>
 481
 482    <varlistentry>
 483     <term>udb</term><listitem>
 484     <para>
 485      This value is required and specifies the unique database for
 486      this profile . All target profiles should hold a unique database.
 487     </para>
 488    </listitem>
 489    </varlistentry>
 490
 491    <varlistentry id="urlRecipe">
 492     <term>urlRecipe</term><listitem>
 493     <para>
 494      The value of this field is a string that generates a dynamic link
 495      based on record content. If the resulting string is non-zero in length
 496      a new field, <literal>metadata</literal> with attribute
 497      <literal>type="generated-url"</literal>.
 498      The contents of this field is the result of the URL recipe conversion.
 499      The urlRecipe value may refer to an existing metadata element by
 500      ${field[pattern/result/flags]}, which will take content
 501      of field and perform a regular expression conversion using the pattern
 502      given. For example: <literal>${md-title[\s+/+/g]}</literal> takes
 503      metadadata element <literal>title</literal> and converts one or more
 504      spaces to a plus character.
 505     </para>
 506     <para>
 507      If the <link linkend="contentConnector">contentConnector</link>
 508      setting also defined, the resulting value is
 509      augmented with a session string as well as the content proxy server.
 510     </para>
 511    </listitem>
 512    </varlistentry>
 513
 514    <varlistentry>
 515     <term>zurl</term><listitem>
 516     <para>
 517      This is setting is mandatory and specifies the ZURL of the
 518      target in the form of host/database. The HTTP method should
 519      not be provided as this is guessed from the "sru" attribute value.
 520     </para>
 521    </listitem>
 522    </varlistentry>
 523   </variablelist>
 524  </refsect1>
 525  <refsect1>
 526   <title>DATABASE parameters</title>
 527   <para>
 528    Extra information may be carried in the Z39.50 Datbase or SRU path,
 529    such as authentication to be passed to backend etc. Some of
 530    the parameters override TARGET profile values. The format is
 531   </para>
 532   <para>
 533    udb,parm1=value1&amp;parm2=value2&amp;...
 534   </para>
 535   <para>
 536    Where udb is the unique database recognised by the backend and parm1,
 537    value1, .. are parameters to be passed. The following describes the
 538    supported parameters.
 539   </para>
 540   <variablelist>
 541    <varlistentry>
 542     <term>user</term>
 543     <listitem>
 544      <para>
 545       Specifies user to be passed to backend. If this parameters is
 546       omitted, the user will be taken from TARGET profile setting
 547       <literal>authentication</literal>.
 548      </para>
 549     </listitem>
 550    </varlistentry>
 551    <varlistentry>
 552     <term>password</term>
 553     <listitem>
 554      <para>
 555       Specifies password to be passed to backend. If this parameters is
 556       omitted, the password will be taken from TARGET profile setting
 557       <literal>authentication</literal>.
 558      </para>
 559     </listitem>
 560    </varlistentry>
 561    <varlistentry>
 562     <term>proxy</term>
 563     <listitem>
 564      <para>
 565       Specifies proxy to be for backend. If this parameters is
 566       omitted, the proxy will be taken from TARGET profile setting
 567       <literal>cfProxy</literal>.
 568      </para>
 569     </listitem>
 570    </varlistentry>
 571    <varlistentry>
 572     <term>cproxysession</term>
 573     <listitem>
 574      <para>
 575       Session ID for content proxy. This parameter is, generally,
 576       not used by anything but the content proxy itself.
 577      </para>
 578     </listitem>
 579    </varlistentry>
 580    <varlistentry>
 581     <term>realm</term>
 582     <listitem>
 583      <para>
 584       Session realm to be used for this target, changed the resulting
 585       URL to be used for getting a target profile, by changing the
 586       value that gets substituted for the %realm string.
 587      </para>
 588     </listitem>
 589    </varlistentry>
 590    <varlistentry>
 591     <term>x-parm</term>
 592     <listitem>
 593      <para>
 594       All parameters that has prefix x, dash are passed verbatim
 595       to the backend.
 596      </para>
 597     </listitem>
 598    </varlistentry>
 599   </variablelist>
 600  </refsect1>
 601  <refsect1>
 602   <title>SCHEMA</title>
 603   <literallayout><xi:include
 604   xi:href="../xml/schema/filter_zoom.rnc"
 605   xi:parse="text"
 606   xmlns:xi="http://www.w3.org/2001/XInclude" />
 607   </literallayout>
 608  </refsect1>
 609
 610  <refsect1>
 611   <title>EXAMPLES</title>
 612   <para>
 613    The following configuration illustrates most of the
 614    facilities:
 615    <screen><![CDATA[
 616     <filter type="zoom">
 617       <torus
 618          url="http://torus.indexdata.com/src/records/?query=udb%3D%db"
 619          proxy="localhost:3128"
 620          />
 621       <fieldmap cql="cql.anywhere"/>
 622       <fieldmap cql="cql.serverChoice"/>
 623       <fieldmap cql="dc.creator" ccl="au"/>
 624       <fieldmap cql="dc.title" ccl="ti"/>
 625       <fieldmap cql="dc.subject" ccl="su"/>
 626
 627       <cclmap>
 628         <qual name="ocn">
 629           <attr type="u" value="12"/>
 630           <attr type="s" value="107"/>
 631         </qual>
 632       </cclmap>
 633       <log apdu="true"/>
 634     </filter>
 635 ]]>
 636    </screen>
 637   </para>
 638
 639  </refsect1>
 640
 641  <refsect1>
 642   <title>SEE ALSO</title>
 643   <para>
 644    <citerefentry>
 645     <refentrytitle>metaproxy</refentrytitle>
 646     <manvolnum>1</manvolnum>
 647    </citerefentry>
 648   </para>
 649   <para>
 650    <citerefentry>
 651     <refentrytitle>virt_db</refentrytitle>
 652     <manvolnum>3mp</manvolnum>
 653    </citerefentry>
 654   </para>
 655  </refsect1>
 656
 657  &copyright;
 658 </refentry>
 659
 660 <!-- Keep this comment at the end of the file
 661 Local variables:
 662 mode: nxml
 663 nxml-child-indent: 1
 664 End:
 665 -->