FAQs: Integrating Remote JMS Providers

Understanding JMS and JNDI Terminology

Q. What is a remote JMS provider?

A. A remote JMS provider is a JMS server that is hosted outside a local standalone WebLogic Server or outside a WebLogic Server cluster. The remote JMS server can be a WebLogic or a non-WebLogic (foreign) JMS server.

Q. What is JNDI?

A. JNDI is the Java API for accessing naming and directory services. WebLogic Server uses it to expose resources such as connection factories, destinations, data sources and enterprise beans. Applications can look up resources by their configured names.

Cluster-wide bindings can make resources available through the cluster's naming service without requiring the application to know the hosting server. Lookup and use remain subject to binding scope, resource availability and security permissions.

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 client ID?

A. A client ID identifies a connection for subscription identity where the selected subscription API requires it. For the standard classic APIs, Session.createDurableConsumer() and Session.createDurableSubscriber() require a client ID; Session.createSharedDurableConsumer() can create a shared durable subscription without one. WebLogic's Restricted client-ID policy enforces exclusive registration within its applicable scope. Unrestricted policy permits multiple connections to use the same client ID. Subscription-sharing rules still apply; matching client IDs do not merge subscriptions on different physical distributed-topic members. See Developing Advanced Pub/Sub Applications.

Q. What is the difference between a JMS topic and a JMS queue?

A. Queue consumers compete for messages on a queue. For a topic, delivery is organized by subscriptions: each eligible subscription can receive a copy, and consumers of a shared subscription share delivery of that subscription's messages. Selection, acknowledgement, redelivery and expiration rules still apply.

Q. What is a topic subscription?

A. A subscription represents a topic's delivery relationship with one or more consumers. Messages published while it exists are considered for that subscription according to its selection rules. A subscription can be shared or unshared and durable or non-durable. Creating a new subscription does not retrieve messages published before that subscription existed. Reopening an existing durable subscription can make messages previously retained for that subscription available.

Q. What is a non-durable topic subscriber?

A. A non-durable subscription exists while its consumer, or at least one consumer of a shared subscription, remains active. The standard shared non-durable APIs use a subscription name. WebLogic also supports policy-based sharing through traditional subscriber APIs, as described in Shared Subscriptions and Client ID Policy. A non-durable subscription does not preserve a backlog for consumption after that subscription has ended, and persistent delivery mode does not make the subscription durable.

Q. What is a durable subscriber?

A. A durable subscription retains eligible messages while it has no active consumer, subject to expiration and other applicable policies. Its identity includes the subscription name and any client ID required by the chosen API. For WebLogic distributed topics, subscriptions on different physical members remain separate. Persistent messages can be recovered with the durable subscription after a server restart, subject to the persistent store and recovery configuration. See Developing Advanced Pub/Sub Applications.

Understanding Transactions

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 ensure data consistency. For example, to ensure 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 the message 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. Jakarta Transactions (JTA) coordinates global transactions that can include multiple enlisted resources, such as JMS and JDBC resources. XA provides the resource-manager interface used for distributed transaction coordination. UserTransaction is an API for application-managed transaction demarcation, not another transaction type. A transaction can be associated with a thread, suspended and resumed, or propagated through supported invocation paths.

Q. What is a local transaction?

A. A local JMS transaction groups sends and receives performed through one transacted session. It does not include JDBC work or operations through another session or JMS provider.

Q. How does JMS provide local transactions?

A. In the classic JMS API, create a transacted Session and use its commit or rollback methods. In the simplified API, use a locally transacted JMSContext where that mode is supported. Destination placement does not change the session transaction boundary. In Jakarta EE components, follow the container's transaction rules; a session participating in JTA is controlled by that JTA transaction.

Q. Are JMS local transactions useful for integration purposes?

A. Local JMS transactions are useful when the required atomic work fits within one transacted session. Use a global transaction when atomic completion must include separately enlisted resources, such as a database or another messaging provider.

Q. What is Automatic Transaction Enlistment?

A. Automatic enlistment means that the runtime associates a resource's work with the applicable JTA transaction without application code explicitly enlisting its XAResource. It requires a supported transaction integration and the appropriate connection-factory, resource and container configuration.

WebLogic JMS can participate through a transaction-enabled connection factory. WebLogic-managed JMS resource references and MDBs can provide transaction integration for supported third-party providers with the required XA capability. Messaging-bridge transaction behavior depends on its configured quality of service and adapter/provider support. A direct lookup of a foreign factory does not itself add WebLogic transaction management or pooling.

See Message-Driven EJBs, JMS resource-reference pools and Messaging Bridges for the supported configuration of each integration. Support for local transacted sessions alone does not establish XA/global transaction support.

How to Integrate with a Remote Provider

Q. What does a JMS client do to communicate with a remote JMS provider?

A. A typical client using the classic API performs these steps:

Look up a connection factory and destination using the configured naming service.
Create a Connection from the connection factory.
Create a Session, then create the required producer or consumer from that session.
For message consumption, start the connection when the application is ready to receive deliveries.
Close the application's JMS resources and naming context when finished.

The simplified API uses JMSContext in place of the separate Connection and Session. Follow the provider's supported API and the applicable standalone or container-managed lifecycle rules.

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 subscriptions, the subscription name and, where required, the client ID. For MDBs, follow the documented MDB subscription and identity configuration; do not infer all identity values solely from 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 usually 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.

For participation in a global JTA transaction, use a connection factory and integration configured for XA/global transactions. A local transacted session does not by itself require an XA-enabled factory.

When the legacy default connection factories are enabled, familiar built-in JNDI names include the following:
- 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.
Applications can also use configured connection factories. Jakarta EE components have the platform default connection factory at java:comp/DefaultJMSConnectionFactory. Select the factory and transaction settings required by the application; do not treat this list as the complete factory inventory.

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 Jakarta 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. WebLogic-managed JMS connection-factory references can pool connections, sessions and producers. Applications should close their logical handles so eligible resources can be reused. Ordinary resource-reference consumers are closed with their provider consumers; do not assume they are pooled. MDB containers manage their own connections, sessions and consumers for message delivery.

Q. Which 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 provider client	Depends on provider transaction integration and configuration; direct lookup alone adds none	No WebLogic-managed pool from direct use
Messaging bridge	Depends on configured QoS and adapter/provider transaction support	Managed internally by the bridge
Foreign JMS server definition	No transaction wrapper by itself; combine with an appropriate managed integration	No pool by itself
JMS resource reference	With the required managed transaction configuration and provider capability	Connections, sessions and producers; not ordinary consumers
JMS MDB	With supported container-managed transaction and provider configuration	Container-managed delivery resources
JMS SAF client	Local transacted sends are supported; do not assume participation in an application's global transaction	Not an application resource-reference pool
Server-side JMS SAF	A send to the local imported destination can participate when configured; later forwarding is asynchronous	Managed internally by SAF

Best Practices When Integrating with Remote Providers

Q. How do I receive messages from a remote 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 Message-Driven 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, then 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 a standalone client needs a global transaction involving a non-WebLogic JMS provider, use a supported transaction integration. One option is an EJB service that performs the messaging work on WebLogic Server using appropriately configured managed resources and an XA-capable provider.

For asynchronous forwarding to a third-party JMS provider, consider a local destination and a messaging bridge. For supported WebLogic-to-WebLogic forwarding, consider server-side JMS SAF or the JMS SAF client, according to where local storage is needed. See Using a Messaging Bridge, Using WebLogic Store-and-Forward and Using WebLogic JMS SAF Client.

A client can also use the remote provider's naming and messaging APIs directly, or look up configured foreign mappings through WebLogic JNDI. Include the required compatible provider libraries on the client classpath. Foreign mappings centralize lookup configuration; they do not themselves supply pooling or global transaction enlistment.

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.

Using Foreign JMS Server Definitions

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 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.

Using EJB/Servlet JMS Resource References

Q. What are JMS resource references?

A. A resource reference gives a component a logical name in its java:comp/env environment. Declare references through the supported annotations or component deployment descriptors and map them to the intended resources. For an application using the same compatible API, the deployment mapping can change without recompiling its resource lookup code.

WebLogic-managed connection-factory references can reuse eligible connection, session and producer resources after application handles are closed. They can also integrate with JTA when the provider and managed configuration support it.

Look up java:comp/env/<reference-name>, using the name actually declared for that component. For example, a reference named jms/QCF is looked up as java:comp/env/jms/QCF. The jms/ portion is part of the declared name, not an extra prefix added by the runtime.

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 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 are not 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. Choose connection-factory transaction capabilities according to the application's transaction requirements. For XA-capable sessions used outside an existing JTA transaction, the WebLogic wrappers can create an internal transaction for an operation. The behavior depends on the provider and operation; WebLogic JMS producer operations with native transaction integration do not require that wrapper-created transaction. Do not assume that every operation through an XA-capable factory incurs the same overhead. See Understanding Transactions.

Using WebLogic Store-and-Forward

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 when 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. Use JMS SAF for asynchronous forwarding to WebLogic JMS destinations in supported release combinations. Choose the local sending service and imported destinations for the required topology.

Between two stand-alone server instances
Between server instances in a cluster
Across two clusters in a domain
Across separate domains

Q. What limitations and design tradeoffs should I consider for JMS SAF?

A. JMS SAF forwards sends through local imported destinations to supported WebLogic JMS destinations. It is not a general consumer for a remote source and does not forward directly to third-party JMS products; use an MDB, client consumer or messaging bridge as appropriate. Temporary destinations are not supported as SAF reply destinations. Confirm the supported source/target release combination in WebLogic Server Compatibility.

For direct access to an available local destination, send directly unless the topology requires forwarding. SAF adds a forwarding stage and local resource requirements; assess latency, throughput, storage and quotas for the workload. These are design tradeoffs, not a blanket prohibition based on latency.

Using WebLogic JMS SAF Client

Q. What is the WebLogic JMS SAF Client?

A. The JMS SAF client provides local store-and-forward for standalone producers sending to WebLogic JMS destinations. It accepts messages into the client's configured local SAF environment and forwards them when the target becomes available, subject to persistence, expiration, error-handling and resource-limit settings. See Reliably Sending Messages Using the JMS SAF Client.

Q. When should I use the WebLogic JMS SAF Client?

A. Use the JMS SAF client when a standalone producer needs local buffering during connectivity interruptions and the target WebLogic release combination is supported. It is a sending facility, not a general remote-consumer API. Consult the client guide's requirements and limitations.

Q. What are the limitations of using the JMS SAF Client?

A. See Limitations of Using the JMS SAF Client.

Using a Messaging Bridge

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

Exactly-once bridge forwarding requires the corresponding QoS configuration and supported transaction-capable adapters, connection factories and providers. Do not infer that guarantee merely from a provider advertising XA capability. Configure whether QoS degradation is permitted and verify the bridge's effective QoS.

Q. When should I use a messaging bridge?

A. Use a bridge when the application needs asynchronous forwarding between supported JMS providers or destinations. A local source destination can let producers continue sending during a target outage, subject to source availability, quotas and expiration. To retain messages across failures, configure the required persistence and recovery; for a topic source, configure the required durable subscription. The bridge resumes forwarding when its connections and target become usable.

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.
For supported WebLogic-to-WebLogic store-and-forward topologies, consider JMS SAF. See Using WebLogic Store-and-Forward.

Q. Why are some of my messages not being forwarded?

A. Usually, 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, then 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 affect messages on the bridge source destination. If a redelivery limit option is enabled on the JMS provider that hosts the bridge source destination, then you may need to reconfigure the provider to prevent the bridge automatic retry mechanism from causing messages to exceed the redelivery limit.

Using Message-Driven Beans

Q. What is a Message Driven EJB (MDB)?

A. A JMS message-driven bean (MDB) is an enterprise bean whose container delivers messages to its onMessage method. The container manages delivery resources and lifecycle according to the MDB configuration. MDBs have the following characteristics:

Automatically connects to a source destination and automatically retries connecting if the remote destination is inaccessible.
Can process received messages in container-managed transactions when the transaction settings and provider integration support it.
Automatically pool their internal JMS connections, sessions, and consumers.
Use supported annotations and deployment descriptors to configure delivery and transaction behavior; WebLogic settings and foreign mappings provide additional provider configuration.
The messaging processing application logic is contained in a single method callback onMessage().
A MDB is an EJB that supports transactions, security, JDBC, and other typical EJB actions.

See Message-Driven EJBs in Developing Jakarta Enterprise Beans Using Deployment Descriptors.

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 effect. 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 Server 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.
For container-managed transactional delivery, configure Container transaction management and the Required transaction attribute for the listener method, using supported annotations or descriptors. The connection factory and provider integration must support the required transactions; third-party transactional JMS integration requires the appropriate XA capability. An incompatible configuration can fail deployment or connection setup rather than silently become non-transactional. The container establishes the transaction for message processing and enlists the supported resources.

Using AQ JMS

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 standalone clients. AQ JMS uses a database connection and stores JMS messages in a database accessible to an entire WebLogic Server cluster, enabling the use of database features and tooling for data manipulation 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.

A FAQs: Integrating Remote JMS Providers