Oracle® Application Server Web Services Developer's Guide 10g (10.1.3.1.0) Part Number B28974-01 |
|
|
View PDF |
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. |
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
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.
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
<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.
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();
...
For more information on:
using the Test Page to test Web service deployment, see Chapter 13, "Testing Web Service 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.