Skip Headers
Oracle® Application Server Web Services Developer's Guide
10g Release 2 (10.1.2)
Part No. B14027-01
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

7 Developing and Deploying JMS Web Services

This chapter describes the procedures you use to configure, deploy, and build Oracle Application Server Web Services that expose JMS destinations, including JMS Queues and JMS Topics as Web Services. This chapter also covers writing a backend JMS message processor to consume incoming JMS messages and to generate outgoing JMS messages.

Oracle Application Server Web Services supports asynchronous message facilities with JMS Web Services.

This chapter covers the following topics:

7.1 JMS Web Services Overview

This section covers the following topics:

7.1.1 Using JMS Web Services

The sample code for JMS Web Services is supplied on the Oracle Technology Network Web site,

http://otn.oracle.com/tech/java/oc4j/demos/1012/index.html

After expanding the Web Services demo.zip file, the samples are in the demo1 and demo2 directories under webservices/demo/basic/jms_service on UNIX and webservices\demo\basic\jms_service.

JMS Web Services examples show both OC4J/JMS and Oracle JMS. In the samples, demo1 uses OC4J/JMS and demo2 uses Oracle JMS.

Using JMS Web Services, Oracle Application Server supplies a Servlet that supports two operations on messages: a send operation and a receive operation. Using these two operations, if the destination is a JMS Queue, send means enqueue, and receive means dequeue. If the destination is a topic, send means publish and receive means subscribe. An individual JMS Web Service can support just the send operation, just the receive operation, or both operations, as determined by the service developer.

The JMS Web Service determines how to handle incoming and outgoing messages for JMS destinations based on the configuration of the JMS Web Service and on the operation specified by the client-side program that uses the JMS Web Service. The Oracle Application Server Web Services runtime verifier throws an exception if the operation supplied by a JMS Web Service client is invalid. For example, if the deployment operation is send, and the request is receive, an exception is thrown.

The client-side message associated with a JMS Web Service is an XML document that conforms to the Document Object Model (DOM) as specified by the W3C (org.w3c.dom.Element). For a send operation, it is the client-side developer's job to deliver a message of the correct form to a JMS Web Service. And likewise, for a receive operation, the client must handle the message it receives from a JMS Web Service.


See Also:

http://java.sun.com/products/jms/ for information on JMS

7.1.2 JMS Web Services Backend Message Processing

A JMS Web Service consists of configuration information that defines the Web Service, and, in addition the server-side developer provides code that consumes the messages that a JMS Web Service client sends, or generates the messages that the client receives.

This section describes the architecture for processing JMS messages associated with a JMS Web Service and covers the following topics:

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

Runtime architecture of Oracle JMS Web Services.
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

Runtime architecture of an Oracle JMS Web Services.
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 Writing JMS Web Services and Handling Messages

Writing a JMS Web Service presents a server-side developer with two tasks:

  1. Building the backend message processing program for a JMS Web Service.

  2. Preparing and configuring a JMS Web Service.

This section covers the following:

7.2.1 Using an MDB for Backend Message Processing

When a JMS Web Service uses an MDB for generating or consuming messages, the MDB must be assembled with the JMS Web Service. In this case, the MDB is packaged as part of the J2EE .ear file that is deployed as a JMS Web Service.

Using an MDB with a JMS Web Service, the server-side developer is responsible for performing the following steps:

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.

Example 7-1 Sample Incoming onMessage() Method for JMS Web Service

  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.

Example 7-2 Sample Outgoing Message for JMS Web Service

// 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.2.2 Using a JMS Standalone Program for Backend Message Processing

Using a JMS standalone program on the backend for the JMS Web Service, the server-side developer is responsible for performing the following steps:

  1. Developing the JMS client that defines the JMS destinations, handles incoming messages, processes them, and produces the outgoing messages. The JMS client can also perform processing that uses a JMS destination that triggers an MDB.

  2. Assembling the JMS Web Service .ear file using the WebServicesAssembler tool and a configuration file containing the top-level tag <jms-doc-service>.

  3. Defining the resource references associated with JMS destinations in the OC4J/JMS jms.xml configuration file. If the JMS destinations are defined in Oracle JMS, then the developer must run the sql files that initialize the access to the Oracle JMS destinations.


    Note:

    When a JMS Web Service uses standalone a JMS client to consume or generate messages, the standalone client cannot be assembled with the JMS Web Service.

7.2.3 Message Processing and Reply Messages

The JMS Web Service processes an incoming message, a JMS Web Service send operation message, and places the message on a JMS destination. This section covers details that a developer needs to know to consume and process the JMS messages that originate from a JMS Web Service.

The client-side message associated with a JMS Web Service is an XML document that conforms to the Document Object Model (DOM) as specified by the W3C (org.w3c.dom.Element). When a JMS Web Service is sent an Element from a Web Service client, it creates a JMS ObjectMessage that contains the Element. The JMS Web Service may set certain header values before it places the message on a JMS destination. Depending on the values of optional configuration tags specified when the JMS Web Service is assembled, the JMS Web Service sets the following JMS Message Headers:

JMSType
JMSReplyTo
JMSExpiration
JMSPriority
JMSDeliveryMode

When the JMS Web Service sets the JMSReplyTo header, it uses either the value specified with the <reply-to-topic-resource-ref> or the <reply-to-queue-resource-ref> (only one of these should be configured for any given JMS Web Service). The value specified with the <reply-to-connection-factory-resource-ref> tag is set on the message as a standard string property. The property name is OC4J_REPLY_TO_FACTORY_NAME.

Example 7-3 provides a code segment that shows where the onMessage() method gets the ReplyTo information for message generated from a JMS Web Service send operation:

Example 7-3

  public void onMessage(Message inMessage) {
    // Do some processing
    ObjectMessage msg = null;
    String        factoryName;
    Destination   dest;
    Element       el;
    try {
      // Message should be of type objectMessage
      if (inMessage instanceof ObjectMessage) {
        // retrieve the object
        msg = (ObjectMessage) inMessage;
        el = (Element)msg.getObject();
        System.out.println("MessageBean2::onMessage() => Message received: " );
        ((XMLElement)el).print(System.out);
        processElement(el);
        factoryName = inMessage.getStringProperty("OC4J_REPLY_TO_FACTORY_NAME");
        dest = inMessage.getJMSReplyTo();
.
.
.

7.3 Preparing and Configuring JMS Web Services

This section describes how to use the Oracle Application Server Web Services tool WebServicesAssembler to prepare a J2EE .ear file for a JMS Web Service.

To deploy a JMS Web Service, you need to assemble a J2EE .ear file. The J2EE .ear file can include the following:

This section describes the procedures you use to create a configuration file to use with the WebServicesAssembler.

This section contains the following topics:

7.3.1 Creating a Configuration File to Assemble JMS Web Services

The Oracle Application Server Web Services assembly tool, WebServicesAssembler, assists in assembling Oracle Application Server Web Services. This section describes how to create an XML configuration file that describes the JMS Web Service to be assembled.

Create WebServicesAssembler configuration file by adding the following:

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.

Table 7-1 Top Level WebServicesAssembler Configuration Tags

Tag Description
<context> context</context> Specifies the context root of the Web Service.

This tag is required.

<datasource-JNDI-name> name</datasource-JNDI-name> Specifies the datasource associated with the Web Service.
<description> description</description> Provides a simple description of the Web Service.

This tag is optional.

<destination-path> dest_path</destination-path> Specifies the name of the generated J2EE .ear file output. The dest_path specifies the complete path for the output file.

This tag is required.

<display-name> disp_name</display-name> Specifies the Web Service display name.

This tag is optional.

<option name="source-path"> path<option> Includes a specified file in the output .ear file. Use this option to specify java resources, or the name of an existing .war, .ear, or ejb-jar file that is used as a source file for the output J2EE .ear file.

When a .war file is supplied as input, the optional contextroot specifies the root-context for the .war file.

path1 specifies the context-root for the .war.

path2 specifies the path to the file to include.

For example:

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

This tag is optional.

<jms-doc-service> sub-tags</jms-doc-service> Use this tag to add a JMS Web Service. See Table 7-2 for a description of the valid sub-tags.
<temporary-directory> temp_dir</temporary-directory> Specifies a directory where the assembler can store temporary files.

This tag is optional.


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.

Table 7-2 JMS Service WebServicesAssembler Configuration Tags

Tag Description
<connection-factory-resource-ref> resource-ref</connection-factory-resource-ref> Specifies the Topic Connection Factory or Queue Connection Factory resource reference resource-ref for the JMS destination associated with the JMS Web Service.

This tag is required.

<jms-delivery-mode> delivery-mode</jms-delivery-mode> Sets the JMSDeliveryMode message header to the specified delivery-mode value for the JMS message that is created with a send operation.

This tag is valid when the <operation> value is: send or both

This tag is optional.

<jms-expiration> expiration</jms-expiration> Sets the JMSExpiration message header to the specified expiration value for the JMS message that is created with a send operation.

This tag is valid when the <operation> value is: send or both

This tag is optional.

<jms-message-type> message-type</jms-message-type> Sets the JMSType for the message to the specified message-type for the JMS message that is created with a send operation

This tag is valid when the <operation> value is: send or both

This tag is optional.

<jms-priority> priority</jms-priority> Sets the JMSPriority message header to the specified priority value for the JMS message that is created with a send operation.

This tag is valid when the <operation> value is: send or both

This tag is optional.

<receive-timeout> timeout</receive-timeout> Provides a configurable timeout value to specify the receive timeout in milliseconds. This specifies the time in milliseconds that a receive operation waits for a new message.

This tag is valid when the <operation> value is: receive or both

When this tag is not specified or when the value is set to 0, a JMS receive operation blocks indefinitely. Valid values are 0 and positive integers.

Default value: 0

This tag is optional.

<operation> op</operation> Specifies the operation op that the JMS Web Service supports.

Using the send and receive operation:

  • If the destination is a JMS Queue, send means enqueue, and receive means dequeue.

  • If the destination is a topic, send means publish and receive means subscribe.

The send operation uses the <connection-factory-resource-ref> and the corresponding JMS destination <queue-resource-ref> or <topic-resource-ref> to determine the JMS destination for a send operation on the service.

With the receive operation, when the <reply-to-connection-factory-resource-ref> tag is not set, then the receive operation uses the <connection-factory-resource-ref> and the corresponding JMS destination <queue-resource-ref> or <topic-resource-ref>. When the <reply-to-connection-factory-resource-ref> tag is set, then the <reply-to-*> tags specify the JMS destination for receive operations.

Valid values: send, receive, both

Default value: both

This tag is optional.

<queue-resource-ref> queue-ref</queue-resource-ref> Specifies the resource reference queue-ref of the destination JMS queue.

Either a <topic-resource-ref> or a <queue-resource-ref> must be specified, but not both. When a <queue-resource-ref> is specified, the <connection-factory-resource-ref> must refer to a corresponding Queue connection factory.

<reply-to-connection-factory-resource-ref> reply-to-conn-factory-res-ref</reply-to-connection-factory-resource-ref> If the <operation> specified is both, then receive operations use the <reply-to-connection-factory-resource-ref>. The specified reply-to-conn-factory-res-ref value specifies the JMS destination connection factory for receive operations. Also, if the MDB, or any JMS consumer, expects to send results back then the name of the destination connection factory to which the reply message will be sent has to be specified in this parameter.

See Also: "Message Processing and Reply Messages".

This tag is optional.

<reply-to-queue-resource-ref> reply-to-queue-res-ref</reply-to-queue-resource-ref> Specifies the resource reference reply-to-queue-res-ref of the destination JMS queue.

When a <reply-to-queue-resource-ref> is specified, the <reply-to-connection-factory-resource-ref> must refer to a corresponding Queue connection factory.

If the <reply-to-connection-factory-resource-ref> tag is set, then either a <reply-to-topic-resource-ref> or a <reply-to-queue-resource-ref> must be specified, but not both.

This tag is optional.

<reply-to-topic-resource-ref> reply-to-topic-res-ref </reply-to-topic-resource-ref> Specifies the resource reference reply-to-topic-res-ref of the destination JMS Topic.

When a <reply-to-topic-resource-ref> is specified, the <reply-to-connection-factory-resource-ref> must refer to a corresponding Topic connection factory.

If the <reply-to-connection-factory-resource-ref> tag is set, then either a <reply-to-topic-resource-ref> or a <reply-to-queue-resource-ref> must be specified, but not both.

This tag is optional.

<topic-resource-ref> topic-ref</topic-resource-ref> Specifies the resource reference topic-ref of the destination JMS Topic.

Either a <topic-resource-ref> or a <queue-resource-ref> must be specified, but not both. When a <topic-resource-ref> is specified, the <connection-factory-resource-ref> must refer to a corresponding Topic connection factory.

<topic-subscription-name> topic-name</topic-subscription-name> When a JMS provider supports durable JMS topics, the JMS Doc service supports using the durable topics. To specify a durable topic, use this tag to specify the topic-name. This tag is only valid when a <topic-resource-ref> is supplied.

This tag is optional.

<uri> URI</uri> This tag specifies servlet mapping pattern for the Servlet that implements the JMS Web Service. The path specified as the URI is appended to the <context> to specify the JMS Web Service location.

This tag is optional.


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.

Example 7-4 Sample WebServicesAssembler Configuration File for JMS 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>

7.3.2 Running WebServicesAssembler With JMS Web Services

After you create the WebServicesAssembler configuration file, you can generate a J2EE .ear file for the JMS Web Service. The J2EE EAR file includes Web Service servlet configuration information, including the generated file web.xml, and if the service includes MDBs, the ejb.jar file containing the implementation classes.

Run the Oracle Application Server Web Services assembly tool, WebServicesAssembler as follows:

java -jar WebServicesAssembler.jar -config my_jms_service_config

Where: my_jms_service_config is the configuration file that contains the <jms-doc-service> tag.

7.4 Deploying JMS Web Services

After creating the .ear file containing Java classes and the Web Services Servlet deployment descriptors, you can deploy the Web Service as you would any standard J2EE application stored in an .ear file (to run under OC4J).


See Also:

Oracle Application Server Containers for J2EE User's Guide in the Oracle Application Server 10g Documentation Library

7.5 Limitations for JMS Web Services

The JMS Web Service only supports messages of type ObjectMessage (javax.jms.Message.ObjectMessage).