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:
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.
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>.