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><title>DESCRIPTION</title>
  25   <para>
  26    This filter implements a generic client based on
  27    <ulink url="&url.yaz.zoom;">ZOOM</ulink> of YAZ.
  28    The client implements the protocols that ZOOM C does: Z39.50, SRU
  29    (GET, POST, SOAP) and SOLR .
  30   </para>
  31
  32   <para>
  33    This filter only deals with Z39.50 on input. The following services
  34    are supported: init, search, present and close. The backend target
  35    is selected based on the database as part search and
  36    <emphasis>not</emphasis> as part of init.
  37   </para>
  38
  39   <para>
  40    This filter is an alternative to the z3950_client filter but also
  41    shares properties of the virt_db - in that the target is selected
  42    for a specific database
  43   </para>
  44
  45   <para>
  46    The ZOOM filter relies on a target profile description, which is
  47    XML based. It picks the profile for a given database from a web service
  48    or it may be locally given for each unique database (AKA virtual database
  49    in virt_db). Target profiles are directly and indrectly given as part
  50    of the <literal>torus</literal> element in the configuration.
  51   </para>
  52
  53  </refsect1>
  54
  55  <refsect1><title>CONFIGURATION</title>
  56    <para>
  57      The configuration consists of three parts: <literal>torus</literal>,
  58      <literal>fieldmap</literal> and <literal>cclmap</literal>.
  59    </para>
  60    <para>
  61      The <literal>torus</literal> element specifies target profiles
  62      and takes the following content:
  63    </para>
  64    <variablelist>
  65      <varlistentry>
  66        <term>attribute <literal>url</literal></term>
  67        <listitem><para>
  68            URL of Web service to be used to fetch target profile
  69            for a given database (udb). The special sequence
  70            <literal>%db</literal> of the URL is replaced by the
  71            actual database specified as part of Search.
  72          </para>
  73        </listitem>
  74      </varlistentry>
  75      <varlistentry>
  76        <term>attribute <literal>xsldir</literal></term>
  77        <listitem><para>
  78            Directory that is searched for XSL stylesheets. Stylesheets
  79            are specified in the target profile by the
  80            <literal>transform</literal> element.
  81          </para>
  82        </listitem>
  83      </varlistentry>
  84      <varlistentry>
  85        <term>attribute <literal>element_transform</literal></term>
  86        <listitem><para>
  87            Specifies the element that triggers retrieval and transform using
  88            the parameters elementSet, recordEncoding, requestSyntax, transform
  89            from the target profile. Default value
  90            is "pz2", due to the fact that for historical reasons the
  91            common format is that used in Pazpar2.
  92          </para>
  93        </listitem>
  94      </varlistentry>
  95      <varlistentry>
  96        <term>attribute <literal>element_raw</literal></term>
  97        <listitem><para>
  98            Specifies an element that triggers retrieval using the
  99            parameters elementSet, recordEncoding, requestSyntax from the
 100            target profile. Same actions as for element_transform, but without
 101            the XSL transform. Useful for debugging. The default value is "raw".
 102          </para>
 103        </listitem>
 104      </varlistentry>
 105      <varlistentry>
 106        <term>element <literal>records</literal></term>
 107        <listitem><para>
 108            Local target profiles. This element may includes zero or
 109            more <literal>record</literal> elements (one per target
 110            profile). See section TARGET PROFILE.
 111          </para>
 112        </listitem>
 113      </varlistentry>
 114    </variablelist>
 115    <para>
 116      The <literal>fieldmap</literal> may be specified zero or more times and
 117      specifies the map from CQL fields to CCL fields and takes the
 118      following content:
 119    </para>
 120    <variablelist>
 121      <varlistentry>
 122        <term>attribute <literal>cql</literal></term>
 123        <listitem>
 124          <para>
 125            CQL field that we are mapping "from".
 126          </para>
 127        </listitem>
 128      </varlistentry>
 129      <varlistentry>
 130        <term>attribute <literal>ccl</literal></term>
 131        <listitem>
 132          <para>
 133            CCL field that we are mapping "to".
 134          </para>
 135        </listitem>
 136      </varlistentry>
 137    </variablelist>
 138    <para>
 139      The final part of the configuration consists of zero or more
 140      <literal>cclmap</literal> elements that specifies a <emphais>base</emphais>
 141      CCL profile to be used for all targets. This configuration, thus, will
 142      be combined with cclmap-definitions from the target profile.
 143    </para>
 144  </refsect1>
 145  <refsect1><title>QUERIES</title>
 146    <para>
 147      The ZOOM filter accepts three query types: RPN(Type-1), CCL and
 148      CQL.
 149    </para>
 150    <para>
 151      Queries are converted in two separate steps. In the first step
 152      the input query is converted to RPN/Type-1. This is always
 153      the common internal format between step 1 and step 2.
 154      In step 2 the query is converted to the native query type of the target.
 155    </para>
 156    <para>
 157      Step 1: for RPN, the query is passed unmodified to the target.
 158    </para>
 159    <para>
 160      Step 1: for CCL, the query is converted to RPN via
 161      <literal>cclmap</literal> elements part of the target profile.
 162    </para>
 163    <para>
 164      Step 1: For CQL, the query is converted to CCL. The mappings of
 165      CQL fields to CCL fields are handled by <literal>fieldmap</literal>
 166      elements as part of the target profile. The resulting query, CCL,
 167      is the converted to RPN using the schema mentioned earlier (via
 168      <literal>cclmap</literal>).
 169    </para>
 170    <para>
 171      Step 2: If the target is Z39.50-based, it is passed verbatim (RPN).
 172      If the target is SRU-based, the RPN will be converted to CQL.
 173      If the target is SOLR-based, the RPN will be converted to SOLR's query
 174      type.
 175    </para>
 176  </refsect1>
 177
 178  <refsect1><title>TARGET PROFILE</title>
 179    <para>
 180      The following elements are honored by the ZOOM module of Metaproxy.
 181      Note that unknown elements are silently ignored. There are several
 182      elements in use that makes no sense to the ZOOM module.
 183    </para>
 184    <variablelist>
 185      <varlistentry>
 186        <term>authentication</term><listitem>
 187          <para>
 188            Authentication parameters to be sent to the target. For
 189            Z39.50 targets, this will be sent as part of the
 190            Init Request.
 191          </para>
 192          <para>
 193            If this value is omitted or empty, not authentication information
 194            is simply omitted.
 195          </para>
 196        </listitem>
 197      </varlistentry>
 198
 199      <varlistentry>
 200        <term>piggyback</term><listitem>
 201          <para>
 202            A value of 1/true is a hint to the ZOOM module that this Z39.50
 203            target supports piggyback searches, ie Search Response with
 204            records. Any other value (false) will prevent the ZOOM module
 205            to make use of piggyback (all records part of Present Response).
 206          </para>
 207        </listitem>
 208      </varlistentry>
 209
 210      <varlistentry>
 211        <term>queryEncoding</term><listitem>
 212          <para>
 213            If this value is defined, all queries will be converted
 214            to this encoding. This should be used for all Z39.50 targets that
 215            do not use UTF-8 for query terms.
 216          </para>
 217        </listitem>
 218      </varlistentry>
 219
 220      <varlistentry>
 221        <term>udb</term><listitem>
 222          <para>
 223            This value is required and specifies the unique database for
 224            this profile . All target profiles should hold a unique database.
 225          </para>
 226        </listitem>
 227      </varlistentry>
 228
 229      <varlistentry>
 230        <term>cclmap_*</term><listitem>
 231          <para>
 232            This value specifies CCL field (qualifier) definition for some
 233            field. For Z39.50 targets this most likely will specify the
 234            mapping to a numeric use attribute + a structure attribute.
 235            For SRU targets, the use attribute should be string based, in
 236            order to make the RPN to CQL conversion work properly (step 2).
 237          </para>
 238        </listitem>
 239      </varlistentry>
 240
 241      <varlistentry>
 242        <term>elementSet</term><listitem>
 243          <para>
 244            Specifies the elementSet to be sent to the target if record
 245            transform is enabled (not to be confused' with the record_transform
 246            module). The record transform is enabled only if the client uses
 247            record syntax = XML and a element set determined by
 248            the <literal>element_transform</literal> /
 249            <literal>element_raw</literal> from the configuration.
 250            By default that is the element sets <literal>pz2</literal>
 251            and <literal>raw</literal>.
 252            If record transform is not enabled, this setting is
 253            not used and the element set specified by the client
 254            is passed verbatim.
 255          </para>
 256        </listitem>
 257      </varlistentry>
 258
 259      <varlistentry>
 260        <term>recordEncoding</term><listitem>
 261          <para>
 262            Specifies the character encoding of records that are returned
 263            by the target. This is primarily used for targets were records
 264            are not UTF-8 encoded already. This setting is only used
 265            if the record transform is enabled (see description of elementSet).
 266          </para>
 267        </listitem>
 268      </varlistentry>
 269
 270      <varlistentry>
 271        <term>requestSyntax</term><listitem>
 272          <para>
 273            Specifies the record syntax to be specified for the target
 274            if record transform is enabled; see description of elementSet.
 275            If record transform is not enabled, the record syntax of the
 276            client is passed verbatim to the target.
 277          </para>
 278        </listitem>
 279      </varlistentry>
 280
 281      <varlistentry>
 282        <term>sru</term><listitem>
 283          <para>
 284            If this setting is set, it specifies that the target is web service
 285            based and must be one of : <literal>get</literal>,
 286            <literal>post</literal>, <literal>soap</literal>
 287            or <literal>solr</literal>.
 288          </para>
 289        </listitem>
 290      </varlistentry>
 291
 292      <varlistentry>
 293        <term>transform</term><listitem>
 294          <para>
 295            Specifies a XSL stylesheet filename to be used if record
 296            transform is anabled; see desciprion of elementSet.
 297            The XSL transform is only used if the element set is set to the
 298            value of <literal>element_transform</literal> in the configuration.
 299          </para>
 300        </listitem>
 301      </varlistentry>
 302
 303      <varlistentry>
 304        <term>zurl</term><listitem>
 305          <para>
 306            This is setting is mandatory and specifies the ZURL of the
 307            targetin the form of host/database.
 308          </para>
 309        </listitem>
 310      </varlistentry>
 311    </variablelist>
 312  </refsect1>
 313  <refsect1><title>SCHEMA</title>
 314    <literallayout><xi:include
 315                      xi:href="../xml/schema/filter_zoom.rnc"
 316                      xi:parse="text"
 317                      xmlns:xi="http://www.w3.org/2001/XInclude" />
 318    </literallayout>
 319  </refsect1>
 320
 321  <refsect1><title>EXAMPLES</title>
 322   <para>
 323    The following configuration illustrates most of the
 324    facilities:
 325    <screen><![CDATA[
 326     <filter type="zoom">
 327       <torus
 328          url="http://torus.indexdata.com/src/records/?query=udb%3D%db"
 329          xsldir="."
 330          />
 331       <fieldmap cql="cql.anywhere"/>
 332       <fieldmap cql="cql.serverChoice"/>
 333       <fieldmap cql="dc.creator" ccl="au"/>
 334       <fieldmap cql="dc.title" ccl="ti"/>
 335       <fieldmap cql="dc.subject" ccl="su"/>
 336
 337       <cclmap>
 338         <qual name="ocn">
 339           <attr type="u" value="12"/>
 340           <attr type="s" value="107"/>
 341         </qual>
 342       </cclmap>
 343     </filter>
 344 ]]>
 345    </screen>
 346   </para>
 347
 348  </refsect1>
 349
 350  <refsect1><title>SEE ALSO</title>
 351   <para>
 352    <citerefentry>
 353     <refentrytitle>metaproxy</refentrytitle>
 354     <manvolnum>1</manvolnum>
 355    </citerefentry>
 356   </para>
 357   <para>
 358    <citerefentry>
 359     <refentrytitle>virt_db</refentrytitle>
 360     <manvolnum>3mp</manvolnum>
 361    </citerefentry>
 362   </para>
 363  </refsect1>
 364
 365  &copyright;
 366 </refentry>
 367
 368 <!-- Keep this comment at the end of the file
 369 Local variables:
 370 mode: sgml
 371 sgml-omittag:t
 372 sgml-shorttag:t
 373 sgml-minimize-attributes:nil
 374 sgml-always-quote-attributes:t
 375 sgml-indent-step:1
 376 sgml-indent-data:t
 377 sgml-parent-document:nil
 378 sgml-local-catalogs: nil
 379 sgml-namecase-general:t
 380 End:
 381 -->