SRU (Search/Retrieval Using URL)

SRU

Explain Operation

The Explain operation allows a client to retrieve a description of the facilities available at an SRU server. It can then be used by the client to self-configure and provide an appopriate interface to the user. The record is in XML and follows the ZeeRex Schema.

There are two methods for getting the explain record:

  • Via the SRU Explain Operation. 
  • Via the http GET request at the base URL for the service (no parameters).
    This can be considered an SRU request (and hence have a default recordPacking of 'xml'), with no extraRequestData and leaving it up to the server to determine the version of the response.
    Otherwise, the response is identical to an SRU explainResponse message.

PARAMETERS

Request Parameters

Name Mandatory/Optional? Description
operation Mandatory The string: 'explain'.
version Mandatory The version of the request, and a statement by the client that it wants the response to be less than, or preferably equal to, that version. See Versions.
recordPacking Optional A string to determine how the explain record should be escaped in the response. Defined values are 'string' and 'xml'. The default is 'xml'. See Records.
stylesheet Optional A URL for a stylesheet. The client requests that the server simply return this URL in the response. See Stylesheets.
extraRequestData Optional Provides additional information for the server to process. See Extensions.

Response Parameters

Name Type Mandatory? Description
version xsd:string Mandatory The version of the response. This MUST be less than or equal to the version requested by the client.
>> See Versions.
record record Mandatory A single Explain record, wrapped in the record metadata fields. >> See Records.
extraResponseData xmlFragment Optional Additional information returned by the server.
>> See Extensions.
echoedExplainRequest <echoedExplainRequest> Optional The request parameters echoed back to the client in a simple XML form. >> See Echoing the Request.

ZEEREX FOR SRU

ZeeRex/SRU Summary:

  • The protocol attribute on the serverInfo element MUST have the value: SRU
  • The transport attribute on the serverInfo element MUST be one of: http or https
  • The method attribute on the serverInfo element MUST be a space separated list, comprising any number of the following values: GET POST SOAP
  • The database element within serverInfo MUST contain the path section of the URL to the server, without the first / and up to the ?
  • The set element within indexInfo is used to define the short names of context sets.
  • Indexes are described by including the name of the index in the name element within map, and the short name for the context set in the set attribute on that element.
  • The schemaInfo section is used to described the schemas supported by the server.

ZEEREX Specification

EXAMPLES

The following URLs would all retrieve the explain document:

http://myserver.com/cgi/mysru?operation=explain&version=1.1&recordPacking=xml
http://myserver.com/cgi/mysru?
http://myserver.com/cgi/mysru

The corresponding response from the server would be:

<sru:explainResponse xmlns:sru="//www.loc.gov/zing/srw/">
 <sru:version>1.1</sru:version>
 <sru:record>
   <sru:recordPacking>XML</sru:recordPacking>
   <sru:recordSchema>http://explain.z3950.org/dtd/2.1/</sru:recordSchema>
   <sru:recordData>

   <zr:explain xmlns:zr="http://explain.z3950.org/dtd/2.1/">
     <zr:serverInfo protocol="SRU" version="1.2" transport="http"
                    method="GET POST SOAP">
        <zr:host>myserver.com</zr:host>
        <zr:port>80</zr:port>
        <zr:database>cgi/mysru</zr:database>
     </zr:serverInfo>
     <zr:databaseInfo>
       <title lang="en" primary="true">SRU Test Database</title>
     </zr:databaseInfo>
     <zr:indexInfo>
       <zr:set name="dc" identifier="info:srw/cql-context-set/1/dc-v1.1"/>
        <zr:index>
          <zr:map><zr:name set="dc">title</zr:name></zr:map>
        </zr:index>
     </zr:indexInfo>
     <zr:schemaInfo>
        <zr:schema name="dc" identifier="info:srw/schema/1/dc-v1.1">
          <zr:title>Simple Dublin Core</zr:title>
        </zr:schema>
     </zr:schemaInfo>
     <zr:configInfo>
         <zr:default type="numberOfRecords">1</zr:default>
         <zr:setting type="maximumRecords">50</zr:setting>
         <zr:supports type="proximity"/>
     </zr:configInfo>
    </zr:explain>

   </sru:recordData>
 </sru:record>
</sru:explainResponse>

 

Additional Zeerex Examples