Writing Pluggable Provider

What Is A Pluggable Provider

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

locating the service
loading the service
invoking the service
converting the result from the service into a SOAP envelope

By default the SOAP engine will use the RPCJavaProvider for RPC services, and the MsgJavaProvider for Message services. The RPCJavaProvider simply loads the appropriate class, invokes the desired method and converts any result into a SOAP envelope.

Pluggable providers were introduced because it was clear that not all services would be methods on Java classes. For example, using pluggable providers a service could be an executable, or an EJB.

Using Pluggable Providers

When deploying a service the type field in the provider element is used to denote whether the service is a java method or a script that should be passed along to BSF. For example:

DeploymentDescriptor.xml
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
             id="urn:xmltoday-delayed-quotes">
  <isd:provider type="java"
                scope="Application"
                methods="getQuote">
    <isd:java class="samples.stockquote.StockQuoteService"/>
  </isd:provider>
</isd:service>

To use a different type of provider simply place the full classname in the type attribute:

DeploymentDescriptor.xml
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
             id="urn:testprovider">
  <isd:provider type="com.mycom.MyProvider"
                scope="Application"
                methods="myMethod">
    <isd:java class="com.mycom.MyClass"/>
    <isd:option key="classpath" value="c:\classes" /> 
  </isd:provider>
</isd:service>

Notice that the java element can still be optionally used if your provider needs it. Also, notice that there can optionally be option elements that can be used to configure your provider. These options will be placed in the props instance variable of the deployment descriptor passed into the locate method.

How To Write A Pluggable Provider

Providers need to implement the Provider interface:

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 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 call invoke to actually call the service. Notice that invoke call does not have any information about the service, all of that information was passed into the locate method so it is the responsibilty 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 into a SOAP envelope and placing it in the res parameter (a SOAPContext).