X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fzoom.xml;h=b80df073130548b33af924fc2fcedd3cfdb3f15a;hb=30006392c5d236b5da322842855bd246b2ccfdd8;hp=253be8f6e31aad1db234276da4bffeb044a10338;hpb=2a22abb08a31fd2ce7343b26fdcb045bd8e42199;p=metaproxy-moved-to-github.git diff --git a/doc/zoom.xml b/doc/zoom.xml index 253be8f..b80df07 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -9,7 +9,7 @@ Metaproxy Index Data - + zoom 3mp @@ -21,14 +21,15 @@ Metaproxy ZOOM Module - DESCRIPTION + + DESCRIPTION This filter implements a generic client based on ZOOM of YAZ. The client implements the protocols that ZOOM C does: Z39.50, SRU (GET, POST, SOAP) and SOLR . - + This filter only deals with Z39.50 on input. The following services are supported: init, search, present and close. The backend target @@ -52,273 +53,562 @@ - CONFIGURATION - - The configuration consists of three parts: torus, - fieldmap and cclmap. - + + CONFIGURATION + + The configuration consists of five parts: torus, + fieldmap, cclmap, + contentProxy and log. + + + torus - The torus element specifies target profiles - and takes the following content: + 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 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. - - - + + 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. + + + The special sequence %realm is replaced by value + of attribute realm or by realm DATABASE argument. + + + + + attribute realm + + + The default realm value. Used for %realm in URL, unless + specified in DATABASE argument. + + + + + 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 - The fieldmap may be specified zero or more times and - specifies the map from CQL fields to CCL fields and takes the - following content: + The fieldmap may be specified zero or more times and + specifies the map from CQL fields to CCL fields and takes the + following content: - - attribute cql - - - CQL field that we are mapping "from". - - - - - attribute ccl - - - CCL field that we are mapping "to". - - - + + attribute cql + + + CQL field that we are mapping "from". + + + + + attribute ccl + + + CCL field that we are mapping "to". + + + + + + cclmap - The final part of the configuration consists of zero or more - cclmap elements that specifies a base - CCL profile to be used for all targets. This configuration, thus, will - be combined with cclmap-definitions from the target profile. + The third part of the configuration consists of zero or more + cclmap elements that specifies + base CCL profile to be used for all targets. + This configuration, thus, will be combined with cclmap-definitions + from the target profile. - - QUERIES + + + contentProxy - The ZOOM filter accepts three query types: RPN(Type-1), CCL and - CQL. + 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 - Queries are converted in two separate steps. In the first step - the input query is converted to RPN/Type-1. This is always - the common internal format between step 1 and step 2. - 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 CCL, the query is converted to RPN via - cclmap elements part of the target profile. - - - Step 1: For CQL, the query is converted to CCL. The mappings of - CQL fields to CCL fields are handled by fieldmap - elements as part of the target profile. The resulting query, CCL, - is the converted to RPN using the schema mentioned earlier (via - cclmap). - - - 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 - type. - - - - 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 log element controls logging for the + ZOOM filter. - - authentication - - Authentication parameters to be sent to the target. For - Z39.50 targets, this will be sent as part of the - Init Request. - - - If this value is omitted or empty, not authentication information - is simply omitted. - - - + + 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 + + The ZOOM filter accepts three query types: RPN(Type-1), CCL and + CQL. + + + Queries are converted in two separate steps. In the first step + the input query is converted to RPN/Type-1. This is always + the common internal format between step 1 and step 2. + In step 2 the query is converted to the native query type of 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 + cclmap elements part of + the target profile as well as + base CCL maps. + + + Step 1: For CQL, the query is converted to CCL. The mappings of + CQL fields to CCL fields are handled by + fieldmap + elements as part of the target profile. The resulting query, CCL, + is the converted to RPN using the schema mentioned earlier (via + cclmap). + + + 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 + type. + + + + + 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 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: + + + + authentication + + Authentication parameters to be sent to the target. For + Z39.50 targets, this will be sent as part of the + Init Request. + + + If this value is omitted or empty no authentication information is sent. + + + + + + cclmap_field + + 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). + + + + + + cfAuth + + 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. + + + - - 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). - - - + + cfProxy + + Specifies HTTP proxy for the target in the form + host:port. + + + - - 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. - - - + + cfSubDB + + Specifies sub database for a Connector Framework based target. + + + - - udb - - This value is required and specifies the unique database for - this profile . All target profiles should hold a unique database. - - - + + contentConnector + + Specifies a database for content-based proxy'ing. + + + - - cclmap_* - - 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). - - - + + elementSet + + Specifies the elementSet to be sent to the target if record + transform is enabled (not to be confused' with the record_transform + module). The record transform is enabled only if the client uses + record syntax = XML and a element set determined by + the element_transform / + element_raw from the configuration. + By default that is the element sets pz2 + and raw. + If record transform is not enabled, this setting is + not used and the element set specified by the client + is passed verbatim. + + + - - elementSet - - Specifies the elementSet to be sent to the target if record - transform is enabled (not to be confused' with the record_transform - module). The record transform is enabled only if the client uses - record syntax = XML and a element set determined by - the element_transform / - element_raw from the configuration. - By default that is the element sets pz2 - and raw. - If record transform is not enabled, this setting is - not used and the element set specified by the client - is passed verbatim. - - - + + 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 + by the target. This is primarily used for targets were records + are not UTF-8 encoded already. This setting is only used + if the record transform is enabled (see description of elementSet). + + + - - recordEncoding - - Specifies the character encoding of records that are returned - by the target. This is primarily used for targets were records - are not UTF-8 encoded already. This setting is only used - if the record transform is enabled (see description of elementSet). - - - + + requestSyntax + + Specifies the record syntax to be specified for the target + if record transform is enabled; see description of elementSet. + If record transform is not enabled, the record syntax of the + client is passed verbatim to the target. + + + - - requestSyntax - - Specifies the record syntax to be specified for the target - if record transform is enabled; see description of elementSet. - If record transform is not enabled, the record syntax of the - client is passed verbatim to the target. - - - + + sortmap_field + + This value the native field for a target. The form of the value is + given by sortStrategy. + + + + + + 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 + based and must be one of : get, + post, soap + or solr. + + + - - sru - - If this setting is set, it specifies that the target is web service - based and must be one of : get, - post, soap - or solr. - - - + + transform + + Specifies a XSL stylesheet filename 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. + + + - - transform - - Specifies a XSL stylesheet filename to be used if record - transform is anabled; see desciprion of elementSet. - The XSL transform is only used if the element set is set to the - value of element_transform in the configuration. - - - + + udb + + This value is required and specifies the unique database for + this profile . All target profiles should hold a unique database. + + + - - zurl - - This is setting is mandatory and specifies the ZURL of the - targetin the form of host/database. - - - - + + urlRecipe + + 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, 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 also defined, the resulting value is + augmented with a session string as well as the content proxy server. + + + + + + zurl + + This is setting is mandatory and specifies the ZURL of the + target in the form of host/database. The HTTP method should + not be provided as this is guessed from the "sru" attribute value. + + + + + + + DATABASE parameters + + Extra information may be carried in the Z39.50 Datbase or SRU path, + such as authentication to be passed to backend etc. Some of + the parameters override TARGET profile values. The format is + + + udb,parm1=value1&parm2=value2&... + + + Where udb is the unique database recognised by the backend and parm1, + value1, .. are parameters to be passed. The following describes the + supported parameters. + + + + user + + + Specifies user to be passed to backend. If this parameters is + omitted, the user will be taken from TARGET profile setting + authentication. + + + + + password + + + Specifies password to be passed to backend. If this parameters is + omitted, the password will be taken from TARGET profile setting + authentication. + + + + + proxy + + + Specifies proxy to be for backend. If this parameters is + omitted, the proxy will be taken from TARGET profile setting + cfProxy. + + + + + cproxysession + + + Session ID for content proxy. This parameter is, generally, + not used by anything but the content proxy itself. + + + + + realm + + + 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. + + + + + x-parm + + + All parameters that has prefix x, dash are passed verbatim + to the backend. + + + + - SCHEMA - - + + SCHEMA + + - EXAMPLES + + EXAMPLES The following configuration illustrates most of the facilities: @@ -326,7 +616,7 @@ @@ -340,14 +630,16 @@ + ]]> - + - SEE ALSO + + SEE ALSO metaproxy @@ -367,15 +659,7 @@