OpenSPML 2.0 Toolkit Overview

Introduction

This document provides an overview of the OpenSPML 2.0 Toolkit, a collection of Java classes that assist in submitting OASIS SPML 2.0 (SPML2) requests and receiving SPML2 responses. There are also classes in the toolkit that assist in the implementation of servlet-based SPML2 servers.

The toolkit is not vendor specific, it may be used by any Java application to communicate with any SPML2 compliant server. Again, it may also be used by an SPML2 server to parse requests and build responses.

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

This new version of the toolkit is designed to be pluggable, in part to make supporting the "profiles" of SPML 2.0 simpler; but to also allows you to plug-in different SOAP providers, different XML parsers, and you should be able to use different XML to Java binding tools (e.g. JAXB) to support the XML Schema profile.

This document provides only an overview of the available classes. Please consult the Javadocs (in /docs/apis) for more detailed information.

Currently, the distribution includes the following jar files (in the <root>>/lib directory):

openspml2-toolkit.jar: contains the class files for the OpenSPML 2.0 Toolkit.

The 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 openspml2-toolkit.jar anywhere and include it in the client application's classpath.

The library requires some other libraries, these are included in the distribution in the tools directory. They should also be made available to servers and clients. (You'll note that one of these in the openspml.jar from the 1.0 toolkit. We'll eventually remove this dependency.)

Here's an example web.xml (just the pertinent parts) that uses a service like 'dev/null' to handle requests. This should server as a starting point.

    <servlet>
        <servlet-name>openspmlRouter</servlet-name>
        <display-name>OpenSPML SOAP Router</display-name>
        <description>A router of RPC traffix - nominally SPML 2.0 over SOAP</description>
        <servlet-class>
            org.openspml.v2.transport.RPCRouterServlet
        </servlet-class>
        <init-param>
            <param-name>dispatchers</param-name>
            <param-value>org.openspml.v2.transport.SPMLViaSoapDispatcher</param-value>
        </init-param>
        <init-param>
            <param-name>trace</param-name>
            <param-value>true</param-value>
        </init-param>
        <init-param>
            <param-name>monitor</param-name>
            <param-value>org.openspml.v2.util.SwingRPCRouterMonitor</param-value>
        </init-param>
        <init-param>
            <param-name>SpmlViaSoap.spmlMarshallers</param-name>
            <param-value>org.openspml.v2.util.SimpleSPMLMarshaller</param-value>
        </init-param>
        <init-param>
            <param-name>SpmlViaSoap.spmlMarshallers.SimpleSPMLMarshaller.trace</param-name>
            <param-value>true</param-value>
        </init-param>
        <init-param>
            <param-name>SpmlViaSoap.spmlExecutors</param-name>
            <param-value>org.openspml.v2.test.DeadEndExecutor</param-value>
        </init-param>
    </servlet>

    <servlet-mapping>
        <servlet-name>openspmlRouter</servlet-name>
        <url-pattern>/openspml2</url-pattern>
    </servlet-mapping>

Apart from supporting the new version of the protocol, we also had some other goals.

We wanted to carry forward the good things about the 1.0 toolkit, namely:

• Separation between protocol and SPML handlers
• Protocol handler registration via servlet properties
• 'Plug-in' and registration mechanism for provider-specific server implementation via SPMLHandler interface

We wanted to make the toolkit more open - dropping some things; like:

• relies on DOM - we now allow you readily replace the parser implementation.
• too many things named handler - hopefully the naming is improved.
• SOAP toolkit agnostic - a replaceable layer in the toolkit knows about SOAP. You could readily use any SOAP toolkit you'd like.

We have added, or intend to add, the following items to the kit:

• a comprehensive example of a provider/server
• interoperability test suites, hitting live server(s)
• if there's to be a standard schema, use it in the examples and suites
• documentation, like javadoc, tutorials, and quick start guides.
• perhaps some infrastructure like logging; or at least a coherent exception handling model/strategy.

The toolkit services are layered and the package names that mirror the layers. Where appropriate they also mirror the specification.

This section names the layers and the package(s) that represent those layers. Generally, we are starting at the top of the layering and working down through to the dependencies. In other words, the first package listed should only be dependent on the next package listed.

We provide a list of the interesting classes in each package (not alsways complete), with short descriptions. The Javadoc is a more definitive set of information.

A note on class naming... there are a fair number of interfaces in the toolkit. We often define "starter" classes that are meant to be used as a base for the implementation of an interface. These classes are usually abstract and are named Basic<interfacename>. So, if we have an interface named "Foo", the "BasicFoo" class is the corresponding starter. This starter class may not be in the same package as the interface. Additionally, we often preface classes with "Simple"; which is meant to indicate that this is an example class that may not be implemented robustly enough to use in a production server, but it should communicate the basics of what the "real" implementation should look like.

Web Service Layer

(org.openspml.v2.transport)

Here's where determine how communication will happen. We don't assume much about the transport layer; while we do provide an example of using HttpServlet and SOAP as the transport - it should be possible to implement different transport protocols.

RPCDispatcher

Implement this interface in order to to implement an RPC API. We implement it to support SPML2 via SOAP.

  public void init(RPCRouter router, Map config) throws Spml2TransportException;
  public String dispatchRequest(String message) throws Spml2TransportException;

RPCRouter

This is an interface that can be monitored, and implementation should manage RPCDispatcher objects.

RPCRouterMonitor

An interface to allow the monitoring of the messages flowing through the router.

RPCRouterMonitorListener

Monitors tell listeners when they close.

RPCRouterServlet

An implementation of the RPCRouter interface that is also an HttpServlet. This also manages dispatchers, the default being one that knows how to take SOAP to SPML2 and back.

SPMLViaSOAPDispatcher

Implements the RPCDispatcher interface. This adapts from the world of the transport to the provider. Maintains a list of marshallers,and executors. The marshallers convert the transport data to XML and back.

Provider Layer (SPML2 domain)

(org.openspml.v2.provider)

This is where the provider implementation begins. The classes here receive the data from the transport layer and manipulate it. For example, SPMLMarshaller implementations move XML to Java and back.

SPMLMarshaller

An interface that receives Strings (SPML2) and returns SPMLRequest objects. These can also convert Response objects back to Strings (SPML2).

  public void init(Map config) throws Spml2Exception;
  public String getUniqueName();
  public Request unmarshallRequest(String msg) throws Spml2Exception;
  public String marshallResponse(Response res) throws Spml2Exception;

SPMLExecutor

An interface that processes Java objects (Request/Response). Implementations can redispatch them to other SPMLExecutor objects or could do the work directly. One might define an SPMLExecutor that takes a request, introspects on it, and calls a private method that implements the funtionality. Alternatively, one might define an executor that looks at the request and dispatches to a sub-executor that performs the operation. In the former case, the methods implement the operations, in the latter, the sub-handlers implement the operations.

  public Response execute(Request request) throws Spml2Exception;

Open Content Support

(org.openspml.v2.msg)

The SPML2 .xsds allow for Open Content in the object (i.e xsd:any for elements and attributes). The toolkit therefore has to allow for Java classes that represent this content. We do this by allowing clients of the toolkit to implement the OpenContentAttr and OpenContentElement interfaces. The latter is the more interesting.

We also use the Adapter pattern; providing an interface called OpenContentElementAdapter, and 2 default implementations that allow us to manage objects of type Marshallable and String (raw xml) as OpenContent.

Again, these implementations:

1. Manage objects implementing our Marshallable interface as OpenContent. Marshallable implementations can be hooked into the toolkit classes to become first-class citizens of the toolkit.
2. Manage Strings of XML as OpenContent, allowing you to do your own marshalling/unmarshalling.

NOTE: The string adapter is only enabled if you set the "org.openspml.v2.adaptXMLStrings" system property.

The other classes of interest in this package are XMLMarshaller and XMLUnmarshaller. These are the interfaces that we implement to actual bind XML to Java objects and back. These are what you would implement to replace, for example, our example classes that use Xerces DOM, with a different parser or parser model.

Core, Capabilities and Profiles

(subpackages of org.openspml.v2.msg and org.openspml.v2.profiles)

This section will discuss the contents of the subpackages of the .msg package. These contain the Java classes that are specified in the .xsd files of the standard distribution. Each package is named according to its prefix in these .xsds.

Since the key thing to know is where to find the classes, we won't list all the classes in each package here. You can refer to the Javadoc for that.

Table of Core and Capabilities Packages

"Core and Capabilities" Packages	Description
org.openspml.v2.msg.spml	This package holds the classes for the "core" capability.
org.openspml.v2.msg.pass	This package holds the classes for the "password" capability.
org.openspml.v2.msg.spmlasync	This package holds the classes for the "async" capability.
org.openspml.v2.msg.spmlbatch	This package holds the classes for the "batch" capability.
org.openspml.v2.msg.spmlbulk	This package holds the classes for the "bullk" capability.
org.openspml.v2.msg.spmlref	This package holds the classes for the "reference" capability.
org.openspml.v2.msg.spmlsearch	This package holds the classes for the "search" capability.
org.openspml.v2.msg.spmlsuspend	This package holds the classes for the "suspend" capability.
org.openspml.v2.msg.spmlupdates	This package holds the classes for the "updates" capability.

Table of Profiles Packages

"Profiles" Packages	Description
org.openspml.v2.profiles.spmldsml	This package holds classes defining the DSML Schema, as defined in the DSML Profile .xsd.
org.openspml.v2.profiles.dsml	This package holds classes defining the DSML 2.0 Java Bindings that are used in the DSML profile; i.e. Attr, Modification, and Value.
org.openspml.v2.profiles	This package is meant to hold ProfileRegistrar implementations. These classes are used to configure the system (via ObjectFactory) to use the desired profiles. The DSMLProfileRegistrar is the one example.
org.openspml.v2.profiles.xmlschema	This package will hold the classes that make it easier to add your own Java Binding classes into the toolkit. We want to allow the use of tools like JAXB and XmlBeans with the toolkit.

Example: Registering the DSML Profile

This is an example of telling the system that you want to use the DSML profile.

import org.openspml.v2.profiles.DSMLProfileRegistrar;
import org.openspml.v2.util.xml.ObjectFactory;

public class MySPMLv2Requestor {

    public static void main(String args[]) {

        ...

        // register the profile for DSML (do this even before listTargets!)
        ObjectFactory.getInstance().register(new DSMLProfileRegistrar());

        ...
    }

}

The implementation of the DSML classes is fairly straight-forward. In short, they simply implement the OpenContentElement interface and are then plugged into the system. Have look in the <root>/src/java/... tree for details.

One more note. Our Java bindings use a Reflection-based protocol to make these apis easier to write by hand. Because of this, some of the field names in the classes may look a little odd; but hopefully the comments in the code are sufficient to explain this.

org.openspml.v2.client - This package has classes that are used to talk to an SPML server via SOAP. They are simple - meant mostly as examples. They do not use any libraries other than the JDK.

SimpleSOAPClient

A class providing a simplified interface for making message-oriented SOAP requests.

Spml2Client

A class providing a mechanism to send and receive SPML2 requests using the msg.spml.Request and msg.spml.Response classes. Once the request is formatted as XML, it uses the SimpleSOAPClient class to handle the actual communication. When the XML response is received, it is unmarshalled into a Response and returned.

org.openspml.v2.util and org.openspml.v2.util - These two packages contain classes that implement some of the toolkit interfaces, mostly as examples, and might also be generally useful throughout the rest of the toolkit. Rather that enumerate all of them, we refer you to the Javadoc. We do describe a couple of the more important classes.

org.openspml.v2.util.xml.ObjectFactory

This class is a Singleton; and it is used to hook new OpenContent bindings classes (in particular, implementations of Marshallable and OpenContentElement) into the toolkit. It defines a couple of inner-interfaces that allow this. Please see the Javadoc.

org.openspml.v2.util.xml.OperationalNameValuePair

We provide a class that implements the OpenContentElement interface (and uses the MarshallableElemenent/Marshallable reflection based binding protocol) and can be used by clients to pass server-specific operational attributes (perhaps auth-tokens) in the SPMLv2 requests. This is not part of the specification, but it is useful to pass information "out-of-band".

This class is always available in the toolkit. It's always known to the ObjectFactory.

org.openspml.v2.util.EnumConstant

This is the base class for the Enums that are defined in the .xsd files (e.g. StatusRequest). This class made it easy to write Java bindings for these portions of the .xsd. If you are using the XML Shema profile, you might find this useful - along with the Reflection based binding protocol that we use in the toolkit.

Thanks for your interest in this toolkit.