Apache SOAP utilizes XML documents called "deployment descriptors" to provide information to the SOAP runtime about the services that should be made available to clients. They can provide a wide array of information such as the URN for the service (which is used to route the request when it comes in), method and class details if the service is being provided by a Java class, or the name of a script if the service is implemented in any of the BSF supported scripting languages. The exact contents of the deployment descriptor depend upon the type of artifact which is being exposed via SOAP. Below you will find details about the different types of deployment descriptors which may be used in this release.
A deployment descriptor which exposes a service which is implemented via a standard Java class (including a normal Java Bean) looks like the following:
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
id="urn:service-urn" [type="message"] [checkMustUnderstands="true|false"]>
<isd:provider type="java"
scope="Request | Session | Application"
methods="exposed-methods">
<isd:java class="implementing-class" [static="true|false"]/>
</isd:provider>
<isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener>
</isd:service>
Where service-urn is the URN that you want to give to a service, exposed-methods is a space separated list of methods which you wish to expose, and implementing-class is fully qualified class name (i.e. packagename.classname) that provides the methods which are being exposed. On the <service> element, there is an optional attribute called type which may be set to the value "message" if the service is document-oriented instead of being an RPC invoked service, and an optional attribute called checkMustUnderstands which may be set to either "true" or "false" depending upon whether or not you want the server to throw a Fault if there were SOAP headers in the request which were marked as MustUnderstand. On the <java> element, there is an optional attribute called static, which may be set to either "true" or "false", depending upon whether or not the methods which are being exposed are static or not. The <provider> element also takes a scope attribute which indicates the lifetime of the instantiation of the implementing class. "Request" indicates that the object will be removed after this request has completed, "Session" indicates that the object will last for the current lifetime of the HTTP session, and Application indicates that the object will last until the servlet which is servicing the requests is terminated.
A deployment descriptor which exposes a service which is implemented via an Enterprise Java Bean looks like the following:
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
id="urn:service-urn">
<isd:provider type="provider-class"
scope="Application"
methods="exposed-methods">
<isd:option key="JNDIName" value="jndi-name"/>
<isd:option key="FullHomeInterfaceName" value="home-name" />
<isd:option key="ContextProviderURL" value="context-provider" />
<isd:option key="FullContextFactoryName" value="factory-name" />
</isd:provider>
<isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener>
</isd:service>
Where service-urn and exposed-methods have the same meaning as in the standard Java class deployment descriptor, provider-class is either org.apache.soap.providers.StatelessEJBProvider, org.apache.soap.providers.StatefulEJBProvider, or org.apache.soap.providers.EntityEJBProvider, depending on whether or not the implementation is a stateless session bean, a stateful session bean, or an entity bean, respectively, jndi-name is the registered JNDI name of the EJB, home-name is the fully qualified class name of the EJB's home, context-provider is the URL associated with the JNDI context provider, and factory-name is the name of the JNDI context factory. For backwards compatibility, the jndi-name may also be specified in the class attribute of the <java> element.
A deployment descriptor which exposes a service which is implemented via a BSF Script looks like the following:
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
id="urn:service-urn">
<isd:provider type="script"
scope="Request | Session | Application"
methods="exposed-methods">
<isd:script language="language-name" [source="source-filename"]>
[script-body]
</isd:script>
</isd:provider>
<isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener>
</isd:service>
Where service-urn, exposed-methods, and scope have the same meaning as in the standard Java class deployment descriptor, and language-name is the name of the BSF-supported language that the script was written in. The deployment descriptor must also have either a source attribute on the <script> element, or contain a script-body, which has the actual script which will be used to provide the service. If the deployment descriptor has the source attribute, then source-filename refers to the file which contains the service implementation.
In all of the examples above, a single fault listener, org.apache.soap.server.DOMFaultListener, has been registered. In reality, any class which implements the interface specified by org.apache.soap.server.SOAPFaultListener may be registered via the <faultListener> element. Multiple fault listeners may be specified by simply adding additional <faultListener> elements. For more information about Apache SOAP fault listeners, look here.
Type mapping information for RPC services may also be specified in the deployment descriptors. Mappings are specified through the use of a <mappings> element which may optionally appear as a child of the <service> element. Mappings specified in this manner are only available to the service described by the deployment descriptor in which they appear. A deployment descriptor with type mappings looks like the following:
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="...">
<isd:provider .../>
<isd:faultListener .../>
<isd:mappings [defaultRegistryClass="registry-class"]>
<isd:map encodingStyle="encoding-uri" xmlns:x="qname-namespace" qname="x:qname-element"
javaType="java-type" java2XMLClassName="serializer" xml2JavaClassName="deserializer"/>
...
</isd:mappings>
Where encoding-uri is the URI for the encoding method (i.e. http://schemas.xmlsoap.org/soap/encoding/ for the standard SOAP encoding,) qname-namespace is the namespace for the XML element, qname-element is the name of the XML element, java-type is the fully qualified Java class that you are providing the mapping for (i.e. samples.Date,) serializer is the fully qualified Java class that implements org.apache.soap.util.xml.Serializer, and deserializer is the fully qualified Java class that implements org.apache.soap.util.xml.Deserializer. On the <mappings> element is an optional attribute called defaultRegistryClass, whose value (indicated by registry-class)is the fully qualified Java class (which is a subclass of org.apache.soap.encoding.SOAPMappingRegistry) that you wish to use as the default type mapping registry. For more information about the Apache SOAP type mapping support, look here.
Last updated 5/20/2001 by Bill Nagy <nagy@watson.ibm.com>.