Writing Providers

When creating services, it makes sense to take advantage of legacy programming artifacts in order to not have to reinvent the wheel, and to program in the language(s) in which you are most comfortable. The developers of Apache SOAP recognized that not all services were going to be methods on Java classes, and architected a way to allow any type of programming artifact to be used as a service implementation. To enable this, a layer of abstraction was created between the Apache SOAP server and the service implementation. This layer is called the Apache SOAP Pluggable Provider.

A pluggable provider acts as the bridge between the SOAP engine and the service which is being invoked. The provider is responsible for:

Apache SOAP comes with six predefined providers:

Using Pluggable Providers

Information about the provider that you wish your service to use is located in the deployment descriptor. The <provider> element, as well as its descendent elements, provide information to the runtime and provider about what they should do to make a service accessible. The type attribute on the <provider> element identifies the Java class which should act as the provider. If you are exposing a Java class (either as an RPC-based service or as a message-oriented service) then you should specify "java" as the value for this attribute, if you are exposing a BSF-supported script then you should specify "script", otherwise you should specify the fully qualified classname of the provider.

Additional information to the pluggable providers may be specified by adding <option> elements as descendents to the <provider> elements. For more information about specifying pluggable providers and their options, look here.

Writing Pluggable Providers

If you need to support programming artifacts which are not directly supported by one of the included providers, or if one of the included providers does not quite meet your needs, then you will need to create your own pluggable provider.

Providers need to implement the org.apache.soap.util.Provider interface, which is as follows:

public interface Provider {
  public void locate( DeploymentDescriptor dd,
                      Envelope             env,
                      Call                 call,
                      String               methodName,
                      String               targetObjectURI,
                      SOAPContext          reqContext)
                throws SOAPException ;
  public void invoke(SOAPContext req, SOAPContext res) throws SOAPException ;
}
The locate method will be called in order to allow the provider a chance to verify that the service implementation exists and is available to process the request. If an error occurs, this method should throw a SOAPException. After a successful call to locate the SOAP engine will then execute the invoke method to actually call the service implementation. Notice that the invoke call does not have any information about the service. All of that information was passed into the locate method, so it is the responsibility of locate to save whatever information is needed so that invoke can call the service.

The invoke method is also responsible for converting any response from the service implementation into a SOAP envelope and placing it in the res parameter (a SOAPContext).

If any <option> elements which were specified in the deployment descriptor for the service are accessible as properties via a Hashtable retrieved through a call to dd.getProps() in the locate method.

Last updated 5/20/2001 by Bill Nagy <nagy@watson.ibm.com>.