This chapter describes the JMS RA implementation, including the main components, design options, and other prerequisite considerations needed to use the JMS RA to interoperate using WebLogic JMS in a foreign application server.
The JMS RA has the following basic components:
ra.xml file: An xml file used to configure the JMS RA to interoperate between foreign application servers and WebLogic JMS.
wlthint3client.jar file: The WebLogic Thin T3 java client is a light-weight client that provides integration between applications running on foreign application servers and WebLogic Server. One common use case is integration with WebLogic JMS destinations. See "Understanding the WebLogic Thin T3 Client" in Developing Stand-alone Clients for Oracle WebLogic Server.
Classes and JAR files for Oracle Wallet Support:
oraclepki.jar
osdt_cert.jar
osdt_core.jar
WalletUtilWrapper.class
weblogic.jms.ra.jar file: The WebLogic Server Java EE Connector Architecture version 1.6 compliant resource adapter implementation.
The following section provides a basic overview of the steps required to integrate the JMS RA with a foreign application server, allowing applications to interoperate with WebLogic JMS.:
The application code needs to be JMS compliant and may utilize supported weblogic.jms.extensions. For information on JMS RA features, support, and limitations, see Understanding the WebLogic JMS Resource Adapter and General Limitations and Considerations. For basic information on programing WebLogic JMS, see "Understanding WebLogic JMS" in Developing JMS Applications for Oracle WebLogic Server.
Configure the ra.xml file for your environment:
Deploy and manage the JMS RA. Use the foreign application server's native support for management tasks such as deployment, configuration, and monitoring. See:
The Oracle Fusion Middleware Error Messages Reference provides information about the error messages you may encounter when using the JMS RA and other Oracle Fusion Middleware components.
This section provides information on general limitations and considerations when using the JMS RA:
If two or more JMS RAs are deployed on the same application server, all the deployments must use the same WebLogic release version of the wljmsra.rar file. Different release versions may contain different classes due to changes in features and bug fixes and it is not possible to predict which version of the JMS RA's classes are loaded by the application server at any given time.
The JMS RA does not automatically unsubscribe (remove) a durable subscriber if the listening MDB becomes unavailable. Although WebLogic Server MDBs support the ability to unsubscribe, they also create and name the subscription. Foreign application servers typically allow users to specify subscription names in MDB configurations, making it difficult to determine if it is appropriate to unsubscribe a given durable subscriber. Even it can be determined that it is appropriate to remove a given subscription, the JCA contract does not provide a standard implementation to provide the callback interface to remove a subscriber.
Automatic JMS Client Failover is not supported. See JMS RA Outbound Connection Limitations.
Applications utilizing the WebLogic JMS RA utilize WebLogic JMS connections that are associated with a foreign application server's connection manager. These managed JMS connections are created, used, and retuned to the foreign application server's connection pool for reuse by other applications as outlined in various Java EE specifications. This has the following limitations:
Using setClientID on a connection is not allowed. Once a ClientID is set on a connection, it can not be removed and every application that reuses the connection unknowingly has a ClientID value. An application using such a connection is also prevented form calling setClientID as this operation has already been performed on the connection.
As specified by the JEE 6 specification, other methods that may interfere with connection management by the container, such as setExceptionListener, are not supported.
Set connection properties, such as setSubscriptionSharingPolicy, as part of the connection factory settings. Otherwise, you will need to ensure that the connection/session is created in the managed connection pool before attempting to set the property directly on the connection.
For a message-driven bean's message listener, only REQUIRED and NOT_SUPPORTED may be used for the value of the <trans-attribute> element. See http://docs.oracle.com/javaee/6/api/javax/ejb/TransactionAttributeType.html.
The following sections describe how this release of the JMS RA supports the weblogic.jms.extensions API.
The JMS RA uses custom wrapper classes to automatically implement the supported weblogic.jms.extensions interfaces and provide support for WebLogic features such as Unit-of-Order (UOO) and message scheduling. The JMS RA ra.xml file is pre-populated with entries corresponding to the correct WebLogic JMS wrapper classes so that you do not need any additional configuration to access supported WebLogic JMS features.
Note:
Use WebLogic Connection Factories when using weblogic.jms.extensions. See JMS RA Connection Factories.
This release of the JMS RA supports the following weblogic.jms.extensions interfaces
weblogic.jms.extensions.WLConnection
weblogic.jms.extensions.WLSession
weblogic.jms.extensions.WLQueueSession
weblogic.jms.extensions.WLTopicSession
weblogic.jms.extensions.WLDestination
weblogic.jms.extensions.WLMessageProducer
weblogic.jms.extensions.WLMessage
weblogic.jms.extensions.XMLMessage
All weblogic.jms.extensions are supported.
Oracle provides a JMS RA example for you to review when you install the examples in your WebLogic distribution. This example demonstrates how to utilize the JMS RA deployed on a foreign application server to interoperate with the WebLogic JMS service using a simple employee clock-in application.
The example illustrates how to:
Configure and use a WebLogic Server cluster
Configure and use WebLogic connection factories.
Configure and use distributed topics and queues.
Deploy the JMS RA to supported foreign application server. See Supported Application Servers.
Configure JMS RA config-properties which include:
A WebLogic JNDI context for the WebLogic Server providing the JMS service.
An adminobject element which map the local JNDI name sample/destination/queue to the destination bound to the WebLogic JNDI as DistributedQueue
An adminobject element which maps the local JNDI name sample/destination/topic to the destination bound in the WebLogic JNDI as DistributedTopic
A connection factory bound in the local JNDI name as sample/factory that maps to the connection factory bound to WebLogic's JNDI as weblogic.jms.ConnectionFactory.
Configure resource-ref and resource-env-ref elements in a servlet's web.xml that map to the local JNDI names defined for the JMS RA's connection factory and destinations.
Configure activation-config elements required to allow message-driven beans (MDBs) to consume inbound messages.
The JMS RA example is located in EXAMPLES_HOME\wl_server\examples\src\examples\jms\resourceAdapter, where EXAMPLES_HOME represents the directory in which the WebLogic Server code examples are configured. For more information, see "Sample Applications and Code Examples" in Understanding Oracle WebLogic Server.