About

Relay plugin passes Pazpar2 commands through to Pazpar2 and configures Pazpar2 for the request through a variety of configuration mechanisms.

Protocol

Request/Response semantics and syntax are a superset of Pazpar2 with the exception of Pazpar2's session parameter which is omitted for the Service Proxy (relay does it's own session management and tracking).

Commands init and settings (in MODE 2 and 3) may be ignored.

For more about pazpar2 protocol see: Pazpar2 manual

Following extensions to the pazpar2 protocol can be applied when making requests to the Relay plugin: "torusquery","recordfilter","windowid","recordquery"

Protocol extensions

recordquery

recordquery is an extension to pazpar2's record command. With pazpar2 one can request a record from a current search by providing a record id:

command=record&id=a-record-id

With Service Proxy, this request can be extended with a record query which will then be used by the Service Proxy to bootstrap a search to request the record from. This way it becomes possible to ask for a given record without having a previous search context.

The query should be as distinct as possible. It could be a title/author search:

command=record&id=a-record-id&recordquery=au="an author" and ti="a title"

The value of the recordquery parameter must be URL encoded.

Configuration

This plug-in is configured in service-proxy.properties or equivalent.

Registration

Plugin class is registered with the following (name is arbitrary):

plugins.relay = com.indexdata.serviceproxy.plugins.Pazpar2RelayPlugin

Properties

PROXY_MODE

1 - Generic proxy, requires a statically configured pazpar2 to work and does not use authentication
2 - No authentication but a target torus is required to dynamically configure pazpar2
3 - Authentication enabled, target torus required for authentication and configuration

Mandatory, no default

Example:

    relay.PROXY_MODE = 3

TORUS_BASEURL

The address at which to obtain targets for configuration of pazpar2

Mandatory, no default

Example:

    relay.TORUS_BASEURL = http://some-server/torus/searchable

PAZPAR2_URL

The address at which Pazpar2 is listening for requests

Mandatory, no default

Example:

  relay.PAZPAR2_URL = http://some-server:someport/search.pz2

USE_OPAQUE_ID

Controls what record (torus) field should be used for indexing records in pazpar2. The default value "no" uses 'zurl' field as the ID source. Other values include: "yes" (the 'id' field is used) and "udb" (the 'udb' field is used). "udb" is the recommended setting as it gives cleanest and most stable identifiers, however, all records must include the 'udb' field in this mode or the target will be ignored (some installations may be missing udb fields).

Optional, default "no"

Example:

  relay.USE_OPAQUE_ID = udb

PAZPAR2_SERVICE_ID

Refers to a specific service id in Pazpar2's configuration (pazpar2.cfg) If not specified the default service (unnamed) will be used.

PAZPAR2_SERVICE_ID and PAZPAR2_SERVICE_XML are mutually exclusive. If both are specified here, PAZPAR2_SERVICE_XML will take precedence.

Optional

Example:

    relay.PAZPAR2_SERVICE_ID = service-identifier

PAZPAR2_SERVICE_XML

The name of a file containing service definitions for pazpar2. The file should reside in the same directory as the configuration file. See also comments under PAZPAR2_SERVICE_ID.

Optional

Example:

    relay.PAZPAR2_SERVICE_XML = some-host-service.xml

CF_ENGINE_ADDRESS

If set to a host and a port, this parameter will be used to override what CF engine to use for CF based targets, replacing the address that each CF target would be configured with from the Torus for instance.

Optional

Example:

    relay.CF_ENGINE_ADDRESS = localhost:9003

PARSE_RESPONSE

Enable or disable parsing Pazpar2 XML responses. 'yes' may slow down relay operation but is required if there is any post-processing further down the chain (e.g ACE).

Optional, default false

Example:

  relay.PARSE_RESPONSES = true

TORUS_REALM

Only in proxy mode 2, specific Torus realm to fetch target configuration from.

Mandatory in mode 2

Example:

    relay.TORUS_REALM = *

TORUS_PARAMS

Only in proxy mode 2, specific Torus params send when fetching target configuration.

Optional, in mode 2

Example:

  relay.TORUS_PARAMS = ?param1=value1

USE_TURBO_MARC

Only in proxy mode 2 and 3, enables or disables use of TurboMARC by overriding the "pz:nativesyntax" to "tmarc" for MARC21/OPAC targets. Possible values "yes" and "no".

Optional, default "yes", in mode 2 and 3 only

Example:

  relay.USE_TURBO_MARC = no

STREAMBUFF_SIZE

Size of the proxying buffer. Change only if you know what you are doing.

Mandatory, no default

Example:

  relay.STREAMBUFF_SIZE = 4096

CCLMAP_TERM, CCLMAP_SU, CCLMAP_AU, CCLMAP_TI, CCLMAP_JT, CCLMAP_DATE etc

Fallbacks for the CCL field maps, used in cases where the target profile record is missing required mapping information. Can be also used to map author/title/subject searches to keyword (eg "u=1016 t=l,r s=al") in cases when target do not support them natively.

Optional, sane defaults

Example:

Map title and author searches to keyword for targets that do not support them at all:

  relay.CCLMAP_AU = u=1016 t=l,r s=al
  relay.CCLMAP_TI = u=1016 t=l,r s=al
  relay.CCLMAP_SU = u=1016 t=l,r s=al

SERIALIZE_REQUESTS

Instructs Relay plugin to process pazpar2 requests sequentially if set to "true". The default is to process requests concurrently. Setting this parameter might help in case of concurrency issues with requests, potentially at some performance cost.

Optional, default false 

  relay.SERIALIZE_REQUESTS = true