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