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="http://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>
|