OpenSPML Toolkit

1 Introduction

This document provides an overview of the OpenSPML Toolkit, a collection of Java classes that assist in submitting SPML requests, and receiving SPML responses. The toolkit is not vendor specific, it may be used by any Java application to communicate with any SPML compliant server. It may also be used by an SPML server to parse requests and build responses.

A Java object model is provided for all of the request and response elements defined in the SPML protocol. In addition a set of classes to perform SOAP communication is also provided. This provides Java developers with a convenient mechanism to make SPML requests without having to worry about the details of the XML language or the HTTP transport protocol.

This document provides only an overview of the available classes. Please consult the Javadocs for more detailed information.

2 Installation and Use

The distribution includes the following jar files:

openspml.jar: contains the class files for the OpenSPML library

The openspml.jar file is normally installed in the WEB-INF/lib directory of your web application. If you wish to use only the client portion of the library, you may put openspml.jar anywhere and include it in the client application's classpath.

The library requires version 2.2 or higher of the Apache SOAP library, and version 2.4.0 or higher of the Xerces XML parser with JAXP support.

3 Request Classes

The following classes are used to construct SPML requests sent from a client to the server.

SpmlRequest: The base class for all requests. It provides a request id, an indication of synchronous or asynchronous execution mode, and a collection of vendor specific operational attributes.
BatchRequest: A class used to represent a list of add, modify, delete, or search requests that are to be performed together. It also provides an indication of whether the requests are to be performed serially or in parallel, and an indication of whether the batch should terminate upon the first error in any of the child requests.
StatusRequest: A class used to request the status of a BatchRequest that was executed asynchronously.
CancelRequest: A class used to request that a BatchRequest that is executing asynchronously be canceled.
SchemaRequest: Requests vendor-specific schema for objects that may be managed by the server.
AddRequest: Requests the creation of a new objects.
ModifyRequest: Requests the modification of an existing object.
DeleteRequest: Requests the deletion of an object.
SearchRequest: A class used to perform queries and return attributes of objects.

4 Response Classes

The following classes are used to construct SPML responses send from the server back to the client.

SpmlResonse: The base class for all responses. It provides an overall indication of success or failure, a list of error messages, and a set of operational attributes.
BatchResponse: A class used to represent a list of add, modify, delete, or search results that were performed together.
StatusResponse: The result of a status request on an asynchronous batch request.
CancelResponse: The result of a cancel request on an synchronously executing batch request.
SchemaResponse: A class used to represent the vendor-specific schema for objects that may be managed by the server.
AddResponse: A class used to represent the results of creating a new object. It may include the server-generated object identifier, as well as attributes that were not included in the add request, but generated as a side effect.
ModifyResponse: The result of an object modification.
DeleteResponse: The result of an object deletion.
SearchResponse: The result of a query. The result may include an arbitrary collection of the attributes from each object that matched the search criteria.

5 Communication Classes

The following classes use the SPML object model classes described above to perform actual SPML requests using a SOAP binding with an HTTP transport protocol.

SOAPClient: A class providing a simplified interface for making message-oriented SOAP requests using the Apache 2.2 SOAP library.
SpmlClient: A class providing a mechanism to send and receive SPML requests using the SpmlRequest and SpmlResponse classes. Once the request is formatted as XML, it uses the SOAPClient class to handle the actual communication. When the XML response is received, it is parsed into a SpmlResponse and returned.
LighthouseClient: A class that encapsulates a SpmlClient instance to provide a more Lighthouse-specific interface. All requests made using this client are ultimately implemented with SPML requests.
SOAPRouter

6 Utility Classes

The classes described in this section provide general purpose utilities used by other classes in the library.

SpmlBuffer: A class used to format the XML strings for SPML messages.
XmlParser: A wrapper around the Xerces parser that provides a simpler interface, and maintains a pool of parser objects for better performance.
XmlElement: A wrapper around the DOM Element class that provides a convenient collection of methods for analyzing DOM trees.