WSRF Developer Guide

The Developer Guide provides instructions for using many of the features that are included in Apache WSRF. If you are new to this project, you should start with the Getting Started and the Tutorial before reading this guide. They provide a good starting point for learning how to use Apache WSRF.

The Developer Guide often refers to different parts of the Web Services Resource Framework (WSRF) specifications that are defined by the OASIS standards body. You should become familiar with these specifications and refer to them as needed.

The Developer Guide guide often refers to Apache Axis, Apache Tomcat, Apache Ant, and Apache XMLBeans. Instructions for these packages are included as required and are not meant to replace the formal documentation for these projects. Consult them as necessary.

Lastly, Apache WSRF is consumed by the Pubscribe and Muse projects. Many of the concepts that are covered in this guide are also applicable to Pubscribe and Muse. While it is not required, it is a good idea to start with Apache WSRF before moving on to these other projects.

Apache WSRF is an implementation of the WSRF family of specifications that are defined by the OASIS standards body. Ultimately, this family of specifications defines a method of exposing resources using Web services. This is typically done for management purposes. The resource can be anything from a device to an application component or even a current management component such as a JMX MBean. The specifications include:

• WS Resource - Defines a WS-Resource and describes how one Web service can be used to represent multiple resource instances.
• WS-ResourceProperties (WSRF-RP) - Defines how to define and interact with stateful properties of a WS-Resource.
• WS-ResourceLifetime (WSRF-RL) - Defines a way in which the lifetime of a WS-Resource can be monitored and how the WS-Resource can be destroyed.
• WS-ServiceGroup (WSRF-SG) - Defines how WS-Resources can be aggregated or grouped together for a domain specific purpose.
  Note

  The WS-ServiceGroup specification is currently not implemented in Apache WSRF.
• WS-BaseFaults (WSRF-BF) - Defines a standard format for SOAP faults thrown by WSRF services.

The resource invocation framework is the foundation upon which Apache WSRF is implemented. The framework includes a set of core interfaces, as well as runtime pieces. The framework is discussed in detail below.

Core Interfaces

The resource invocation framework revolves around several core interfaces:

• WsrfService - represents a WSRF service (i.e. a service that represents the external interface for a set of WS-Resource instances of a particular type)
• Resource - represents a WS-Resource as defined by the WS-Resource specification.
• ResourceHome - provides a way to instantiate and lookup Resource instances; there is one ResourceHome object per type of Resource
• ResourceContext - provides request context information to the WSRF service

Runtime Behavior

At runtime, the entry point to the framework is the ResourceHandler. The ResourceHandler is implemented as a JAX-RPC 1.1 handler to allow it to run inside of any JAX-RPC-based SOAP engine. Since it acts as a request dispatcher, it belongs either as the pivot point of the handler chain or as the last handler in the chain. For each incoming SOAP request, the ResourceHandler performs the following steps:

1. deserializes the contents of the request message body to an XMLBeans XmlObject and then validates this XmlObject according to its schema type as it was defined in the service's WSDL;
2. creates a ResourceContext and populates it with vital information associated with the request such as the service name, the service URL, and the JAX-RPC SOAPMessageContext;
3. based on the name of the service to which the request was sent, instantiates the appropriate type of service object, passing it the ResourceContext;
4. based on either the request body element or the wsa:Action header (this is configurable on a per-operation basis), maps the request to a particular method of the service object, invoking that method with the request XmlObject as a parameter;
5. serializes the XmlObject returned by the method and adds it to the body of the response message.

Schema validation of incoming requests is a powerful feature. When validation fails, a fault is returned to the client that contains a detailed description of exactly what is wrong with the XML. Request validation is not only powerful, but it is also efficient, since it is performed via XMLBeans, which uses an in-memory binary schema store. Nevertheless, if the utmost performance is required, request validation can be disabled.

As described above, when the ResourceHandler creates a service instance, it passes it a ResourceContext object. From the context, methods in the service an obtain the specific resource instance that was targeted by the current request; this is accomplished by simply calling the getResource method on the context. Under the hood, the context uses the service name as a key to lookup the resource home object from JNDI. It then extracts a resource key Object from the header portion of the SOAP request and uses this key to lookup a resource instance from the home. If there is no resource registered in the home with the specified key, a ResourceUnknownException is thrown, which ultimately is propagated back to the client as a ResourceUnknownFault WSRF base fault.

A set of tools and integrations are provided that facilitate developing WSRF-compliant Web services. They are provided to help developers focus on defining their WS Resource without having to deal with low-level implementation details.

The tools and integrations include:

• A WSRF WSDL template for writing WSRF-compliant WSDLs
• A Wsdl2Java tool for generating Java Classes from a WSDL
• An integration with Apache XMLBeans for generating custom types defined in the WSDL
• An integration with Apache Axis for automatically deploying WS Resources