Apache SOAP deployment descriptors

Apache SOAP utilizes XML documents called deployment descriptors to provide the SOAP run time with information on client services. The contents of the deployment descriptor vary, depending on the type of programming component that is published using SOAP. Deployment descriptors provide an array of information, such as:

• The Web service's Uniform Resource Name (URN), which is used to route the request when it arrives
• Method and class details, if the service is being provided by a Java^(TM) class
• User ID and password information, if the service provider must connect to a database

Deployment descriptors for each of the soap samples are included in the soapsamples.ear file in the ServerSamplesCode directory. For example, this might be /QIBM/UserData/WebAS5/Base/instance_name/installedApps/soapsamples.ear/ ServerSampleCode/src/addressbook/DeploymentDescriptor, where instance_name is the name of the root folder for your WAS instance.

Standard Java class deployment descriptor

A deployment descriptor that publishes a service that is implemented with a standard Java class or bean can look like this example:

<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="urn:service-urn" [type="message"]>
   <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>

In the example,

• Variables:
  • service-urn is the URN that you give to a service. (All services deployed within a single EAR file must have URNs that are unique within that EAR file.)
  • exposed-methods is a list of methods, separated by spaces, which are being published.
  • implementing-class is a fully qualified class name (that is, a packagename.classname) that provides the methods that you are publishing.

• The <service> element has an optional attribute called type which is set to the value message if the service is document oriented instead of invoked with a remote procedure call (RPC).
• The <java> element has an optional attribute called static, which can be set to either true or false, depending on whether the methods are available, or exposed, to service requesters. If exposed, this attribute indicates whether the method is static or not.
• The <provider> element a scope attribute that indicates the lifetime of the instantiation of the implementing class.
  • Request indicates the object is removed after the request completes.
  • Session indicates the object lasts for the lifetime of the HTTP session.
  • Application indicates the object lasts until the servlet that is servicing the requests is terminated.

Enterprise bean deployment descriptor

A deployment descriptor that publishes a service that is implemented with an enterprise bean can looks like this:

<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment7quot; id="urn:service-urn">
   <isd:provider type="provider-class" scope="Application" methods="exposed-methods">
      <isd:java class="jndi-name"/>
      <isd:option key="FullHomeInterfaceName" value="home-name" />
   </isd:provider>
   <isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener>
</isd:service>

In the example,

• service-urn and exposed-methods have the same meaning as in the standard Java class deployment descriptor.
• provider-class is one of the following depending on the implementation of the bean:

  Provider class	Bean implementation
  com.ibm.soap.providers.WASStatelessEJBProvider	stateless session bean
  com.ibm.soap.providers.WASStatefulEJBProvider	stateful session bean
  com.ibm.soap.providers.WASEntityEJBProvider	entity bean

• jndi-name is the registered JNDI name of the enterprise bean.
• home-name is the fully qualified class name of the enterprise bean's home interface.

Bean Scripting Framework (BSF) script deployment descriptor

A deployment descriptor that publishes a service that is implemented with a BSF script can look like the following example:

<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.
• language-name is the name of the BSF-supported language that you use to write the script.

The deployment descriptor must also have a source attribute on the <script> element, or a script-body attribute. The script-body attribute contains the script that is used to provide the service. If the deployment descriptor has the source attribute, then source-filename refers to the file that contains the service implementation.