This chapter provides information on how to integrate WebLogic Server 12.1.3 with remote JMS providers. The Java EE standards for JMS (messaging), JTA (transaction), and JNDI (naming) work together to provide reliable java-to-java messaging between different host machines and even different vendors. Oracle WebLogic Server provides a variety of tools that leverage these APIs to aid integrating remote JMS providers into a local application.
Q. What is a remote JMS provider?
A. A remote JMS provider is a JMS server that is hosted outside a local stand-alone WebLogic server or outside WebLogic server cluster. The remote JMS server may be a WebLogic or a non-WebLogic (foreign) JMS server.
Q. What is JNDI?
A. JNDI (Java Naming and Directory Interface) is a Java EE lookup service that maps names to services and resources. JNDI provides a directory of advertised resources that exist on a particular stand-alone (non-clustered) WebLogic server, or within a WebLogic server cluster. Examples of such resources include JMS connection factories, JMS destinations, JDBC (database) data sources, and application EJBs.
A client connecting to any WebLogic server in a WebLogic cluster can transparently reference any JNDI advertised service or resource hosted on any WebLogic server within the cluster. The client doesn't require explicit knowledge of which particular WebLogic server in the cluster hosts a desired resource.
Q. What is a JMS connection factory?
A. A JMS connection factory is a named entity resource stored in JNDI. Applications, message driven beans (MDBs), and messaging bridges lookup a JMS connection factory in JNDI and use it to create JMS connections. JMS connections are used in turn to create JMS sessions, producers, and consumers that can send or receive messages.
Q. What is a JMS connection-id?
A. JMS connection-ids are used to name JMS client connections. Durable subscribers require named connections, otherwise connections are typically unnamed. Note that within a clustered set of servers or stand-alone server, only one JMS client connection may use a particular named connection at a time. An attempt to create new connection with the same name as an existing connection will fail.
Q. What is the difference between a JMS topic and a JMS queue?
A. JMS queues deliver a message to one consumer, while JMS topics deliver a copy of each message to each consumer.
Q. What is a topic subscription?
A. A topic subscription can be thought of as an internal queue of messages waiting to be delivered to a particular subscriber. This internal queue accumulates copies of each message published to the topic after the subscription was created. Conversely, it does not accumulate messages that were sent before the subscription was created. Subscriptions are not sharable, only one subscriber may subscribe to a particular subscription at a time.
Q. What is a non-durable topic subscriber?
A. A non-durable subscriber creates unnamed subscriptions that exist only for the life of the JMS client. Messages in a non-durable subscription are never persisted—even when the message's publisher specifies a persistent quality of service (QOS). Shutting down a JMS server terminates all non-durable subscriptions.
Q. What is a durable subscriber?
A. A durable subscriber creates named subscriptions that continue to exist even after the durable subscriber exits or the server reboots. A durable subscriber connects to its subscription by specifying topic-name, connection-id, and subscriber-id. Together, the connection-id and subscriber-id uniquely name the subscriber's subscription within a cluster. A copy of each persistent message published to a topic is persisted to each of the topic's durable subscriptions. In the event of a server crash and restart, durable subscriptions and their unconsumed persistent messages are recovered.
Q. What is a transaction?
A. A transaction is a set of distinct application operations that must be treated as an atomic unit. To maintain consistency, all operations in a transaction must either all succeed or all fail. See "Introducing Transactions" in Developing JTA Applications for Oracle WebLogic Server.
Q. Why are transactions important for integration?
A. Integration applications often use transactions to assure data consistency. For example, to assure that a message is forwarded exactly-once, a single transaction is often used to encompass the two operations of receiving the message from its source destination and sending to the target destination. Transactions are also often used to ensure atomicity of updating a database and performing a messaging operation.
Q. What is a JTA/XA/global transaction?
A. In Java EE, the terms JTA transaction, XA transaction, user transaction, and global transaction are often used interchangeably to refer to a single global transaction. Such a transaction may include operations on multiple different XA capable resources and even different resource types. A JTA transaction is always associated with the current thread, and may be passed from server to server as one application calls another. A common example of an XA transaction is one that includes both a WebLogic JMS operation and a JDBC (database) operation.
Q. What is a local transaction?
A. A JMS local transaction is a transaction in which only a single resource or service may participate. A JMS local transaction is associated with a particular JMS session where the destinations of a single vendor participate. Unlike XA transactions, a database operation can not participate in a JMS local transaction.
Q. How does JMS provide local transactions?
A. Local transactions are enabled by a JMS specific API called transacted sessions. For vendors other than WebLogic JMS, the scope of a transacted session is typically limited to a single JMS server. In WebLogic JMS, multiple JMS operations on multiple destinations within an entire cluster can participate in a single transacted session's transaction. In other words, it is scoped to a WebLogic cluster and no remote JMS provider to the JMS session's cluster can participate in a transaction.
Q. Are JMS local transactions useful for integration purposes?
A. Local transactions are generally not useful for integration purposes as they are limited in scope to a single resource, typically a messaging or database server.
Q. What is Automatic Transaction Enlistment?
A. Operations on resources such as database servers or messaging servers participate in a Java EE JTA transaction provided that:
the resource is XA transaction capable
the resource has been enlisted with the current transaction
the client library used to access the resource is transaction aware (XA enabled).
Automatic participation of operations on an XA capable resource in a transaction is technically referred to as automatic enlistment.
WebLogic clients using XA enabled WebLogic APIs automatically enlist operation in the current thread's JTA transaction. Examples of XA enabled WebLogic clients include WebLogic JMS XA enabled (or user transaction enabled) connection factories, and JDBC connection pool data sources that are global transaction enabled.
Foreign (non-WebLogic) JMS clients do not automatically enlist in the current JTA transaction. Such clients must either go through an extra step of programmatically enlisting in the current transaction, or use WebLogic provided features that wrap the foreign JMS client and automatically enlist when the foreign JMS client is accessed via wrapper APIs.
JMS features that provide automatic enlistment for foreign vendors are:
To determine if a non-WebLogic vendor's JMS connection factory is XA capable, check the vendor documentation. Remember, support for transacted sessions (local transactions) does not imply support for global/XA transactions.
Q. What does a JMS client do to communicate with a remote JMS provider?
A. To communicate with any JMS provider, a JMS client must perform the following steps:
Look up a JMS connection factory object and a JMS destination object using JNDI
Create a JMS connection using the connection factory object
Create message consumers or producers using the JMS connection and JMS destination objects.
Q. What information do I need to set up communications with a remote JMS provider?
A. You will need the following information to set up communications with a remote JMS provider:
The destination type—whether the remote JMS destination is a queue or a topic.
The JNDI name of the remote JMS destination.
For durable topic subscribers—the connection-id and subscriber-id names that uniquely identify them. Message Driven EJBs provide default values for these values based on the EJB name.
For non-WebLogic remote JMS providers
Initial Context Factory Class Name— the java class name of the remote JMS Provider's JNDI lookup service.
The file location of the java jars containing the remote JMS provider's JMS client and JNDI client libraries. Ensure that these jars are specified in the local JVM's classpath.
The URL of the remote provider's JNDI service. For WebLogic servers, the URL is normally in the form t3://hostaddress:port. If you are tunneling over HTTP, begin the URL with http rather than t3. No URL is required for server application code that accesses a WebLogic JMS server that resides on the same WebLogic server or WebLogic cluster as the application.
The JNDI name of the remote provider's JMS connection factory. This connection factory must exist on the remote provider, not the local provider.
If the JMS application requires transactions, the connection factory must be XA capable. WebLogic documentation refers to XA capable factories as user transactions enabled.
By default, WebLogic servers automatically provide three non-configurable connection factories:
weblogic.jms.ConnectionFactory—a non-XA capable factory.
weblogic.jms.XAConnectionFactory—an XA-capable factory
weblogic.jms.MessageDrivenBeanConnectionFactory—an XA-capable factory for message driven EJBs.
Additional WebLogic JMS connection factories must be explicitly configured.
Q. What if a foreign JMS provider JNDI service has limited functionality?
A. The preferred method for locating JMS provider connection factories and destinations is to use a standard Java EE JNDI lookup. Occasionally a non-WebLogic JMS provider's JNDI service is hard to use or unreliable. The solution is to create a startup class or load-on-start servlet that runs on a WebLogic server that does the following:
Uses the foreign provider's proprietary (non-JNDI) APIs to locate connection factories and JMS destinations.
Registers the JMS destinations and JMS connection factories in WebLogic JNDI.
Q. How can I pool JMS resources?
A. Remote and local JMS resources, such as client connections and sessions, are often pooled to improve performance. Message driven EJBs automatically pool their internal JMS consumers. JMS consumers and producers accessed through resource-references are also automatically pooled.
Q. What tools are available for integrating with remote JMS providers?
A. The following table summarizes the tools available for integrating with remote JMS providers:
| Method | Automatic Enlistment | JMS Resource Pooling |
|---|---|---|
| Direct use of the remote provider's JMS client | Yes for a WebLogic server provider. Other providers must perform enlistment programmatically. | No. Can be done programmatically. |
| Messaging Bridge | Yes | N/A |
| Foreign JMS Server Definition | No. To get automatic enlistment, use in conjunction with a JMS resource reference or MDB. | No. To get resource pooling, use in conjunction with a JMS resource reference or MDB. |
| JMS Resource Reference | Yes | Yes |
| Message Driven EJBs | Yes | Yes |
| SAF Client | N/A | N/A |
| SAF | Yes | N/A |
Q. How do I receive messages from a remote a JMS provider from within an EJB or Servlet?
A. Use a message driven EJB. Synchronous receives are not recommended because they idle a server side thread while the receiver blocks waiting for a message. See Using Messaging Beans.
Q. How do I send messages to a remote JMS provider from within an EJB or Servlet?
A. Use a resource reference. It provides pooling and automatic enlistment. See Using EJB/Servlet JMS Resource References. In limited cases where wrappers are not sufficient, you can write your own pooling code.
If the target destination is remote, consider adding a local destination and messaging bridge to implement a store-and-forward high availability design. See Using a Messaging Bridge.
Another best practice is to use foreign JMS server definitions. Foreign JMS server definitions allow an application's JMS resources to be administratively changed and avoid the problem of hard-coding URLs into application code. In addition, foreign JMS server definitions are required to enable resource references to reference remote JMS providers. See Using Foreign JMS Server Definitions.
Q. How do I communicate with remote JMS providers from a client?
A. If the destination is not provided by WebLogic Server, and there is a need to include operations on the destination in a global transaction, use a server proxy to encapsulate JMS operations on the foreign vendor in an EJB. Applications running on WebLogic server have facilities to enlist non-WebLogic JMS providers that are transaction (XA) capable with the current transaction.
If you need store-and-forward capability, consider sending to local destinations and using messaging bridges to forward the message to the foreign destination. See:
Another option is to simply use the remote vendor's JNDI and JMS API directly or configuring foreign JMS providers to avoid hard-coding references to them. You will need to add the foreign provider's class libraries to the client's class-path.
Q. How can I tune WebLogic JMS interoperability features?
A. See Tuning WebLogic Server EJBs, Tuning WebLogic Message Bridge, and Tuning WebLogic JMS Store-and-Forward in Tuning Performance of Oracle WebLogic Server.
Q. What are Foreign JMS Server Definitions?
A. Foreign JMS server definitions are an administratively configured symbolic link between a JNDI object in a remote JNDI directory, such as a JMS connection factory or destination object, and a JNDI name in the JNDI name space for a stand-alone WebLogic Server or a WebLogic cluster. They can be configured using the WebLogic Server Administration Console, standard JMX MBean APIs, or programmatically using scripting. See Simplified Access to Foreign JMS Providers.
Q. When is it best to use a Foreign JMS Server Definition?
A. For this release, a Foreign JMS Server definition conveniently moves JMS JNDI parameters into one central place. You can share one definition between EJBs, servlets, and messaging bridges. You can change a definition without recompiling or changing deployment descriptors. They are especially useful for:
Any message driven EJB (MDB) where it is desirable to administer standard JMS communication properties via configuration rather than hard code them into the application's EJB deployment descriptors. This applies even if the MDB's source destination isn't remote.
Any MDB that has a destination remote to the cluster. This simplifies deployment descriptor configuration and enhances administrative control.
Any EJB or servlet that sends or receives from a remote destination.
Enabling resource references to refer to remote JMS providers. See Using EJB/Servlet JMS Resource References.
Q. What are JMS resource references?
A. Resource references are specified by servlet and EJB application developers and packaged with an application. They are easy-to-use and provide a level of indirection that lets applications reference JNDI names defined in an EJB descriptor rather than hard-coding JNDI names directly into application source code.
JMS resource-references provide two additional features:
Automatic pooling of JMS resources when those resources are closed by the application.
Automatic enlistment of JMS resources with the current transaction, even for non-WebLogic JMS providers.
Inside an EJB or a servlet application code, use JMS resource references by including resource-ref elements in the deployment descriptors and then use JNDI a context to look them up using the syntax java:comp/env/jms/<reference name>.
Resource references provide no functionality outside of application code, and therefore are not useful for configuring a message driven EJB's source destination or a messaging bridge's source or target destinations.
For WebLogic documentation on JMS resource-reference pooling, see Chapter 4, "Enhanced Support for Using WebLogic JMS with EJBs and Servlets."
Q. What advantages do JMS resource references provide?
A. JMS resource references provide the following advantages:
They ensure portability of servlet and EJB applications: they can be used to change an application's JMS resource without recompiling the application's source code.
They provide automatic pooling of JMS Connection, Session, and MessageProducer objects.
They provide automatic transaction enlistment for non-WebLogic JMS providers. This requires XA support in the JMS provider. If resource references aren't used, then enlisting a non-WebLogic JMS provider with the current transaction requires extra programmatic steps.
Q. How do I use resource references with foreign JMS providers?
A. To enable resource references to reference remote JMS providers, they must be used in conjunction with a foreign JMS definition. This is because resources references do not provide a place to specify a URL or initial context factory. See Using Foreign JMS Server Definitions.
Q. How do I use resource references with non-transactional messaging?
A. For non-transactional cases, do not use a global transaction (XA) capable connection factory. This will impact messaging performance. If you do, the resource reference will automatically begin and commit an internal transaction for each messaging operation. See Understanding Transactions.
Q. What is the WebLogic Store-and-Forward Service?
A. The WebLogic Store-and-Forward (SAF) Service enables WebLogic Server to deliver messages reliably between applications that are distributed across WebLogic Server instances. For example, with the SAF service, an application that runs on or connects to a local WebLogic Server instance can reliably send messages to a destination that resides on a remote server. If the destination is not available at the moment the messages are sent, either because of network problems or system failures, then the messages are saved on a local server instance, and are forwarded to the remote destination once it becomes available. See Understanding the Store-and-Forward Service in Administering the Store-and-Forward Service for Oracle WebLogic Server.
Q. When should I use the WebLogic Store-and-Forward Service?
A. The WebLogic Store-and-Forward (SAF) Service should be used when forwarding JMS messages between WebLogic Server 9.0 or later domains. The SAF service can deliver messages:
Between two stand-alone server instances.
Between server instances in a cluster.
Across two clusters in a domain.
Across separate domains.
Q. When can't I use WebLogic Store-and-Forward?
A. You can't use the WebLogic Store-and-Forward service in the following situations:
Receiving from a remote destination—use a message driven EJB or implement a client consumer directly.
Sending messages to a local destination—send directly to the local destination.
Forwarding messages to prior releases of WebLogic Server. See Using a Messaging Bridge.
Interoperating with third-party JMS products (for example, MQSeries). See Using a Messaging Bridge.
When using temporary destinations with the JMSReplyTo field to return a response to a request.
Environment with low tolerance for message latency. SAF increases latency and may lower throughput.
Q. What is the WebLogic JMS SAF Client?
A. The JMS SAF Client feature extends the JMS store-and-forward service introduced in WebLogic Server 9.0 to standalone JMS clients. Now JMS clients can reliably send messages to server-side JMS destinations, even when the client cannot reach a destination (for example, due to a temporary network connection failure). While disconnected from the server, messages sent by a JMS SAF client are stored locally on the client file system and are forwarded to server-side JMS destinations when the client reconnects. See Reliably Sending Messages Using the JMS SAF Client.
Q. When should I use the WebLogic JMS SAF Client?
A. Use when forwarding JMS messages to WebLogic Server 9.0 or later domains.
Q. What are the limitations of using the JMS SAF Client?
Q. What is a messaging bridge?
A. Messaging bridges are administratively configured services that run on a WebLogic server. They automatically forward messages from a configured source JMS destination to a configured target JMS destination. These destinations can be on different servers than the bridge and can even be foreign (non-WebLogic) destinations. Each bridge destination is configured using the four common properties of a remote provider:
The initial context factory.
The connection URL.
The connection factory JNDI name.
The destination JNDI name.
Messaging bridges can be configured to use transactions to ensure exactly-once message forwarding from any XA capable (global transaction capable) JMS provider to another.
Q. When should I use a messaging bridge?
A. Typically, messaging bridges are used to provide store-and-forward high availability design requirements. A messaging bridge is configured to consume from a sender's local destination and forward it to the sender's actual target remote destination. This provides high availability because the sender is still able to send messages to its local destination even when the target remote destination is unreachable. When a remote destination is not reachable, the local destination automatically begins to store messages until the bridge is able to forward them to the target destination when the target becomes available again.
Q. When should I avoid using a messaging bridge?
A. Other methods are preferred in the following situations:
Receiving from a remote destination—use a message driven EJB or implement a client consumer directly.
Sending messages to a local destination—send directly to the local destination.
Environment with low tolerance for message latency. Messaging Bridges increase latency and may lower throughput. Messaging bridges increase latency for messages as they introduce an extra destination in the message path and may lower throughput because they forward messages using a single thread.
Forward messages between WebLogic 9.0 domains—Use WebLogic Store-and-Forward. See Using WebLogic Store-and-Forward.
Q. Why are some of my messages not being forwarded?
A. Normally, a messaging bridge should forward all messages. If some messages are not being forwarded, here are some possible reasons:
Some messages may have an expiration time, in which case either the JMS provider for the source or target destination expires the message.
If you configured the bridge source destination to specify a selector filter, only the filtered messages are forwarded.
A bridge does not directly provide an option to automatically move messages to an error destination, or to automatically delete messages, after a limited number of forward attempts. That said, it is possible that a JMS provider may provide such an option, which could, in turn, effect any messages on the bridge source destination. If a redelivery limit option is enabled on the JMS provider that hosts the bridge source destination, you may need to reconfigure the provider to prevent the bridge automatic retry mechanism from causing messages to exceed the redelivery limit.
Q. What is a Message Driven EJB (MDB)?
A. Message Driven EJBs are EJB containers that internally use standard JMS APIs to asynchronously receive messages from local, remote, or even foreign JMS destinations and then call application code to process the messages. MDBs have the following characteristics:
Automatically connects to a source destination and automatically retries connecting if the remote destination is inaccessible.
Support automatic enlistment of the received messages in container managed transactions, even when the JMS provider is not WebLogic.
Automatically pool their internal JMS connections, sessions, and consumers.
A MDB's source destination, URL, and connection factory are configured in the EJB and WebLogic descriptors which are packaged as part of an application.
The messaging processing application logic is contained in a single method callback onMessage().
A MDB is a full-fledged EJB that supports transactions, security, JDBC, and other typical EJB actions.
For more information, see Message-Driven EJBs in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.
Q. When should I use a MDB?
A. MDBs are the preferred mechanism for WebLogic server applications that receive and process JMS messages.
Q. Do I need to use a Messaging Bridge with a MDB?
A. Configure MDBs to directly consume from their source destination rather than insert a messaging bridge between them. MDBs automatically retry connecting to their source destination if the source destination is inaccessible, so there is no need to insert a messaging bridge in the message path to provide higher availability. Introducing a messaging bridge may have a performance impact. See Using a Messaging Bridge.
Q. What is the best way to configure a MDB?
A. The following section provides tips for configuring a MDB:
To configure MDB concurrency and thread pools, use the max-beans-in-free-pool and dispatch-policy descriptor fields. WebLogic may create fewer concurrent instances than max-beans-in-free-pool depending on the number of available server threads in the MDB's thread pool.
Use foreign JMS server definitions when configuring a MDB to consume from a remote JMS provider. Although WebLogic MDB descriptors can be configured to directly refer to remote destinations, this information is packaged with the application and is not dynamically editable. You should configure a foreign JMS server definition and then configure the MDB to reference the foreign definition instead. Please note that some documentation refers to foreign JMS server definitions as wrappers. See Using Foreign JMS Server Definitions.
Use care when configuring a MDB for container managed transactions. A MDB supports container managed XA transactions when a MDB's descriptor files have transaction-type of Container and a trans-attribute of Required and the JMS connection factory is XA enabled. Failure to follow these steps will result in the MDB being non-transactional. The default WebLogic setting for a MDB connection factory is XA enabled. The MDB automatically begins a transaction and automatically enlists the received message in the transaction.
Q. Can I interoperate with AQ JMS?
A. Oracle WebLogic Server applications interoperate with Oracle Streams Advanced Queuing (AQ) through the JMS API using either WebLogic Server resources (Web Apps, EJBs, MDBs) or stand-alone clients. AQ JMS uses a database connection and stored JMS messages in a database accessible to an entire WebLogic Server cluster, enabling the use of database features and tooling for data manipulating and backup.
Use the JMS Foreign Server configuration to interoperate with Oracle Streams Advanced Queuing (AQ) through the JMS API using either WebLogic Server resources (Web Apps, EJBs, MDBs) or stand-alone clients. See Interoperating with Oracle AQ JMS in Administering JMS Resources for Oracle WebLogic Server.
Q. How do I migrate my OC4J applications to WebLogic Server?
A. For information on how to migrate your applications from Oracle OC4J to Oracle WebLogic Server, see Oracle Fusion Middleware Upgrade Guide for Java EE.