ODL Search Specification

The jOAI ODL Search Specification is a Web service available in jOAI that allows clients to perform textual and fielded searches over the metadata in the data provider. After issuing a search request, clients receive the matching metadata records back within the standard ListRecords or ListIdentifiers response containers. The metadata may then be used in a custom search user interface or processed by remote clients on the fly.

The Search page in jOAI is implemented using ODL search and can be customized and easily installed to another location or remote Web server as described below in the section Search client template.

jOAI ODL search is an extension to the OAI protocol that supports searching similar to the Open Digital Library (ODL) search specification (odlsearch1).

Searching

To perform a jOAI ODL search, clients must provide a search query in the set argument of either a ListRecords or ListIdentifiers request. The set argument must conform to the following syntax: dleseodlsearch/[query string]/[set]/[offset]/[length] where "dleseodlsearch" is the exact string dleseodlsearch, "query string" indicates a list of keywords or Lucene query upon which to search, "set" indicates the set over which to search, "offset" indicates the offset into the results list to begin the results, and "length" indicates the total number of results to return. To search over all sets, clients must supply the string "null" in the set field. Clients must escape all spaces in query string and set with a plus (+) symbol and all slashes (/) with %2F. The default boolean logic is AND. To request a query using boolean OR, clients must supply the exact string "OR" between each term in the query string.

Examples:

".../provider?verb=ListRecords&metadataPrefix=oai_dc&set=dleseodlsearch/ocean/null/0/10" - Performs a text search for the term "ocean" across all sets in the repository, returning matching results numbers 0 through 10.

".../provider?verb=ListRecords&metadataPrefix=oai_dc&set=dleseodlsearch/ocean/null/10/10" - Performs a text search for the word "ocean" across all sets in the repository, returning matching results numbers 10 through 20.

".../provider?verb=ListRecords&metadataPrefix=oai_dc&set=dleseodlsearch/ocean+weather/dcc/0/10" - Performs a text search for the terms "ocean" AND "weather" across the set dcc, returning matching results numbers 0 through 10.

".../provider?verb=ListRecords&metadataPrefix=oai_dc&set=dleseodlsearch/ocean+OR+weather/dcc/0/10" - Performs a text search for the terms "ocean" OR "weather" across the set dcc, returning matching results numbers 0 through 10.

".../provider?verb=ListRecords&metadataPrefix=oai_dc&set=dleseodlsearch/%2Ftext%2F%2Fdc%2Ftitle:ocean/dcc/0/10" - Performs a text search for the terms "ocean" in the search field '/text//dc/title' across the set dcc, returning matching results numbers 0 through 10.

Search fields and query syntax

The jOAI index provides separate search fields for all data that reside in the records in the repository. Standard, XPath, and Custom search fields and query syntax are described in detail in the Digital Discovery System (DDS) Search API Documentation (see the sections titled 'Search fields' and 'Example search queries'). jOAI and DDS share the same repository code base and thus the available search fields, query syntax, and related processing are the same.

ODL search explorer

Use the form below to construct and submit sample ODL search queries to the data provider. Enter a query string into the search interface. Then click Search to view the XML response and see the ODL request that appears in the address (URL) bar.

Enter keyword:
	Search in set: Format:

Flow control

All state is embedded in the search query string, giving clients control over response flow. Clients can "page through" a set of results by issuing the same request in succession and incrementing the offset parameter by the desired quanta. For example, a client wishing to iterate through three pages of results for a search on the term ocean, retrieving ten records per page, would issue the following three queries:

".../provider?verb=ListRecords&metadataPrefix=oai_dc&set=dleseodlsearch/ocean/null/0/10"

".../provider?verb=ListRecords&metadataPrefix=oai_dc&set=dleseodlsearch/ocean/null/10/10"

".../provider?verb=ListRecords&metadataPrefix=oai_dc&set=dleseodlsearch/ocean/null/20/10"

At the end of each response an empty resumptionToken element is provided for the client that contains the attributes completeListSize and cursor. The completeListSize attribute shows the total number of records in the repository that match the given query. The cursor reflects the offset into the result set where the current response container begins.

Search client template

jOAI includes an ODL search client template that comes installed with the software as part of the Search page and can be modified within the software or copied and moved to any JSP container. The search template can provide a search for the local data provider installation or any other DLESE jOAI v2.0.4 or later data provider.

To use the template, modify or copy the file located at $CATALINA_HOME/webapps/oai/odl_search_client.jsp ($CATALINA_HOME refers to the location of the Tomcat installation for jOAI) and follow the instructions provided in the file.

As you code your JSP page(s) you may find this tutorial useful regarding making JSP pages that use UTF-8 Unicode: Developing Multilingual Web Applications Using JavaServer Pages Technology.

Note that because ODL search is an extension to the standard OAI protocol, the search template works only when pointed to a DLESE jOAI v2.0.4 or later data provider.