-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY copyright SYSTEM "copyright.xml">
<!ENTITY % idcommon SYSTEM "common/common.ent">
<productname>Metaproxy</productname>
<info><orgname>Index Data</orgname></info>
</refentryinfo>
-
+
<refmeta>
<refentrytitle>zoom</refentrytitle>
<manvolnum>3mp</manvolnum>
<refmiscinfo class="manual">Metaproxy Module</refmiscinfo>
</refmeta>
-
+
<refnamediv>
<refname>zoom</refname>
<refpurpose>Metaproxy ZOOM Module</refpurpose>
</refnamediv>
-
+
<refsect1>
<title>DESCRIPTION</title>
<para>
This filter implements a generic client based on
<ulink url="&url.yaz.zoom;">ZOOM</ulink> of YAZ.
The client implements the protocols that ZOOM C does: Z39.50, SRU
- (GET, POST, SOAP) and SOLR .
+ (GET, POST, SOAP) and Solr .
</para>
-
+
<para>
This filter only deals with Z39.50 on input. The following services
are supported: init, search, present and close. The backend target
<refsect1>
<title>CONFIGURATION</title>
<para>
- The configuration consists of five parts: <literal>torus</literal>,
+ The configuration consists of six parts: <literal>torus</literal>,
<literal>fieldmap</literal>, <literal>cclmap</literal>,
- <literal>contentProxy</literal> and <literal>log</literal>.
+ <literal>contentProxy</literal>, <literal>log</literal>
+ and <literal>zoom</literal>.
</para>
<refsect2>
<title>torus</title>
<term>attribute <literal>url</literal></term>
<listitem>
<para>
- URL of Web service to be used to fetch target profile
- for a given database (udb). The special sequence
- <literal>%db</literal> of the URL is replaced by the
- actual database specified as part of Search.
+ URL of Web service to be used when fetch target profiles from
+ a remote service (Torus normally).
+ </para>
+ <para>
+ The sequence <literal>%query</literal> is replaced with a CQL
+ query for the Torus search.
</para>
<para>
The special sequence <literal>%realm</literal> is replaced by value
of attribute <literal>realm</literal> or by realm DATABASE argument.
</para>
+ <para>
+ The special sequence <literal>%db</literal> is replaced with
+ a single database while searching. Note that this sequence
+ is no longer needed, because the <literal>%query</literal> can already
+ query for a single database by using CQL query
+ <literal>udb==...</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>attribute <literal>content_url</literal></term>
+ <listitem>
+ <para>
+ URL of Web service to be used to fetch target profile
+ for a given database (udb) of type content. Semantics otherwise like
+ <literal>url</literal> attribute above.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="auth_url">
+ <term>attribute <literal>auth_url</literal></term>
+ <listitem>
+ <para>
+ URL of Web service to be used to for auth/IP lookup. If this
+ defined, all access is granted or denied as part of Z39.50 Init
+ by the ZOOM module and the use of database parameters realm and
+ torus_url is not allowed. If this setting is not defined,
+ all access is allowed and realm and/or torus_url may be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="auth_hostname">
+ <term>attribute <literal>auth_hostname</literal></term>
+ <listitem>
+ <para>
+ Limits IP lookup to a given logical hostname.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<listitem>
<para>
The default realm value. Used for %realm in URL, unless
- specified in DATABASE argument.
+ specified in DATABASE parameter.
</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
<varlistentry>
+ <term>attribute <literal>explain_xsl</literal></term>
+ <listitem>
+ <para>
+ Specifies a stylesheet that converts one or more Torus records
+ to ZeeExplain records. The content of recordData is assumed to be
+ holding each Explain record.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>attribute <literal>record_xsl</literal></term>
+ <listitem>
+ <para>
+ Specifies a stylesheet that converts retrieval records after
+ transform/literal operations.
+ </para>
+ <para>
+ When Metaproxy creates a content proxy session, the XSL parameter
+ <literal>cproxyhost</literal> is passed to the transform.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term>element <literal>records</literal></term>
<listitem>
<para>
</para>
<variablelist>
<varlistentry>
+ <term>attribute <literal>config_file</literal></term>
+ <listitem>
+ <para>
+ Specifies the file that configures the cf-proxy system. Metaproxy
+ uses setting <literal>sessiondir</literal> and
+ <literal>proxyhostname</literal> from that file to configure
+ name of proxy host and directory of parameter files for the cf-proxy.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term>attribute <literal>server</literal></term>
<listitem>
<para>
host[:port]. That is without a method (such as HTTP) and optional
port number.
</para>
+ <note>
+ <para>
+ This setting is deprecated. Use the config_file (above)
+ to inform about the proxy server.
+ </para>
+ </note>
</listitem>
</varlistentry>
<varlistentry>
using the mkstemp(3) system call. The default value of this
setting is <literal>/tmp/cf.XXXXXX.p</literal>.
</para>
+ <note>
+ <para>
+ This setting is deprecated. Use the config_file (above)
+ to inform about the session file area.
+ </para>
+ </note>
</listitem>
</varlistentry>
</variablelist>
</varlistentry>
</variablelist>
</refsect2>
+
+ <refsect2>
+ <title>zoom</title>
+ <para>
+ The <literal>zoom</literal> element controls settings for the
+ ZOOM.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>attribute <literal>timeout</literal></term>
+ <listitem>
+ <para>
+ Is an integer that specifies, in seconds, how long an operation
+ may take before ZOOM gives up. Default value is 40.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>attribute <literal>proxy_timeout</literal></term>
+ <listitem>
+ <para>
+ Is an integer that specifies, in seconds, how long an operation
+ a proxy check will wait before giving up. Default value is 1.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
</refsect1>
<refsect1>
<title>QUERY HANDLING</title>
</para>
<para>
Step 1: for CCL, the query is converted to RPN via
- <link linkend="cclmap"><literal>cclmap</literal></link> elements part of
- the target profile as well as
+ <link linkend="zoom-torus-cclmap"><literal>cclmap</literal></link>
+ elements part of
+ the target profile as well as
<link linkend="cclmap_base">base CCL maps</link>.
</para>
<para>
<para>
Step 2: If the target is Z39.50-based, it is passed verbatim (RPN).
If the target is SRU-based, the RPN will be converted to CQL.
- If the target is SOLR-based, the RPN will be converted to SOLR's query
+ If the target is Solr-based, the RPN will be converted to Solr's query
type.
</para>
</refsect1>
-
+
<refsect1>
<title>SORTING</title>
<para>
The ZOOM module actively handle CQL sorting - using the SORTBY parameter
which was introduced in SRU version 1.2. The conversion from SORTBY clause
- to native sort for some target is driven by the two parameters:
- <link linkend="sortStrategy"><literal>sortStrategy</literal></link>
- and <link linkend="sortmap"><literal>sortmap_</literal><replaceable>field</replaceable></link>.
+ to native sort for some target is driven by the two parameters:
+ <link linkend="zoom-torus-sortStrategy">
+ <literal>sortStrategy</literal>
+ </link>
+ and <link linkend="zoom-torus-sortmap">
+ <literal>sortmap_</literal><replaceable>field</replaceable>
+ </link>.
</para>
<para>
If a sort field that does not have an equivalent
conversion. It doesn't throw a diagnostic.
</para>
</refsect1>
-
+
<refsect1>
<title>TARGET PROFILE</title>
<para>
</para>
<variablelist>
<varlistentry>
- <term>authentication</term><listitem>
+ <term id="zoom-torus-authentication">authentication</term><listitem>
<para>
Authentication parameters to be sent to the target. For
Z39.50 targets, this will be sent as part of the
- Init Request.
+ Init Request. Authentication consists of two components: username
+ and password, separated by a slash.
</para>
<para>
If this value is omitted or empty no authentication information is sent.
</para>
</listitem>
</varlistentry>
-
- <varlistentry id="cclmap">
+
+ <varlistentry>
+ <term id="zoom-torus-authenticationMode">authenticationMode</term><listitem>
+ <para>
+ Specifies how authentication parameters are passed to server
+ for SRU. Possible values are: <literal>url</literal>
+ and <literal>basic</literal>. For the url mode username and password
+ are carried in URL arguments x-username and x-password.
+ For the basic mode, HTTP basic authentication is used.
+ The settings only takes effect
+ if <link linkend="zoom-torus-authentication">authentication</link>
+ is set.
+ </para>
+ <para>
+ If this value is omitted HTTP basic authencation is used.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="zoom-torus-cclmap">
<term>cclmap_<replaceable>field</replaceable></term><listitem>
<para>
This value specifies CCL field (qualifier) definition for some
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>cfAuth</term><listitem>
<para>
</varlistentry>
<varlistentry>
- <term>cfProxy</term><listitem>
+ <term id="zoom-torus-cfproxy">cfProxy</term><listitem>
<para>
Specifies HTTP proxy for the target in the form
<replaceable>host</replaceable>:<replaceable>port</replaceable>.
</listitem>
</varlistentry>
- <varlistentry id="contentConnector">
+ <varlistentry>
+ <term id="zoom-torus-contentAuthentication">contentAuthentication</term><listitem>
+ <para>
+ Specifies authentication info to be passed to a content connector.
+ This is only used if content-user and content-password are omitted.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="zoom-torus-contentConnector">
<term>contentConnector</term><listitem>
<para>
Specifies a database for content-based proxy'ing.
<literal>element_raw</literal> from the configuration.
By default that is the element sets <literal>pz2</literal>
and <literal>raw</literal>.
- If record transform is not enabled, this setting is
+ If record transform is not enabled, this setting is
not used and the element set specified by the client
is passed verbatim.
</para>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>piggyback</term><listitem>
<para>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>queryEncoding</term><listitem>
<para>
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>recordEncoding</term><listitem>
<para>
</listitem>
</varlistentry>
- <varlistentry id="sortmap">
+ <varlistentry id="zoom-torus-sortmap">
<term>sortmap_<replaceable>field</replaceable></term><listitem>
<para>
This value the native field for a target. The form of the value is
- given by <link linkend="sortStrategy">sortStrategy</link>.
+ given by <link linkend="zoom-torus-sortStrategy">sortStrategy</link>.
</para>
</listitem>
</varlistentry>
-
- <varlistentry id="sortStrategy">
+
+ <varlistentry id="zoom-torus-sortStrategy">
<term>sortStrategy</term><listitem>
<para>
Specifies sort strategy for a target. One of:
</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>sru</term><listitem>
<para>
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="sruVersion">
+ <term>sruVersion</term><listitem>
+ <para>
+ Specifies the SRU version to use. It unset, version 1.2 will be
+ used. Some servers do not support this version, in which case
+ version 1.1 or even 1.0 could be set it.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="transform">
<term>transform</term><listitem>
<para>
Specifies a XSL stylesheet filename to be used if record
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry id="udb">
<term>udb</term><listitem>
<para>
This value is required and specifies the unique database for
<para>
The value of this field is a string that generates a dynamic link
based on record content. If the resulting string is non-zero in length
- a new field, <literal>metadata</literal> with attribute
- <literal>type="generated-url"</literal>.
+ a new field, <literal>metadata</literal> with attribute
+ <literal>type="generated-url"</literal> is generated.
The contents of this field is the result of the URL recipe conversion.
The urlRecipe value may refer to an existing metadata element by
${field[pattern/result/flags]}, which will take content
of field and perform a regular expression conversion using the pattern
given. For example: <literal>${md-title[\s+/+/g]}</literal> takes
- metadadata element <literal>title</literal> and converts one or more
+ metadata element <literal>title</literal> and converts one or more
spaces to a plus character.
</para>
- <para>
- If the <link linkend="contentConnector">contentConnector</link>
- setting also defined, the resulting value is
- augmented with a session string as well as the content proxy server.
- </para>
</listitem>
</varlistentry>
-
- <varlistentry>
+
+ <varlistentry id="zurl">
<term>zurl</term><listitem>
<para>
This is setting is mandatory and specifies the ZURL of the
<refsect1>
<title>DATABASE parameters</title>
<para>
- Extra information may be carried in the Z39.50 Datbase or SRU path,
+ Extra information may be carried in the Z39.50 Database or SRU path,
such as authentication to be passed to backend etc. Some of
the parameters override TARGET profile values. The format is
</para>
<para>
Where udb is the unique database recognised by the backend and parm1,
value1, .. are parameters to be passed. The following describes the
- supported parameters.
+ supported parameters. Like form values in HTTP the parameters and
+ values are URL encoded. The separator, though, between udb and parameters
+ is a comma rather than a question mark. What follows question mark are
+ HTTP arguments (in this case SRU arguments).
+ </para>
+ <para>
+ The database parameters, in alphabetical order, are:
</para>
- <variablelist>
+ <variablelist>
<varlistentry>
- <term>user</term>
+ <term>content-password</term>
<listitem>
<para>
- Specifies user to be passed to backend. If this parameters is
- omitted, the user will be taken from TARGET profile setting
- <literal>authentication</literal>.
+ The password to be used for content proxy session. If this parameter
+ is not given, value of parameter <literal>password</literal> is passed
+ to content proxy session.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>password</term>
+ <term>content-proxy</term>
<listitem>
<para>
- Specifies password to be passed to backend. If this parameters is
- omitted, the password will be taken from TARGET profile setting
- <literal>authentication</literal>.
+ Specifies proxy to be used for content proxy session. If this parameter
+ is not given, value of parameter <literal>proxy</literal> is passed
+ to content proxy session.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>proxy</term>
+ <term>content-user</term>
<listitem>
<para>
- Specifies proxy to be for backend. If this parameters is
- omitted, the proxy will be taken from TARGET profile setting
- <literal>cfProxy</literal>.
+ The user to be used for content proxy session. If this parameter
+ is not given, value of parameter <literal>user</literal> is passed
+ to content proxy session.
</para>
</listitem>
</varlistentry>
<term>cproxysession</term>
<listitem>
<para>
- Session ID for content proxy. This parameter is, generally,
- not used by anything but the content proxy itself.
+ Specifies the session ID for content proxy. This parameter is, generally,
+ not used by anything but the content proxy itself when invoking
+ Metaproxy via SRU.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>nocproxy</term>
+ <listitem>
+ <para>
+ If this parameter is specified, content-proxying is disabled
+ for the search.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>password</term>
+ <listitem>
+ <para>
+ Specifies password to be passed to backend. It is also passed
+ to content proxy session unless overriden by content-password.
+ If this parameter is omitted, the password will be taken from
+ TARGET profile setting
+ <link linkend="zoom-torus-authentication">
+ <literal>authentication</literal>
+ </link>
+ .
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>proxy</term>
+ <listitem>
+ <para>
+ Specifies one or more proxies for backend. If this parameter is
+ omitted, the proxy will be taken from TARGET profile setting
+ <link linkend="zoom-torus-cfproxy">
+ <literal>cfProxy</literal></link>.
+ The parameter is a list of comma-separated host:port entries.
+ Bost host and port must be given for each proxy.
</para>
</listitem>
</varlistentry>
<para>
Session realm to be used for this target, changed the resulting
URL to be used for getting a target profile, by changing the
- value that gets substituted for the %realm string.
+ value that gets substituted for the %realm string. This parameter
+ is not allowed if access is controlled by
+ <link linkend="auth_url">auth_url</link>
+ in configuration.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>retry</term>
+ <listitem>
+ <para>
+ Optional paramater. If the value is 0, retry on failure is
+ disabled for the ZOOM module. Any other value enables retry
+ on failure. If this parameter is omitted, then the value of
+ <literal>retryOnFailure</literal>
+ from the Torus record is used (same values).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>torus_url</term>
+ <listitem>
+ <para>
+ Sets the URL to be used for Torus records fetch - overriding value
+ of <literal>url</literal> attribute of element <literal>torus</literal>
+ in zoom configuration. This parameter is not allowed if access is
+ controlled by
+ <link linkend="auth_url">auth_url</link> in configuration.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>user</term>
+ <listitem>
+ <para>
+ Specifies user to be passed to backend. It is also passed
+ to content proxy session unless overriden by content-user.
+ If this parameter is omitted, the user will be taken from TARGET
+ profile setting
+ <link linkend="zoom-torus-authentication">
+ <literal>authentication</literal>
+ </link>
+ .
</para>
</listitem>
</varlistentry>
</para>
</listitem>
</varlistentry>
- </variablelist>
+ </variablelist>
</refsect1>
<refsect1>
<title>SCHEMA</title>
<literallayout><xi:include
xi:href="../xml/schema/filter_zoom.rnc"
- xi:parse="text"
+ xi:parse="text"
xmlns:xi="http://www.w3.org/2001/XInclude" />
</literallayout>
</refsect1>
-
+
<refsect1>
<title>EXAMPLES</title>
<para>
- The following configuration illustrates most of the
- facilities:
+ In example below Target definitions (Torus records) are fetched
+ from a web service via a proxy. A CQL profile is configured which
+ maps to a set of CCL fields ("no field", au, tu and su). Presumably
+ the target definitions fetched maps the CCL to their native RPN.
+ A CCL "ocn" is mapped for all targets. Logging of APDUs are enabled,
+ and a timeout is given.
<screen><![CDATA[
<filter type="zoom">
<torus
- url="http://torus.indexdata.com/src/records/?query=udb%3D%db"
+ url="http://torus.indexdata.com/src/records/?query=%query"
proxy="localhost:3128"
/>
<fieldmap cql="cql.anywhere"/>
<fieldmap cql="dc.creator" ccl="au"/>
<fieldmap cql="dc.title" ccl="ti"/>
<fieldmap cql="dc.subject" ccl="su"/>
-
+
<cclmap>
<qual name="ocn">
<attr type="u" value="12"/>
</qual>
</cclmap>
<log apdu="true"/>
+ <zoom timeout="40"/>
</filter>
]]>
</screen>
</para>
-
- </refsect1>
-
+
+ <para>
+ Here is another example with two locally defined targets: A
+ Solr target and a Z39.50 target.
+ <screen><![CDATA[
+ </filter>
+ <filter type="zoom">
+ <torus>
+ <records>
+ <record>
+ <udb>ocs-test</udb>
+ <cclmap_term>t=z</cclmap_term>
+ <cclmap_ti>u=title t=z</cclmap_ti>
+ <sru>solr</sru>
+ <zurl>ocs-test.indexdata.com/solr/select</zurl>
+ </record>
+ <record>
+ <udb>loc</udb>
+ <cclmap_term>t=l,r</cclmap_term>
+ <cclmap_ti>u=4 t=l,r</cclmap_ti>
+ <zurl>lx2.loc.gov:210/LCDB</zurl>
+ </record>
+ </records>
+ </torus>
+ <fieldmap cql="cql.serverChoice"/>
+ <fieldmap cql="dc.title" ccl="ti"/>
+ </filter>
+]]>
+ </screen>
+ </para>
+ </refsect1>
+
<refsect1>
<title>SEE ALSO</title>
<para>
</citerefentry>
</para>
</refsect1>
-
+
©right;
</refentry>
projects / metaproxy-moved-to-github.git / blobdiff