Open SiteSearch 4.1.1 Final API Specification: Class Z39api

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Open SiteSearch 4.1.1
Final

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

ORG.oclc.z39
Class Z39api

java.lang.Object
  |
  +--ORG.oclc.z39.Z39api

public class Z39api
extends Object

The Z39 Client API Software presented here is a translation of the C version of the API written by Ralph Levan at OCLC. The documentation presented here is pretty much taken from his documentation.

A description of our fourth version of the Z39.50 Client API is below. It will, of course, undergo some refinement with use and get extended to support new Z39.50 functionality as required. The changes from the fourth version include support for type-101 queries (including proximity operators in the Client APIs query grammer) and the removal of some unneeded parameters in the request calls. Scan was brought into compliance with the final version of the 95 standard. In addition, a number of changes were made to simplify things and to bring the Client API into compliance with the article that was written about it. (See the section on availability at the end of this document.)

The change from the third version is the addition of support for piggybacked Presents with the SearchRequest. This means that there is now an optional PRESENT_RESPONSE object in the SEARCH_RESPONSE object.

The changes from the second version are the addition of support for a simple userid and password on the InitRequest; support for full boolean queries in the SearchRequest; support for both MARC and SUTRS record syntaxes in the PresentRequest. A class to support Scan has been added. It is in an early stage of development and will definitely be enhanced with experience. Finally, a new method, logging(), provides support for run-time diagnostic logging.

High-level description

The classes process IRP messages, they do not send or receive these messages; that is up to the calling routines. (IRP stands for Information Retrieval Protocol, which is the name of the protocol described by Z39.50.) An IRP Request method is called and it produces a BER (Basic Encoding Rules, the chosen transfer syntax for ASN.1) record that can be sent to a Z39.50 target. Conversely, a BER record containing an IRP response is processed and instance variables in an object are filled in with values from the response. The BER records are encoded and decoded using OCLC's BER utilities. These utilities are available via anonymous ftp to ftp.rsch.oclc.org and are in the pub/BER_utilities directory. They are available in either a C version (as source) or a Java version (as class files).

There are two layers to the IRP response methods. The layer you choose to use will depend on coding style and application complexity. The lower layer, consisting of Response() methods in the Z39init, Z39present, Z39search and Z39scan classes, are invoked directly with the Z39.50 target's response to an Init, Search, Present or Scan request. These methods fill in instance variables with the various parameters in the response. They are appropriate when the application (the Z39.50 origin) is relatively simple and "knows" what kind of response it is receiving. This is usually a single user application.

In more complex applications, it is difficult to know what kind of response has arrived. The next layer addresses this problem. The class Z39response will determine the type of response and invoke the appropriate class to process the response. The type is stored in an instance variable in the Z39response object. An object of the appropriate type is also availabe in the Z39response object.

In the descriptions of the methods, I will not discuss the meaning of the various parameters to the request methods. They are fully described in the Z39.50 standard.

In all the request methods, a long referenceId is provided. The value in the referenceId is in an instance variable filled in by the response routines. In complex applications, we have found that it is a useful place to put a reference to an object containing information about the request that has just been processed. Doing this has allowed us to build relatively stateless applications.

The BER record that is created by the request methods is put into a BerString object. The BER record can totally fill the buffer in the BerString object (the default action) or it can leave space for a header and trailer. The caller can then move communications headers and/or trailers into the extra space.

Availability

An article about building Z39.50 clients, which includes a detailed description of the Client API, was written for the Z39.50 Implementors Group. It is available via anonymous ftp at the Z39.50 Maintenance Agencys ftp site at ftp.loc.gov. You're on your own for finding it there.

The article will also be published by the National Institute for Standards and Technology (NIST) as part of a Z39.50 monograph. Good luck finding that too.

Finally, the article is available via anonymous ftp at ftp.rsch.oclc.org in the pub/SiteSearch/z39.50_client_api directory. It is available in several formats, the names of which all begin with zclient.

The OCLC ftp site also provides the .class files for the Z39.50 Client API and a simple client application (zclient.java), which are in the pub/SiteSearch/java directory, as well as the BER utilities which are in the pub/BER_utilities/java directory.

Examples

Java source for 2 examples is provided. The example.java is a Java application that does an Init, Scan, Search and Present. The zapplet.java is a Java applet that does an Init, Scan, Search and Present. The html file for zapplet.java is zapplet.html.

See Also:: zclient, example, zapplet, Z39init, Z39present, Z39search, Z39scan, Z39response

Field Summary
`static int`	`accessControlRequest` A PDU name; see the Z39.50 specification.
`static int`	`accessControlResponse` A PDU name; see the Z39.50 specification.
`static int`	`AttributeList` Exported definition
`static int`	`AttributesPlusTerm` Exported definition
`static int`	`characterStringTerm` characterString Term definition
`static int`	`Close` A PDU name; see the Z39.50 specification.
`static int`	`DatabaseName` A Global parameter; see the Z39.50 specification.
`static int`	`dateTimeTerm` Date-Time Term definition
`static int`	`dedupRequest` A PDU name; see the Z39.50 specification.
`static int`	`dedupResponse` A PDU name; see the Z39.50 specification.
`static int`	`deleteResultSetRequest` A PDU name; see the Z39.50 specification.
`static int`	`deleteResultSetResponse` A PDU name; see the Z39.50 specification.
`static int`	`DiagnosticFormataddMsg` DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.
`static int`	`DiagnosticFormatcondition` DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.
`static int`	`DiagnosticFormatspecified` DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.
`static int`	`DiagnosticFormatunspecified` DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.
`static int`	`ElementSetName` A Global parameter; see the Z39.50 specification.
`static int`	`extendedservicesRequest` A PDU name; see the Z39.50 specification.
`static int`	`extendedservicesResponse` A PDU name; see the Z39.50 specification.
`static int`	`externalTerm` external Term definition
`static int`	`generalTerm` general Term definition
`static int`	`initRequest` A PDU name; see the Z39.50 specification.
`static int`	`initResponse` A PDU name; see the Z39.50 specification.
`static int`	`integerAndUnitTerm` IntegerAndUnit Term definition
`static int`	`MultipleNonSurrogates` DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.
`static int`	`nonSurrogateDiagnostic` DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.
`static int`	`nullTerm` Null Term definition
`static int`	`numericTerm` numeric Term definition
`static int`	`oidTerm` OID Term definition
`static int`	`otherInformation` Global parameter; see the Z39.50 specification
`static int`	`presentRequest` A PDU name; see the Z39.50 specification.
`static int`	`presentResponse` A PDU name; see the Z39.50 specification.
`static int`	`ReferenceId` A Global parameter; see the Z39.50 specification.
`static int`	`resourceControlRequest` A PDU name; see the Z39.50 specification.
`static int`	`resourceControlResponse` A PDU name; see the Z39.50 specification.
`static int`	`resourceReportRequest` A PDU name; see the Z39.50 specification.
`static int`	`resourceReportResponse` A PDU name; see the Z39.50 specification.
`static int`	`ResultSetId` A Global parameter; see the Z39.50 specification.
`static int`	`scanRequest` A PDU name; see the Z39.50 specification.
`static int`	`scanResponse` A PDU name; see the Z39.50 specification.
`static int`	`searchRequest` A PDU name; see the Z39.50 specification.
`static int`	`searchResponse` A PDU name; see the Z39.50 specification.
`static int`	`sortRequest` A PDU name; see the Z39.50 specification.
`static int`	`sortResponse` A PDU name; see the Z39.50 specification.
`static int`	`triggerResourceControlRequest` A PDU name; see the Z39.50 specification.
`static int`	`UserInformationField` UserInformation field; see the Z39.50 specification.

Constructor Summary
`Z39api()`

Methods inherited from class java.lang.Object

clone, 
equals, 
finalize, 
getClass, 
hashCode, 
notify, 
notifyAll, 
toString, 
wait, 
wait, 
wait

Field Detail