From c03baef23be97fa40de8b65e46a3fdde9469effa Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Mon, 17 Oct 2011 13:36:42 +0200 Subject: [PATCH] zoom: document all settings --- doc/zoom.xml | 384 +++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 260 insertions(+), 124 deletions(-) diff --git a/doc/zoom.xml b/doc/zoom.xml index ead2029..a971125 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -56,80 +56,81 @@ CONFIGURATION - The configuration consists of four parts: torus, - fieldmap, cclmap - and log. + The configuration consists of five parts: torus, + fieldmap, cclmap, + contentProxy and log. - torus - - The torus element specifies target profiles - and takes the following content: - - - - attribute url - - - URL of Web service to be used to fetch target profile - for a given database (udb). The special sequence - %db of the URL is replaced by the - actual database specified as part of Search. - - - - - attribute proxy - - - HTTP proxy to bse used for fetching target profiles. - - - - - attribute xsldir - - - Directory that is searched for XSL stylesheets. Stylesheets - are specified in the target profile by the - transform element. - - - - - attribute element_transform - - - Specifies the element that triggers retrieval and transform using - the parameters elementSet, recordEncoding, requestSyntax, transform - from the target profile. Default value - is "pz2", due to the fact that for historical reasons the - common format is that used in Pazpar2. - - - - - attribute element_raw - - - Specifies an element that triggers retrieval using the - parameters elementSet, recordEncoding, requestSyntax from the - target profile. Same actions as for element_transform, but without - the XSL transform. Useful for debugging. - The default value is "raw". - - - - - element records - - - Local target profiles. This element may includes zero or - more record elements (one per target - profile). See section TARGET PROFILE. - - - - + + torus + + The torus element specifies target profiles + and takes the following content: + + + + attribute url + + + URL of Web service to be used to fetch target profile + for a given database (udb). The special sequence + %db of the URL is replaced by the + actual database specified as part of Search. + + + + + attribute proxy + + + HTTP proxy to bse used for fetching target profiles. + + + + + attribute xsldir + + + Directory that is searched for XSL stylesheets. Stylesheets + are specified in the target profile by the + transform element. + + + + + attribute element_transform + + + Specifies the element that triggers retrieval and transform using + the parameters elementSet, recordEncoding, requestSyntax, transform + from the target profile. Default value + is "pz2", due to the fact that for historical reasons the + common format is that used in Pazpar2. + + + + + attribute element_raw + + + Specifies an element that triggers retrieval using the + parameters elementSet, recordEncoding, requestSyntax from the + target profile. Same actions as for element_transform, but without + the XSL transform. Useful for debugging. + The default value is "raw". + + + + + element records + + + Local target profiles. This element may includes zero or + more record elements (one per target + profile). See section TARGET PROFILE. + + + + fieldmap @@ -166,28 +167,60 @@ This configuration, thus, will be combined with cclmap-definitions from the target profile. - - - log - - The log element controls logging for the - ZOOM filter. - - - - attribute apdu - - - If the value of apdu is "true", then protocol packages - (APDUs and HTTP packages) from the ZOOM filter will be - logged to the yaz_log system. A value of "false" will - not perform logging of protocol packages (the default - behavior). - - - - - + + + contentProxy + + The contentProxy element controls content proxy'in. + This section + is optional and must only be defined if content proxy'ing is enabled. + + + + attribute server + + + Specifies the content proxy host. The host is of the form + host[:port]. That is without a method (such as HTTP) and optional + port number. + + + + + attribute tmp_file + + + Specifies a filename of a session file for content proxy'ing. The + file should be an absolute filename that includes + XXXXXX which is replaced by a unique filename + using the mkstemp(3) system call. The default value of this + setting is /tmp/cf.XXXXXX.p. + + + + + + + log + + The log element controls logging for the + ZOOM filter. + + + + attribute apdu + + + If the value of apdu is "true", then protocol packages + (APDUs and HTTP packages) from the ZOOM filter will be + logged to the yaz_log system. A value of "false" will + not perform logging of protocol packages (the default + behavior). + + + + + QUERY HANDLING @@ -202,7 +235,7 @@ In step 2 the query is converted to the native query type of the target. - Step 1: for RPN, the query is passed unmodified to the target. + Step 1: for RPN, the query is passed un-modified to the target. Step 1: for CCL, the query is converted to RPN via @@ -226,16 +259,28 @@ SORTING - + 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: + sortStrategy + and sortmap_field. + + + If a sort field that does not have an equivalent + sortmap_-mapping is passed un-modified through the + conversion. It doesn't throw a diagnostic. TARGET PROFILE - The following elements are honored by the ZOOM module of Metaproxy. - Note that unknown elements are silently ignored. There are several - elements in use that makes no sense to the ZOOM module. + The ZOOM module is driven by a number of settings that specifies how + to handle each target. + Note that unknown elements are silently ignored. + + + The elements, in alphabetical order, are: @@ -246,54 +291,59 @@ Init Request. - If this value is omitted or empty, not authentication information - is simply omitted. + If this value is omitted or empty no authentication information is sent. - piggyback + cclmap_* - A value of 1/true is a hint to the ZOOM module that this Z39.50 - target supports piggyback searches, ie Search Response with - records. Any other value (false) will prevent the ZOOM module - to make use of piggyback (all records part of Present Response). + This value specifies CCL field (qualifier) definition for some + field. For Z39.50 targets this most likely will specify the + mapping to a numeric use attribute + a structure attribute. + For SRU targets, the use attribute should be string based, in + order to make the RPN to CQL conversion work properly (step 2). - queryEncoding + cfAuth - If this value is defined, all queries will be converted - to this encoding. This should be used for all Z39.50 targets that - do not use UTF-8 for query terms. + When cfAuth is defined, its value will be used as authentication + to backend target and authentication setting will be specified + as part of a database. This is like a "proxy" for authentication and + is used for Connector Framework based targets. - + - udb + cfProxy - This value is required and specifies the unique database for - this profile . All target profiles should hold a unique database. + Specifies HTTP proxy for the target in the form + host:port. - + - cclmap_* + cfSubDb - This value specifies CCL field (qualifier) definition for some - field. For Z39.50 targets this most likely will specify the - mapping to a numeric use attribute + a structure attribute. - For SRU targets, the use attribute should be string based, in - order to make the RPN to CQL conversion work properly (step 2). + Specifies sub database for a Connector Framework based target. - + + + contentConnector + + Specifies a database for content-based proxy'ing. + + + + elementSet @@ -313,6 +363,41 @@ + literalTransform + + Specifies a XSL stylesheet to be used if record + transform is anabled; see description of elementSet. + The XSL transform is only used if the element set is set to the + value of element_transform in the configuration. + + + The value of literalTransform is the XSL - string encoded. + + + + + + piggyback + + A value of 1/true is a hint to the ZOOM module that this Z39.50 + target supports piggyback searches, ie Search Response with + records. Any other value (false) will prevent the ZOOM module + to make use of piggyback (all records part of Present Response). + + + + + + queryEncoding + + If this value is defined, all queries will be converted + to this encoding. This should be used for all Z39.50 targets that + do not use UTF-8 for query terms. + + + + + recordEncoding Specifies the character encoding of records that are returned @@ -335,6 +420,27 @@ + sortmap_ + + This value the native field for a target. + + + + + + sortStrategy + + Specifies sort strategy for a target. One of: + z3950, type7, + cql, sru11 or + embed. The embed chooses type-7 + or CQL sortby depending on whether Type-1 or CQL is + actually sent to the target. + + + + + sru If this setting is set, it specifies that the target is web service @@ -349,7 +455,7 @@ transform Specifies a XSL stylesheet filename to be used if record - transform is anabled; see desciprion of elementSet. + transform is anabled; see description of elementSet. The XSL transform is only used if the element set is set to the value of element_transform in the configuration. @@ -357,6 +463,36 @@ + udb + + This value is required and specifies the unique database for + this profile . All target profiles should hold a unique database. + + + + + + urlRecipe + + The value of this field is a string that generates a dynamic link + based on content. If the resulting string is non-zero in length + a new field, metadata with attribute + type=generated-url. 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: ${md-title[\s+/+/g]} takes + metadadata element title and converts one or more + spaces to a plus character. + + + If the contentConnector setting is defined the resulting value is + agmented with a session string as well as the content proxy server. + + + + + zurl This is setting is mandatory and specifies the ZURL of the -- 1.7.10.4