Java Web Services in a Nutshell - page 70

Endpoint javax.xml.messaging

JAXM 1.1; JWSDP 1.0
 public class Endpoint {  // Public Constructors  public Endpoint( String uri);  // Public Methods Overriding Object  public String toString(  );  // Protected Instance Fields  protected String id; 

The Endpoint class encapsulates the concept of a JAXM endpoint, which is the point of communication between a JAXM application client and its local messaging provider. A JAXM client typically builds a SOAP message containing source and destination Endpoint addresses, and delivers it to its local provider, which is responsible for delivering it. Similarly, a JAXM receiver will register with its local provider and supply the Endpoint for which it wishes to receive inbound messages.

An Endpoint is constructed from a URI, which is essentially an arbitrary string that represents a message destination. Here's an example of the construction of an Endpoint :

 Endpoint endpoint = new Endpoint("urn:SOAPRPecho"); 

When a message addressed to this endpoint is sent, the messaging provider is expected to convert the logical address urn:SOAPRPecho to the real address of the receiving JAXM messaging provider using configuration information supplied in an implementation-dependent manner. The actual endpoint address is typically carried in the message as part of a SOAP message header so that it can be interpreted by the receiving provider and used to locate the intended recipient. Both the WS-Routing and ebXML profiles include headers that carry this information.



JAXMException javax.xml.messaging

JAXM 1.1; JWSDP 1.0 serializable checked
 public class JAXMException extends javax.xml.soap.SOAPException {  // Public Constructors  public JAXMException(  ); 
    public JAXMException( Throwable cause); 
    public JAXMException( String reason); 
    public JAXMException( String reason, Throwable cause); 

JAXMException is a checked exception (derived from javax.xml.soap.SOAPException ) that is used to report errors encountered during the execution of methods of the JAXM API.

A JAXMException typically includes a text string giving a human-readable description of the error and, in some cases, may have an associated Throwable that represents the root cause of the problem. The four constructors allow a JAXMException to be created with any combination of text message and Throwable , which may subsequently be retrieved using the getMessage( ) and getCause( ) methods. Note that the Throwable attribute can be set either at construction time or by using the initCause( ) method. However, a java.lang.IllegalStateException is thrown if this method is called when the Throwable attribute has already been set.

Thrown By

ProviderConnection.{close( ) , createMessageFactory( ) , getMetaData( ) , send( )} , ProviderConnectionFactory.{createConnection( ) , newInstance( )}

JAXMServlet javax.xml.messaging

JAXM 1.1; JWSDP 1.0 serializable
 public abstract class JAXMServlet extends javax.servlet.http.HttpServlet {  // Public Constructors  public JAXMServlet(  );  // Protected Class Methods  protected static javax.xml.soap.MimeHeaders getHeaders(javax.servlet.http.HttpServletRequest req);
    protected static void putHeaders(javax.xml.soap.MimeHeaders headers, javax.servlet.http.HttpServletResponse res);  // Public Instance Methods  public void setMessageFactory(javax.xml.soap.MessageFactory msgFactory);  // Public Methods Overriding HttpServlet  public void doPost(javax.servlet.http.HttpServletRequest req,  javax.servlet.http.HttpServletResponse resp) 
        throws;  // Public Methods Overriding GenericServlet         
   public void init(javax.servlet.ServletConfig servletConfig)        
   throws javax.servlet.ServletException;   // Protected Instance Fields  protected javax.xml.soap.MessageFactory msgFactory; 

JAXMServlet is a skeleton servlet that can be subclassed to create a container-resident JAXM client. The subclass must do the following:

  • Declare that it implements either the OnewayListener or ReqRespListener interface

  • Install a suitable MessageFactory i n the init( ) method

  • Provide an implementation of the onMessage( ) method

A SOAP message is delivered to the servlet as an HTTP POST request and is therefore handled in the servlet's doPost( ) method, which converts the body of the request to a javax.xml.soap.SOAPMessage object. This object is then passed to the onMessage( ) method, which the JAXM client is required to implement.

A client should implement the OnewayListener interface if it does not intend to return a reply immediately. In this case, the onMessage( ) method has the following signature:

 public void onMessage(SOAPMessage message); 

The ReqRespListener interface is intended for clients that create a synchronous reply that is, the reply method is sent back as the body of the HTTP response message. This interface, therefore, has a variant of onMessage( ) that requires the client to construct and return a reply message:

 public SOAPMessage onMessage(SOAPMessage message); 

In the JAXM reference implementation, it is not possible to construct a working JAXM client that implements the ReqRespListener interface, since the message returned by onMessage( ) is ignored by the JAXM provider. All JAXM clients must, therefore, be asynchronous. It is possible, however, to use JAXMServlet as the base class for a SOAP message receiver that uses the SAAJ API and implements the ReqRespListener interface rather than a JAXM client (although this option is not available for the J2EE 1.4 platform, which does not include JAXM).

The conversion between the representation of a SOAP message in the body of an HTML request or response and the corresponding SOAPMessage is performed by a javax.xml.soap.MessageFactory . A suitable factory must be installed by overriding the init( ) method, calling super.init( ) , and then using the setMessageFactory( ) method. By default, JAXMServlet installs a factory that does not perform processing specific to any of the JAXM profiles. A client that wishes to handle profiled messages (e.g., for WS-Routing or ebXML TRP) must instead supply the message factory provided by that profile. These classes are implementation-dependent, but you can get one in a portable fashion by using the createMessageFactory( ) method of the ProviderConnection class, as the following code snippet shows:

 ProviderConnection conn = ProviderConnectionFactory.newInstance(  )
                        .createConnection(  );