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">
7 <refentry id="ref-zoom">
9 <productname>Metaproxy</productname>
10 <info><orgname>Index Data</orgname></info>
14 <refentrytitle>zoom</refentrytitle>
15 <manvolnum>3mp</manvolnum>
16 <refmiscinfo class="manual">Metaproxy Module</refmiscinfo>
20 <refname>zoom</refname>
21 <refpurpose>Metaproxy ZOOM Module</refpurpose>
24 <refsect1><title>DESCRIPTION</title>
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 .
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.
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
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.
55 <refsect1><title>CONFIGURATION</title>
57 The configuration consists of three parts: <literal>torus</literal>,
58 <literal>fieldmap</literal> and <literal>cclmap</literal>.
61 The <literal>torus</literal> element specifies target profiles
62 and takes the following content:
66 <term>attribute <literal>url</literal></term>
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.
76 <term>attribute <literal>xsldir</literal></term>
78 Directory that is searched for XSL stylesheets. Stylesheets
79 are specified in the target profile by the
80 <literal>transform</literal> element.
85 <term>attribute <literal>element_transform</literal></term>
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.
96 <term>attribute <literal>element_raw</literal></term>
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".
106 <term>element <literal>records</literal></term>
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.
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
122 <term>attribute <literal>cql</literal></term>
125 CQL field that we are mapping "from".
130 <term>attribute <literal>ccl</literal></term>
133 CCL field that we are mapping "to".
139 The final part of the configuration consists of zero or more
140 <literal>cclmap</literal> elements that specifies <emphasis>base</emphasis>
141 CCL profile to be used for all targets. This configuration, thus, will
142 be combined with cclmap-definitions from the target profile.
145 <refsect1><title>QUERIES</title>
147 The ZOOM filter accepts three query types: RPN(Type-1), CCL and
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.
157 Step 1: for RPN, the query is passed unmodified to the target.
160 Step 1: for CCL, the query is converted to RPN via
161 <literal>cclmap</literal> elements part of the target profile.
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>).
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
178 <refsect1><title>TARGET PROFILE</title>
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.
186 <term>authentication</term><listitem>
188 Authentication parameters to be sent to the target. For
189 Z39.50 targets, this will be sent as part of the
193 If this value is omitted or empty, not authentication information
200 <term>piggyback</term><listitem>
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).
211 <term>queryEncoding</term><listitem>
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.
221 <term>udb</term><listitem>
223 This value is required and specifies the unique database for
224 this profile . All target profiles should hold a unique database.
230 <term>cclmap_*</term><listitem>
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).
242 <term>elementSet</term><listitem>
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
260 <term>recordEncoding</term><listitem>
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).
271 <term>requestSyntax</term><listitem>
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.
282 <term>sru</term><listitem>
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>.
293 <term>transform</term><listitem>
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.
304 <term>zurl</term><listitem>
306 This is setting is mandatory and specifies the ZURL of the
307 targetin the form of host/database.
313 <refsect1><title>SCHEMA</title>
314 <literallayout><xi:include
315 xi:href="../xml/schema/filter_zoom.rnc"
317 xmlns:xi="http://www.w3.org/2001/XInclude" />
321 <refsect1><title>EXAMPLES</title>
323 The following configuration illustrates most of the
328 url="http://torus.indexdata.com/src/records/?query=udb%3D%db"
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"/>
339 <attr type="u" value="12"/>
340 <attr type="s" value="107"/>
350 <refsect1><title>SEE ALSO</title>
353 <refentrytitle>metaproxy</refentrytitle>
354 <manvolnum>1</manvolnum>
359 <refentrytitle>virt_db</refentrytitle>
360 <manvolnum>3mp</manvolnum>
368 <!-- Keep this comment at the end of the file
373 sgml-minimize-attributes:nil
374 sgml-always-quote-attributes:t
377 sgml-parent-document:nil
378 sgml-local-catalogs: nil
379 sgml-namecase-general:t