9 Assembling Web Services with JMS Destinations

This chapter describes how to expose a JMS destination as a Web service. A JMS endpoint Web service exposes JMS destinations, either queues or topics, as document-literal style operations in the WSDL. The operation can be in either send or receive mode.

A JMS endpoint Web service can be considered to be a special case of the Java endpoint Web service. In a JMS endpoint Web service, the JMS endpoint implements Web service operations by sending and receiving JMS message objects.

Note:

There are differences between a Web service based on queues (or Oracle Streams Advanced Queuing (AQ)) in the database and a Web service based on a JMS destination. The AQ Web service is based on a configuration of queues that reside in the database. The JMS destination Web service is based on the configuration of a JMS provider in the middle tier. The JMS queues reside in a backend data source. This data source could be a database, a file-based system, or some other data repository.

If you want to construct a Web service from a queue or an AQ in the database, see "How to Assemble a Web Service from an Oracle Streams AQ".

If you want to use JMS as the transport mechanism to communicate with a Web service, see "Using JMS as a Web Service Transport" in the Oracle Application Server Advanced Web Services Developer's Guide.

Understanding JMS Endpoint Web Services

OracleAS Web Services enables you to create Web service endpoints that let you put messages on and take messages off JMS destinations. A JMS Web service endpoint is configured to transfer messages to and from a specific JMS destination or pair of destinations.

A JMS endpoint Web service can have the following operations.

send—the XML payload (SOAP body element) is sent to the corresponding JMS destination. A send operation can be configured so that JMS message properties can be set on each sent message to indicate the JMS reply-to destination, priority, expiration, and so on.
receive—a message is retrieved from the corresponding JMS destination, the content of the JMS message is used to create the SOAP response message body payload.
both—a service can offer both operations.

A JMS endpoint Web service can be configured so that message-ID, correlation-ID, and reply-to-destination JMS message properties can be transmitted as SOAP headers. With this configuration, the message property headers and their types are explicitly declared on the generated WSDL and schema so that the Web service client can use them.

If the destination is a JMS queue, then invoking the send operation means enqueue. Invoking the receive operation means dequeue.
If the destination is a topic, then the send operation means publish and the receive operation means subscribe.

An individual JMS endpoint Web service can support just the send operation, just the receive operation, or both operations, as determined by the service developer.

JMS endpoint Web services use javax.jms.ObjectMessage as the JMS message type. As content, it can carry an instance of javax.xml.soap.SOAPElement or a String representation of an XML fragment.

The WSDL generated for a send JMS endpoint Web service follows the Web Service-Interoperability (WS-I) Basic Profile 1.0 and is interoperable.

Figure 9-1 shows an MDB-based JMS endpoint Web service application that, from the JMS endpoint Web service's view, handles both the message send and the message receive operations. The figure also includes an MDB that is configured to listen to a JMS destination.

Figure 9-1 MDB-Based JMS Endpoint Web Service

This illustration is described in the text.

Description of "Figure 9-1 MDB-Based JMS Endpoint Web Service"

The following steps describe how the MDB-based JMS endpoint Web service application illustrated in Figure 9-1 works.

A Web service client sends a SOAP request to invoke the send operation on the JMS endpoint Web service.
The JMS endpoint Web service processes the incoming message and directs it to a JMS destination, JMS Destination 1.
The EJB container invokes the MDB listening on JMS Destination 1.
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.
(Arrows 5 and 6) A Web service client sends a SOAP request to perform a receive operation on the JMS endpoint Web service to retrieve a message. The JMS endpoint Web service consumes a message from the JMS destination, encloses it in a SOAP response message, and passes the outgoing SOAP response message to the client.

Steps for Assembling a JMS Endpoint Web Service

The following steps describe how to assemble a JMS Endpoint Web service with the WebServicesAssembler tool.

Generate the Web service EAR file by running the WebServicesAssembler with the jmsAssemble command or Ant task.

For the jmsAssemble command, you must specify either the JNDI name of the JMS connection factory used to obtain a connection for the JMS send operation (sendConnectionFactoryLocation) or the JNDI name of the JMS connection factory to be used as the default reply-to of all send operation JMS messages (replyToConnectionFactoryLocation). For more information on the jmsAssemble command and its required and optional arguments, see "jmsAssemble".

In the following example, jms/ws/mdb/theQueueConnectionFactory is the JNDI name of the JMS connection factory used to produce connections to the JMS queue for the JMS send operation.
- jms/ws/mdb/theQueue—the JNDI name of the JMS queue to which the send operation sends the SOAP message payload.
- jms/ws/mdb/logQueueConnectionFactory—the JNDI name of the JMS connection factory to be used for the reply-to queue.
- jms/ws/mdb/logQueue—the JNDI name of the JMS queue that will be set to each send message as the default reply-to destination. Because the linkReceiveWithReplyTo argument is enabled in this example, this reply-to destination is also used by the receive operation of the JMS endpoint Web service to retrieve messages.
The J2EE EAR file produced by this command includes the JMS endpoint Web service configuration information, including the WSDL and the generated web.xml file.

Command line:
```
java -jar wsa.jar -jmsAssemble
     -sendConnectionFactoryLocation jms/ws/mdb/theQueueConnectionFactory
     -sendQueueLocation jms/ws/mdb/theQueue
     -replyToConnectionFactoryLocation jms/ws/mdb/logQueueConnectionFactory
     -replyToQueueLocation jms/ws/mdb/logQueue
     -linkReceiveWithReplyTo true
     -targetNamespace http://oracle.j2ee.ws/jms-doc
     -typeNamespace http://oracle.j2ee.ws/jms-doc/types
     -serviceName JmsService
     -appName jms_service
     -context jms_service
     -input ./build/mdb_service.jar
     -uri JmsService
     -output ./dist
```
Ant task:
```
<oracle:jmsAssemble
         linkReceiveWithReplyTo="true"
         targetNamespace="http://oracle.j2ee.ws/jms-doc"
         typeNamespace="http://oracle.j2ee.ws/jms-doc/types"
         serviceName="JmsService"
         appName="jms_service"
         context="jms_service"
         input="./build/mdb_service.jar"
         uri="JmsService"
         output="./dist"
         sendConnectionFactoryLocation="jms/ws/mdb/theQueueConnectionFactory"
         sendQueueLocation="jms/ws/mdb/theQueue"
         replyToConnectionFactoryLocation="jms/ws/mdb/logQueueConnectionFactory"
         replyToQueueLocation="jms/ws/mdb/logQueue"/>
```
In this command and Ant task:
- jmsAssemble—Exposes a JMS destination (queue or topic) as a Web service. See "jmsAssemble".
- sendConnectionFactoryLocation—Specifies the JNDI name of the JMS ConnectionFactory used to obtain a connection for the JMS send operation. The type of ConnectionFactory must be consistent with the send destination. See "sendConnectionFactoryLocation".
- sendQueueLocation—Specifies the JNDI name of the JMS queue to be used for the JMS send operation. No default value is provided. See "sendQueueLocation".
- replyToConnectionFactoryLocation—Specifies the JNDI name of the JMS connection factory to be used as the default reply-to of all send operation JMS messages. The type of ConnectionFactory must be consistent with the reply-to destination. See "replyToConnectionFactoryLocation".
- replyToQueueLocation—Specifies the JNDI name of the JMS queue to be used as the default reply-to of all send operation JMS messages. See "replyToQueueLocation".
- linkReceivedWithReplyTo—Determines whether the receive operation will be linked to the reply-to destination. See "linkReceiveWithReplyTo".
- targetNamepace—Specifies the target namespace to be used in the generated WSDL. The value can be either a conforming HTTP URL, a non-conforming HTTP URL, or even a URI. See "targetNamespace".
- typeNamespace—Specifies the type namespace to be used in the schema types in the generated WSDL. The name that you specify will always be used and it will not be reversed. See "typeNamespace".
- serviceName—Specifies the service name. See "serviceName".
- appName—Specifies the name of an application. Usually, this name is used as a base value for other arguments like context and uri. See "appName".
- context—Specifies the root context for the web application. See "context".
- input—Specifies the directory or JAR containing the classes that should be copied to WEB-INF/classes. This argument will be added to the classpath used by the WebServicesAssembler. See "input".
- uri—Specifies the URI to use for the Web service. See "uri".
- output— Specifies the directory where generated files will be stored. If the directory does not exist, it will be created. See "output".
Deploy all of the JMS destinations.
Deploy the service and bind the application.

Deploy the EAR file in the standard manner into a running instance of OC4J. For more information on deploying EAR files, see Chapter 19, "Packaging and Deploying Web Services" and the Oracle Containers for J2EE Deployment Guide. The following is a sample deployment command:
```
java -jar <OC4J_HOME>/j2ee/home/admin_client.jar deployer:oc4j:localhost:port <user> <password> 
            -deploy 
            -file dist/jms_service.ear 
            -deploymentName jms_service 
            -bindWebApp default-web-site
```
The following list describes the parameters in this code example.
- <oc4jHome>—The directory containing the OC4J installation.
- <user>—The user name for the OC4J instance. The user name is assigned at installation time.
- <password>—The password for the OC4J instance. The password is assigned at installation time.
- default-web-site —The Web site to which the application will be bound. This is usually default-web-site. To configure Web sites, see the server.xml file in <OC4J_HOME>/j2ee/home/config.
(Optional) Check that deployment succeeded.

OracleAS Web Services provides a Web Service Test Page for each deployed Web service. See "How to Use the Web Services Test Page" for information on accessing and using the Web Service Test Page.
Generate the client-side code.

Generating a client-side proxy from a JMS endpoint Web service WSDL is the same as generating the proxy from any other WSDL. The JMS endpoint Web service WSDL is interoperable, in that it should be consumed by WS-I Basic Profile 1.0-compliant WSDL tools. For example, you can use a .NET WSDL tool to generate C# client stubs to communicate with an Oracle JMS endpoint Web service.
- For the J2SE environment, generate stubs (client proxies) for a J2SE Web service client by running the WebServicesAssembler tool with the genProxy command. For more information on generating and assembling client-side code for the J2SE environment, see Chapter 15, "Assembling a J2SE Web Service Client".
- For the J2EE environment, generate a service endpoint interface and a mapping file for a J2EE Web service client by running the WebServicesAssembler tool with the genInterface command. For more information on generating and assembling client-side code, see Chapter 14, "Assembling a J2EE Web Service Client".
For example, the following command generates stubs that can be used for a J2SE client:

Command line:
```
java -jar wsa.jar -genProxy 
                  -output build/src/client/ 
                  -wsdl http://localhost:8888/hello/JmsService?WSDL 
                  -packageName oracle.demo.jms_service
```
Ant task:
```
<oracle:genProxy  wsdl="http://localhost:8888/hello/JmsService?WSDL"
           output="build/src/client"
           packageName="oracle.demo.jms_service"
/>
```
In this command line and Ant task:
- genProxy—Creates a static proxy stub that can be used by a J2SE Web service client. See "genProxy".
- output—Specifies the directory where generated files will be stored. If the directory does not exist, it will be created. See "output".
- wsdl—Specifies the absolute file path, relative file path, or URL to a WSDL document. See "wsdl".
- packageName—Specifies the package name that will be used for generated classes if no package name is declared in the JAX-RPC mapping file. See "packageName".
This command generates the client proxies and stores them in the directory build/src/client. The client application uses the stub to invoke operations on a remote service. For more information on the required and optional arguments to genProxy, see "genProxy".
Compile and run the client.

List the appropriate JARs on the classpath before compiling the client. Table A-2, "Classpath Components for a Client Using a Client-Side Proxy" lists all of the JAR files that can possibly be used on the client classpath. As an alternative to listing individual JARs, you can include the client-side JAR, wsclient_extended.jar on the client classpath. This JAR file contains all the classes necessary to compile and run a Web service client. The classes are from the individual JAR files listed in Table A-2. See "Setting the Classpath for a Web Service Proxy" for more information on wsclient_extended.jar and the client classpath.

Message Processing and Reply Messages

The JMS endpoint Web service processes an incoming SOAP message and places the payload (the body element of the SOAP 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 endpoint Web service.

The JMS message content associated with a JMS endpoint Web service can be either an instance of javax.xml.soap.SOAPElement (which is also a subclass of org.w3c.dom.Element), or java.lang.String which is the string representation of the XML payload. The JMS endpoint Web service may set certain JMS message header values before it places the message on a JMS destination. Depending on the values of optional configuration arguments specified when the JMS endpoint Web service is assembled, the JMS endpoint Web service sets the following JMS message headers.

JMSType
JMSReplyTo
JMSExpiration
JMSPriority
JMSDeliveryMode

The JMS endpoint Web service sets the JMSReplyTo header with the value specified by the replyToTopicLocation or the replyToQueueLocation argument (only one of these should be configured for any given JMS endpoint Web service). The value specified with the replyToConnectionFactoryLocation argument is set on the message as a standard string property. The property name is OC4J_REPLY_TO_FACTORY_NAME.

Example 9-1 provides a code segment that shows where the onMessage() method gets the reply-to information for a message generated from a JMS endpoint Web service send operation:

Example 9-1 Getting Reply-To Information for a Message Generated by a Send Operation

...
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();
...

Limitations

See "Assembling Web Services with JMS Destinations".

Additional Information

For more information on:

using the Test Page to test Web service deployment, see Chapter 13, "Testing Web Services Deployment".
building J2EE Web service clients, see Chapter 14, "Assembling a J2EE Web Service Client".
building J2SE Web service clients, see Chapter 15, "Assembling a J2SE Web Service Client".
JAX-RPC handlers, see Chapter 16, "Using JAX-RPC Handlers".
using the WebServicesAssembler tool to assemble Web services, see Chapter 18, "Using WebServicesAssembler".
packaging and deploying Web services, see Chapter 19, "Packaging and Deploying Web Services".
JAR files that are needed to assemble a client, see Appendix A, "Web Service Client APIs and JARs".
Web services interoperability, see "Ensuring Interoperable Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.
using quality of service features in Web service clients, see "Managing Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.
adding security to a Web service, see the Oracle Application Server Web Services Security Guide.
adding reliability to a Web service, see "Ensuring Web Service Reliability" in the Oracle Application Server Advanced Web Services Developer's Guide.
adding an auditing and logging configuration to a Web service, see "Auditing and Logging Messages" in the Oracle Application Server Advanced Web Services Developer's Guide.
processing nonstandard data types, see "Custom Serialization of Java Value Types" in the Oracle Application Server Advanced Web Services Developer's Guide.
the JAX-RPC mapping file, see "JAX-RPC Mapping File Descriptor" in the Oracle Application Server Advanced Web Services Developer's Guide.
data types supported by OracleAS Web Services, see "Mapping Java Types to XML and WSDL Types" in the Oracle Application Server Advanced Web Services Developer's Guide.
Oracle JDeveloper tool support for Web service development, see the Oracle JDeveloper on-line help.