7 Developing and Deploying JMS Web Services

7.1.2.1 Using an MDB for Message Processing

A JMS Web Service either sends messages to a JMS destination or receives messages from a JMS destination and can use an MDB on the backend for generating and consuming messages. For example, Figure 7-1 shows an MDB based JMS Web Service that, from the JMS Web Service client's view, handles both the message send and the message receive operations.

Figure 7-1 MDB Based JMS Web Service

Description of the illustration aswsv004.gif

Figure 7-1 includes an MDB that is configured to listen to a JMS destination. The MDB based JMS Web Service works with the following steps:

1. A JMS Web Service client performs a send operation on the JMS Web Service to send a message.

2. The JMS Web Service processes the incoming message and directs it to a JMS destination, JMS Destination 1.

3. The EJB container invokes the MDB listening on JMS Destination 1.

4. After processing the message an MDB produces a new message on JMS Destination 2. Producing and consuming messages could involve one or more MDBs. For example, a single MDB could be listing on JMS Destination 1 and the same MDB could also send the message to JMS Destination 2.

5. (Arrows 5 and 6) A JMS Web Service client performs a receive operation on the JMS Web Service to receive a message. The JMS Web Service consumes a message from the JMS destination, processes it, and passes the outgoing message to the client.

7.1.2.2 Using a JMS Client for Message Processing

Using a JMS client for message processing, the JMS Web Service does not assemble, deploy, or run the JMS code on the backend. A separate JMS program that runs outside of the JMS Web Service, as a standalone JMS client, is responsible for generating and consuming the JMS messages that are associated with the JMS Web Service.

For example, Figure 7-2 shows a JMS Web Service that use a server-side JMS client for message processing.

Figure 7-2 JMS Client Based JMS Web Service

Description of the illustration aswsv005.gif

The JMS Web service includes only configuration information that supports handling messages and using JMS destinations. The JMS client based JMS Web Service works with the following steps:

1. A JMS Web Service client performs a send operation on the JMS Web Service to send a message.

2. The JMS Web Service then processes the incoming message and directs it to JMS DEST 1.

3. The JMS client processes the incoming message on JMS DEST 1. The incoming message could be identified using a message listener, or by other means.

4. After processing the incoming message the JMS client may produce a new message on JMS DEST 2. The message on JMS DEST 2 could be produced by another JMS client or by the same JMS client.

5. (Arrows 5 and 6) A JMS Web Service client performs a receive operation on the JMS Web Service to receive a message. The JMS Web Service consumes an outgoing message from the JMS destination and passes the message to the client.

7.2.1.1 Developing the MDB that Processes Incoming Messages

The MDB that processes incoming messages, generated from a JMS Web Service send operation, must include an onMessage() method with the following characteristics:

• The onMessage() method should be declared as public, but not final or static

• The onMessage() method should have a return type of void

• The onMessage() method should have one argument of type javax.jms.Message. The JMS Web Service only supports messages of type ObjectMessage, so the MDB developer should cast the incoming JMS Web Service message to an ObjectMessage.

• The message payload is available from the message using the getObject() method on the incoming JMS message and casting to the Element type.

Example 7-1 shows an MDB method that handles an incoming JMS Message. Also see MessageBean.java in the demo1 directory for the complete code.

  public void onMessage(Message inMessage) {
        ObjectMessage msg = null;
    Element       e;
        try {
      // Message should be of type objectMessage
      if (inMessage instanceof ObjectMessage) {
        // retrieve the object
        msg = (ObjectMessage) inMessage;
        e = (Element)msg.getObject();
        processElement(e);
        this.send2Queue(e);
      } else {
        System.out.println("MessageBean::onMessage() => Message of wrong type: "
 + inMessage.getClass().getName());
      }     
    } catch (JMSException ex) {
      ex.printStackTrace();
      mdc.setRollbackOnly();
    } catch (Throwable te) {
      te.printStackTrace();
    }
  }

7.2.1.2 Developing the MDB that Generates Outgoing Messages

An MDB that generates an outgoing message, consumed by a JMS Web Service receive operation, must include code that produces a message on a JMS destination with the following characteristics:

• The message placed on the JMS destination should be of type: javax.jms.Message.ObjectMessage.

• Set the payload of the message using the setObject() method on the outgoing JMS message and casting to the java.io.Serializable type.

Example 7-2 shows a code fragment that creates an outgoing message of the correct type. For the complete code for this example, see MessageBean2.java in the demo2 directory.

// Create an Object Message
message = queueSession.createObjectMessage();
// Stuff the result into the ObjectMessage
((ObjectMessage)message).setObject ((java.io.Serializable)ee);                                             // Send the Message
queueSender.send(message);

7.2.1.3 Compiling and Preparing the MDB EJB.jar File

After compiling the MDB classes, create an EJB .jar file that includes the MDB and its required deployment information.

7.2.1.4 Assembling the JMS Web Service With the MDB

Assemble the MDB's EJB.jar file with the JMS Web Service .ear file using the WebServicesAssembler tool and a configuration file containing the top-level tag <option name=source-path"> that specifies the EJB .jar, and the <jms-doc-service> that defines the JMS Web Service configuration.

7.2.1.5 Defining the Server-Side Resource References

Define the resource references associated with the JMS destinations that the JMS Web Service uses:

• If the MDB uses OC4J/JMS, define the resource references in the OC4J jms.xml configuration file.

• If the MDB uses Oracle JMS, then run the sql files that support access to the Oracle JMS destinations.

  
  

  See Also: Chapter 3, "AQ Programmatic Environments" in the Application Developer's Guide - Advanced Queuing in the Oracle9i Database Documentation library

  
  

7.3.1.1 Adding Web Service Top Level Tags

Table 7-1 describes the top level WebServicesAssembler configuration file tags. Add these tags to provide top level information describing the JMS Web Service.

Example 7-4 shows a complete JMS Web Service sample configuration file. The demo1 and demo2 directories in the jms_service directory contain complete config.xml files for JMS Web Services.

<option name="source-path" contextroot="/test">/myTestArea/ws/src/statefull.war</option>

7.3.1.2 Adding JMS Doc Service Tags

The <jms-doc-service> defines the configuration information for a JMS Web Service. The JMS Web Service developer determines if the service supports send operations, receive operations, or both send and receive, based on the value of the <operation> sub-tag. Some of the configuration file tags are only valid, depending on the operation selected for the Web Service. Table 7-2 lists all the supported <jms-doc-service> sub-tags, and includes information on whether each is valid, based on the operation specified.

7.3.1.3 Adding WSDL and Client-Side Proxy Generation Tags

The WebServicesAssembler supports the <wsdl-gen> and <proxy-gen> tags to allow a Web Service developer to generate WSDL files and client-side proxy files. You can use these tags to control whether the WSDL file and the client-side proxy are generated. Using these tags you can also specify that the generated WSDL file or a WSDL file that you write is packaged with the Web Service J2EE .ear.

A client-side developer either uses the WSDL file that is obtained from a deployed Web Service, or the client-side proxy that is generated from the WSDL to build an application that uses the Web Service.

<web-service>
  <display-name>JMS Web Service Example</display-name> 
  <description>JMS Web Service Example</description>
   <!-- Name of the destination --> 
  <destination-path>./jmsws1.ear</destination-path> 
  <temporary-directory>./tmp</temporary-directory> 
  <!-- Context root of the application -->
  <context>/jmsws1</context> 
  <!-- Path of the jar file with MDBs definied/implemented in it -->
  <option name="source-path">MDB/mdb_service1.jar</option>

  <!--  tags for jms doc service  -->
  <jms-doc-service>
    <uri>JmsSend</uri> 
    <connection-factory-resource-ref>jms/theQueueConnectionFactory</connection-factory-resource-ref> 
    <queue-resource-ref>jms/theQueue</queue-resource-ref> 
    <operation>send</operation>x
  </jms-doc-service>

  <jms-doc-service>
    <uri>JmsReceive</uri> 
    <connection-factory-resource-ref>jms/logQueueConnectionFactory</connection-factory-resource-ref> 
    <queue-resource-ref>jms/logQueue</queue-resource-ref> 
    <operation>receive</operation>
   </jms-doc-service>
    <!-- generate the wsdl -->
    <wsdl-gen>
           <wsdl-dir>wsdl</wsdl-dir>
           <!-- over-write a pregenerated wsdl , turn it 'false' to use the pregenerated wsdl-->
           <option name="force">true</option>
           <option name="httpServerURL">http://localhost:8888</option>
           <!-- do not package the wsdl -generate it again on the server-->
           <option name="packageIt">false</option>
    </wsdl-gen>
    <!-- generate the proxy -->
    <proxy-gen>
           <proxy-dir>proxy</proxy-dir>
           <option name="include-source">true</option>
    </proxy-gen>
</web-service>