Common ParametersVersionIn any actively developed protocol or piece of software, there is a concern about interoperability between different versions. In SRU, there is an explicit interoperability mechanism, with precisely defined semantics. The mechanism defined allows for clients and servers using different versions to interact without protocol level errors. Versions of SRU will always be recorded as strings of the format 'major.minor' where major and minor are independent integers. Operations All SRU operations have a version parameter, with the exception of the parameterless form of the explain request. For example: http://z3950.loc.gov:7090/voyager?version=1.2&operation=searchRetrieve&query=dinosaur
The version parameter on a request both indicates the version of the
request and is a statement by the client that it wants the response to
be less than, or preferably equal to, that version. The version parameter
in the response message is the version of the response. If the server
cannot supply a response in that version or lower, then it must return
a diagnostic. If possible this diagnostic would be in the version requested
or lower, but that is not a requirement. Here are some examples of how
this works in practice. If a 2.0 client asks a 1.1 server for a 2.0 response,
then the server is able to respond with a 1.1 response as it is lower
than version 2.0. If a 1.1 client asks a 2.0 server for a 1.1 response
then the server is able to reduce its response version to accomodate
the client. If a 1.1 client asks a 1.1 server for a 1.1 response, then
there is no version mismatch and the server is able to accomodate the
request. Version 1.0 Version 1.0 was an experiment, and has been officially
deprecated. The version 1.0 implementation trial was very useful informing
the development of version 1.1, the first non-experimental version. Version
1.0 does not have a version parameter in any of the requests or responses
and hence cannot be considered to be part of this version interoperability
system. If a client requests version 1.0, then the server may return
a 1.0 response but is under no obligation to do so.Version Documentation
and Changes Documentation for all versions of SRU will be maintained
such that server and client authors are able to track changes between
versions. A summary document of changes between versions will also be
maintained. This version interoperability solution will only work so
long as there are no additional mandatory parameters added to a request,
and as such the SRU editorial board will endeavor to only ever add optional
elements. If there is a requirement to add a mandatory parameter to a
request, then this will be announced with as much prior warning as possible. While only the documentation for the most recent version of the protocol
is maintained, the changes between versions are listed below. Note that
although version 1.0 is officially abandoned, the changes from 1.0 to
1.1 are listed, for the benefit of those who have already implemented
1.0. >> Changes between Versions StylesheetsIn order to render the response, "thin" clients may provide a stylesheet to turn the response XML into a natively renderable format, often HTML or XHTML. This allows a web browser, or other application capable of rendering stylesheets, to act as a dedicated client without requiring any further application logic. The echoedRequest parameter on the response enables a client to use this stylesheet to also have the request it just made available without any client side logic. OperationsAll operations, other than the parameterless explain request, have the stylesheet parameter. The value of the parameter is the URL of the stylesheet to be included in the response. This URL is to be included in the href attribute of the xml-stylesheet processing instruction before the response xml. It is likely that the type will be XSL, but not necessarily. If the server cannot fulfill this request it must supply a diagnostic. This parameter may not be used with SRU via SOAP. It is a SOAP error to return a stylesheet, and hence an error to request one. If this parameter is not supplied, then the server can, at its discretion, include a default stylesheet. The default stylesheet URL may be included in the explain document. For example, upon receiving the request ... http://z3950.loc.gov:7090/voyager?version=1.2&operation=searchRetrieve
&stylesheet=/master.xsl&query=dinosaur ...the server must include the following as beginning of the response: <?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="/master.xsl"?> <sru:searchRetrieveResponse ... Echoing the RequestVery thin clients, such as a web browser with a stylesheet as above, may not have the facility to record the query that generated the response it has just received. In order to prevent clients having to maintain this information, the server may echo the request back to the client along with the response. OperationsThere are no request elements associated with this functionality. There is one response element per operation in which the request is echoed. The name of this is the name of the response element, prefixed by echoed. The parameters are rendered into XML, as per the SRU over SOAP request.xQuery xQuery is an additional parameter for searchRetrieve and scan, which has the query rendered in XCQL. This has two benefits:
baseUrlA server can include is own base URL in the echoed request. This allows the client to easily reconstruct queries by simple concatenation, or retrieve the explain document to fetch additional information such as the title and description to include in the results presented to the user. For example: <echoedSearchRetrieveRequest>
<version>1.2</version> <query>dc.title = dinosaur</query> <recordSchema>mods</recordSchema> <xQuery> <searchClause xmlns="http://www.loc.gov/zing/cql/xcql/"> <index>dc.title</index> <relation> <value>=</value> </relation> <term>dinosaur</term> </searchClause> </xQuery> <baseUrl>http://z3950.loc.gov:7090/voyager</baseUrl> </echoedSearchRetrieveRequest> Extensions(see also Extra Data.) http://z3950.loc.gov:7090/voyager?...&x-info4-onSearchFail=scan
Note that this convention does not guarantee uniqueness since the parameter name will not include a full URI. The extension owner should try to make the name as unique as possible. If the namespace is identified by an 'info:srw' URI, then the recommended convention is to name the parameter "x-infoNNN-XXX" where NNN is the 'info:srw' authority string, and XXX is the name of the parameter. Extension names MUST never be assigned with this form except by the proper authority for the given 'info' namespace. Response Every response has an extraResponseData section. This section can include any well-formed XML, and hence servers can include namespaced XML fragments within it in order to convey information back to the client. The extension MUST supply a namespace and the element names with which to do this, if feedback to the client is necessary. For example: <sru:extraResponseData> SRU via SOAPFor SRU via SOAP, the extension parameters are XML structures. The request parameters are identified by their full namespace, and the name of the parameter is the name of the XML element. Even if there is only one piece of additional information supplied, it must be within a namespaced XML element. This is in order to ensure that servers can distinguish a parameter from one extension from another. For example: <extraRequestData> Semantics: If the server does not understand a piece of information in an extension parameter, it may silently ignore it. This is unlike many other request parameters, where if the server does not implement that particular feature it MUST respond with a diagnostic. If the particular request requires some confirmation that it has been carried out rather than ignored, then the profile designer should include a field in the response. The semantics of parameters in the request may not be modified by extensions. For example, a x-qt-queryType parameter could not change query to be an SQL query, as a server that does not understand the extension would expect the query to be in CQL, and thus be unable to parse it. Instead, the extension should create a new parameter for the SQL query. The semantics of parts of the response may be modified by extensions. It would be possible (though very strange), for example, to replace the recordSchema field in the record structure with your favorite chocolate cookie recipe when the client sends a x-ct-cookieType request parameter. The response semantics may be changed in this way only if the client specifically requests the change. Clients should also expect to receive the regular semantics, as servers are at liberty to ignore extensions, and hence it is recommended that this not be done. ExtraResponseData may be sent that is not directly associated with the request. For example it may contain cost information regarding the query or information on the server or database supplying the results. This data must, however, have been requested. As the request may be echoed, the server must be able to transform the parameters into their XML form. If it encounters an unrecognised parameter, the server may either make its best guess as to how to transform the parameter, or simply not return it at all. It should not, however, add an undefined namespace to the element as this would invalidate the response. If the contents of the parameter is an XML structure, then the extension designer should also specify how to encode this structure in a URL. This may simply be to escape all of the special characters, but the designer could also create a string encoding form with rules as to how to generate the XML in much the same fashion as the relationship between CQL and XCQL. Record, Term and Query ExtensionsIn addition to extra information being included at the top level of the response, there are three further elements in which information can be returned. These are:
<record>
<recordSchema>info:srw/schema/1/dc-v1.1</recordSchema> <recordPacking>xml</recordPacking> <recordData>...</recordData> <recordPosition>1</recordPosition> <extraRecordData> <rel:score xmlns:rel="info:srw/extension/2/relevancy-1.0">0.965</rel:score> </extraRecordData> </record> <term>
<value>dinosaur</value> <extraTermData> <rt:termType xmlns:rt="info:srw/extension/2/requestedTerm-1.2"> requestedTerm </rt:termType> </extraTermData> </term> <xQuery>
<searchClause xmlns="http://www.loc.gov/zing/cql/xcql/"> <index>dc.title</index> <relation> <value>=</value> </relation> <term>dinosaur</term> </searchClause> <extraOperandData> <qry:hits xmlns:qry="info:srw/extension/1/query-1.0">0</qry:hits> </extraOperandData> </xQuery> |
July 25, 2007 |