WebReference.com - Part 2 of chapter 3 from Professional Java Web Services, Wrox Press Ltd. (2/5)

[previous] [next]

Professional Java Web Services

Service Element

All elements within the deployment descriptor are prefixed with isd as a name identifier, which is associated with the https://xml.apache.org/xml-soap/deployment namespace. The service element is the root element.

<isd:service xmlns:isd="https://xml.apache.org/xml-soap/deployment"
                    id="urn:HelloWorldService">
  ...
</isd:service>

All other elements are contained within the service element. The service element contains an id attribute, an optional type, and an optional checkMustUnderstands attribute. The id attribute is used to specify the name of the service. SOAP clients use the value of the id attribute to route requests to the service. In our case, we used the Uniform Resource Name (URN) syntax to specify the name of the service as "urn:HelloWorldService". However, this isn't required; the value of the id attribute can have any value and any format as long as the SOAP client uses the same value to refer to the service. With that being said, SOAP clients can specify "urn:HelloWorldService" for requests to be forwarded to the "Hello World" service.

The optional type attribute has a value of "message" if a service is message-oriented instead of RPC-based. In a message-oriented service, the service implementation is responsible for processing the contents of the SOAP Envelope. Therefore, it has full control of how the SOAP Envelope should be processed. So, any XML document may be passed as part of the envelope body. Also, a message-oriented service is responsible for sending responses back to a SOAP client. For example, if the message-oriented service is participating in a request-response protocol such as HTTP, then it is responsible for generating the appropriate response when a request is received. On the other hand, an RPC-based service doesn't have this type of granular control. When a SOAP message is received from a RPC-based service it's the responsibility of the Apache SOAP run-time environment to do the following: process the SOAP envelope, dispatch the RPC method call request to the service implementation class, and forward the response back to the SOAP client.

The optional checkMustUnderstands attribute can have a value of "true" or "false" depending upon whether or not we want the server to throw a fault if there are SOAP headers in a SOAP request message that have the MustUnderstand attribute set to "true". More information about the MustUnderstand attribute is located in the The Protocol section of Chapter 2.

Provider Element

The provider element contains attributes and sub-elements that specify the details of the code artifact that's implementing the service. The provider element for the "Hello World" service deployment descriptor is below:

<isd:provider type="java"
                scope="Application"
                methods="getMessage">
  <isd:java class="com.wrox.helloworld.service.HelloWorld" static="false"/>
</isd:provider>

The type attribute tells the Apache SOAP run-time environment which provider should be used to handle the code artifact. The type attribute is java for the above provider element since the code artifact for the "Hello World" service is a standard Java class. If the code artifact were an Enterprise JavaBean (EJB) then the value would be 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. If the code artifact were a BSF-supported script then the value would be "script".

The scope attribute indicates the lifetime of the instantiation of the implementing class. The attribute can contain three different values. The values are listed in the table below:

Value	Meaning
Request	Indicates that the object will be removed from memory after this request has completed
Session	Indicates that the object will last for the current lifetime of the HTTP session (Assuming that HTTP is used as the transport protocol)
Application	Indicates that the object will last until the servlet that is servicing the requests is terminated.

Note that the above values are the same as the scope options that are available when using JavaBeans with JavaServer Pages.

The methods attribute contains a space-separated list of methods we want to expose through the service. We want to expose the getMessage() method so it is specified as the value of the method attribute. A related attribute, contained within the java sub-element called class, should contain the fully qualified name of the class (that is, packagename.classname) that provides the methods being exposed.

The static attribute has a value of true or false depending upon whether or not the methods that are being exposed are static or not. In the above deployment descriptor, the static attribute has a value of "false" since the getMessage() method isn't defined as static.

Fault Listener Element

As discussed in the previous chapter, the SOAP specification defines the SOAP Fault element as a mechanism for reporting errors that occur when processing SOAP messages. Errors can arise for a number of reasons, for example, errors within the service implementation, malformed SOAP client request, network transmission problems, or a host of other problems. The Apache SOAP run-time will attempt to capture an error state and then construct a SOAP Fault message containing a base set of information about the error that occurred. In some cases it's useful to augment the fault information for a particular service or to perform one or more additional tasks when an error state arises. This type of fault handling mechanism is provided by Apache SOAP through the use of a pluggable fault handling mechanism into which one or more fault listeners may be registered to process faults. The pluggable fault handling mechanism is based on the event/listener model, which means that the fault listener remains idle until an event occurs.

The faultListener element is used to specify the fault listener that should be used with a service. The value has to be the fully qualified name of a class that implements the SOAPFaultListener interface. Apache SOAP provides two basic fault handlers; they are listed below:

• org.apache.soap.server.DOMFaultListener
• org.apache.soap.server.ExceptionFaultListner

The org.apache.soap.server.DOMFaultListener fault handler is usually used because it adds a DOM element representing the root exception that occurred, whereas the org.apache.soap.server.ExceptionFaultListner fault handler wraps the root exception in a parameter. Below is how the faultListener attribute would look with org.apache.soap.server.DOMFaultListener as the value:

<isd:faultListener>org.apache.soap.server.DOMFaultListener</isd:faultListener>

[previous] [next]

Created: May 23, 2002
Revised: May 23, 2002

URL: https://webreference.com/programming/java/webservices/chap3/2/2.html