Oracle9i Application Server Web Services Developer's Guide Release 2 (9.0.3) Part Number B10004-01 |
|
This chapter describes the procedures you use to configure, deploy, and build Oracle9iAS 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.
Oracle9iAS Web Services supports asynchronous message facilities with JMS Web Services.
This chapter covers the following topics:
This section covers the following topics:
The sample code for JMS Web Services is supplied in the demo1
and demo2
directories in $ORACLE_HOME/webservices/demo/basic/jms_service
on UNIX or in %ORACLE_HOME%\webservices\demo\basic\jms_service
on Windows.
JMS Web Services examples show both Orion JMS and Oracle JMS. In the samples, demo1
uses Orion JMS and demo2
uses Oracle JMS. Oracle JMS is recommended for use with JMS Web Services. Orion JMS examples are provided for demonstration purposes only.
Using JMS Web Services, Oracle9iAS 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 Oracle9iAS 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 |
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:
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 includes an MDB that is configured to listen to a JMS destination. The MDB based JMS Web Service works with the following steps:
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.
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.
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:
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.
Writing a JMS Web Service presents a server-side developer with two tasks:
This section covers the following:
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:
The MDB that processes incoming messages, generated from a JMS Web Service send
operation, must include an onMessage()
method with the following characteristics:
onMessage()
method should be declared as public
, but not final
or static
onMessage()
method should have a return type of void
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
.
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(); } }
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:
javax.jms.Message
.ObjectMessage
.
setObject()
method on the outgoing JMS message and casting to the java.io.Serializeable
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);
After compiling the MDB classes, create an EJB .jar file that includes the MDB and its required deployment information.
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.
Define the resource references associated with the JMS destinations that the JMS Web Service uses:
jms.xml
configuration file.
Using a JMS standalone program on the backend for the JMS Web Service, the server-side developer is responsible for performing the following steps:
WebServicesAssembler
tool and a configuration file containing the top-level tag <jms-doc-service>
.
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.
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:
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(); . . .
This section describes how to use the Oracle9iAS 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:
The Oracle9iAS Web Services assembly tool, WebServicesAssembler
, assists in assembling Oracle9iAS 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:
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.
WebServicesAssembler
Configuration Tags
Tag | Description |
---|---|
|
Specifies the context root of the Web Service. This tag is required. |
|
Specifies the datasource associated with the Web Service. |
|
Provides a simple description of the Web Service. This tag is optional. |
|
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. |
|
Specifies the Web Service display name. This tag is optional. |
|
Includes a specified file in the output .ear file. For a JMS Web Service, use this tag to specify the MDB source The path specifies the path to the file to include. |
|
Use this tag to add a JMS Web Service. See Table 7-2 for a description of the valid sub-tags. |
|
Specifies a directory where the assembler can store temporary files. This tag is optional. |
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.
WebServicesAssembler
Configuration Tags
Tag | Description |
---|---|
|
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. |
|
Sets the
This tag is valid when the This tag is optional. |
|
Sets the
This tag is valid when the This tag is optional. |
|
Sets the
This tag is valid when the This tag is optional. |
|
Sets the
This tag is valid when the This tag is optional. |
|
Specifies the operation op that the JMS Web Service supports.
Using the
The send operation uses the
With the receive operation, when the
Valid values: This tag is optional. |
|
Specifies the resource reference queue-ref of the destination JMS queue.
Either a |
|
If the See Also: "Message Processing and Reply Messages". This tag is optional. |
|
Specifies the resource reference reply-to-queue-res-ref of the destination JMS queue.
When a
If the This tag is optional. |
|
Specifies the resource reference reply-to-topic-res-ref of the destination JMS Topic.
When a
If the This tag is optional. |
|
Specifies the resource reference topic-ref of the destination JMS Topic.
Either a |
|
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 This tag is optional. |
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 teh 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>
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 Oracle9iAS 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.
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).
The JMS Web Service only supports messages of type ObjectMessage (javax.jms.Message
.ObjectMessage)
.
|
![]() Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|