All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class ORG.oclc.z39.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.

Version:
@(#)Z39api.java 1.1 07/09/97
See Also:
zclient, example, zapplet, Z39init, Z39present, Z39search, Z39scan, Z39response

Variable Index

 o accessControlRequest
A PDU name; see the Z39.50 specification.
 o accessControlResponse
A PDU name; see the Z39.50 specification.
 o AttributeList
Exported definition
 o AttributesPlusTerm
Exported definition
 o Close
A PDU name; see the Z39.50 specification.
 o DatabaseName
A Global parameter; see the Z39.50 specification.
 o deleteResultSetRequest
A PDU name; see the Z39.50 specification.
 o deleteResultSetResponse
A PDU name; see the Z39.50 specification.
 o DiagnosticFormataddMsg
DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.
 o DiagnosticFormatcondition
DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.
 o DiagnosticFormatspecified
DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.
 o DiagnosticFormatunspecified
DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.
 o ElementSetName
A Global parameter; see the Z39.50 specification.
 o extendedservicesRequest
A PDU name; see the Z39.50 specification.
 o extendedservicesResponse
A PDU name; see the Z39.50 specification.
 o generalTerm
Exported definition
 o initRequest
A PDU name; see the Z39.50 specification.
 o initResponse
A PDU name; see the Z39.50 specification.
 o MultipleNonSurrogates
DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.
 o nonSurrogateDiagnostic
DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.
 o otherInformation
Global parameter; see the Z39.50 specification
 o presentRequest
A PDU name; see the Z39.50 specification.
 o presentResponse
A PDU name; see the Z39.50 specification.
 o ReferenceId
A Global parameter; see the Z39.50 specification.
 o resourceControlRequest
A PDU name; see the Z39.50 specification.
 o resourceControlResponse
A PDU name; see the Z39.50 specification.
 o resourceReportRequest
A PDU name; see the Z39.50 specification.
 o resourceReportResponse
A PDU name; see the Z39.50 specification.
 o ResultSetId
A Global parameter; see the Z39.50 specification.
 o scanRequest
A PDU name; see the Z39.50 specification.
 o scanResponse
A PDU name; see the Z39.50 specification.
 o searchRequest
A PDU name; see the Z39.50 specification.
 o searchResponse
A PDU name; see the Z39.50 specification.
 o sortRequest
A PDU name; see the Z39.50 specification.
 o sortResponse
A PDU name; see the Z39.50 specification.
 o triggerResourceControlRequest
A PDU name; see the Z39.50 specification.
 o UserInformationField
UserInformation field; see the Z39.50 specification.

Constructor Index

 o Z39api()

Variables

 o initRequest
 public static final int initRequest
A PDU name; see the Z39.50 specification.

 o initResponse
 public static final int initResponse
A PDU name; see the Z39.50 specification.

 o searchRequest
 public static final int searchRequest
A PDU name; see the Z39.50 specification.

 o searchResponse
 public static final int searchResponse
A PDU name; see the Z39.50 specification.

 o presentRequest
 public static final int presentRequest
A PDU name; see the Z39.50 specification.

 o presentResponse
 public static final int presentResponse
A PDU name; see the Z39.50 specification.

 o deleteResultSetRequest
 public static final int deleteResultSetRequest
A PDU name; see the Z39.50 specification.

 o deleteResultSetResponse
 public static final int deleteResultSetResponse
A PDU name; see the Z39.50 specification.

 o accessControlRequest
 public static final int accessControlRequest
A PDU name; see the Z39.50 specification.

 o accessControlResponse
 public static final int accessControlResponse
A PDU name; see the Z39.50 specification.

 o resourceControlRequest
 public static final int resourceControlRequest
A PDU name; see the Z39.50 specification.

 o resourceControlResponse
 public static final int resourceControlResponse
A PDU name; see the Z39.50 specification.

 o triggerResourceControlRequest
 public static final int triggerResourceControlRequest
A PDU name; see the Z39.50 specification.

 o resourceReportRequest
 public static final int resourceReportRequest
A PDU name; see the Z39.50 specification.

 o resourceReportResponse
 public static final int resourceReportResponse
A PDU name; see the Z39.50 specification.

 o scanRequest
 public static final int scanRequest
A PDU name; see the Z39.50 specification.

 o scanResponse
 public static final int scanResponse
A PDU name; see the Z39.50 specification.

 o sortRequest
 public static final int sortRequest
A PDU name; see the Z39.50 specification.

 o sortResponse
 public static final int sortResponse
A PDU name; see the Z39.50 specification.

 o extendedservicesRequest
 public static final int extendedservicesRequest
A PDU name; see the Z39.50 specification.

 o extendedservicesResponse
 public static final int extendedservicesResponse
A PDU name; see the Z39.50 specification.

 o Close
 public static final int Close
A PDU name; see the Z39.50 specification.

 o ReferenceId
 public static final int ReferenceId
A Global parameter; see the Z39.50 specification.

 o ResultSetId
 public static final int ResultSetId
A Global parameter; see the Z39.50 specification.

 o DatabaseName
 public static final int DatabaseName
A Global parameter; see the Z39.50 specification.

 o ElementSetName
 public static final int ElementSetName
A Global parameter; see the Z39.50 specification.

 o otherInformation
 public static final int otherInformation
Global parameter; see the Z39.50 specification

 o UserInformationField
 public static final int UserInformationField
UserInformation field; see the Z39.50 specification.

 o AttributeList
 public static final int AttributeList
Exported definition

 o generalTerm
 public static final int generalTerm
Exported definition

 o AttributesPlusTerm
 public static final int AttributesPlusTerm
Exported definition

 o nonSurrogateDiagnostic
 public static final int nonSurrogateDiagnostic
DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.

 o MultipleNonSurrogates
 public static final int MultipleNonSurrogates
DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.

 o DiagnosticFormatcondition
 public static final int DiagnosticFormatcondition
DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.

 o DiagnosticFormatunspecified
 public static final int DiagnosticFormatunspecified
DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.

 o DiagnosticFormatspecified
 public static final int DiagnosticFormatspecified
DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.

 o DiagnosticFormataddMsg
 public static final int DiagnosticFormataddMsg
DIAG.2 Diagnostic Format Diag-1; see Z39.50 specification.

Constructors

 o Z39api
 public Z39api()

All Packages  Class Hierarchy  This Package  Previous  Next  Index