Enhanced Support for Using WebLogic JMS with EJBs and Servlets (2024)

Note:

• Injection should be enabled for the class. Depending on the class being used and the archive in which it is packaged, it may be necessary to specify a beans.xml file. For more information, see Using Contexts and Dependency Injection for the Java EE Platform in Developing Applications forOracle WebLogic Server.

• If the injected JMSContext is null and if your application fails, then review the server log. If the connection factory could not be found, you can see that error in the server log. If there is no error in the server log then the application failure is probably due to a missing beans.xml file.

When injecting a JMSContext object, you can use the @JMSConnectionFactory annotation to specify the product-specific global JNDI look up name of a connection factory to be used by the container.

Alternatively, you can specify a fully qualified resource reference name of the form java:comp/env/res-ref-name as follows:

@Inject@JMSConnectionFactory("java:comp/env/res-ref-name")private JMSContext context;

In this case, the resource reference name must be defined using a <resource-ref> element in the deployment descriptor that maps it to an appropriate product-specific global JNDI name. See Declaring a Wrapped JMS Factory using Deployment Descriptors.

If no lookup name is provided for the @JMSConnectionFactory annotation, then the Java EE platform default JMS connection factory (java:comp/DefaultJMSConnectionFactory) will be used.

The JMSContext injection cannot use the resource reference to determine whether the connection factory should use container authentication or application authentication. Instead, you can use the @JMSPasswordCredential annotation to specify the type of authentication required.

If you specify the @JMSPasswordCredential annotation then the connection factory will use password authentication, and the specified user and password. If the @JMSPasswordCredential annotation is not defined then the connection factory will use container authentication.

You can declare a JMS connection factory as part of an EJB or servlet by defining a resource-ref element in the ejb-jar.xml or web.xml file, respectively. This process creates a "wrapped" JMS connection factory that can benefit from the more advanced session pooling, automatic transaction enlistment, connection monitoring, and container-managed security features described in Improving Performance Through Pooling.

Here is an example of such a connection factory element:

<resource-ref> <res-ref-name>jms/QCF</res-ref-name> <res-type>javax.jms.QueueConnectionFactory</res-type> <res-auth>Container</res-auth> <res-sharing-scope>Shareable</res-sharing-scope></resource-ref>

This element declares that a JMS QueueConnectionFactory object be bound into JNDI, at the location:

java:comp/env/jms/QCF

This JNDI name is only valid inside the context of the EJB or servlet where the resource-ref is declared, which is what the java:comp/env JNDI context signifies.

In addition to this element, there must be a matching resource-description element in the ejb-jar.xml (for EJBs) or weblogic.xml (for servlets) file that tells the Java EE container which JMS connection factory to put in that location. Here is an example:

<resource-description> <res-ref-name>jms/QCF</res-ref-name> <jndi-name>weblogic.jms.ConnectionFactory</jndi-name></resource-description>

The connection factory specified here must already exist in the global JNDI tree. (This example uses one of the default JMS connection factories that is automatically created when the built-in WebLogic JMS server is used). To use another WebLogic JMS connection factory from the same cluster, include that connection factory's JNDI name inside the jndi-name element. To use a connection factory from another vendor, or from another WebLogic Server cluster, create a Foreign JMS Server.

If the JNDI name specified in the resource-description element is incorrect, then the application is still deployed. However, you will receive an error when you try to use the connection factory.

You can define a JMS destination resource in a web module, EJB module, application client module, or in an application deployment descriptor using the jms-destination or resource-env-ref descriptor elements.

The transaction enlistment, pooling, connection monitoring features take place in the connection factory, not in the destinations. However, this feature is useful for consistency, and to make an application less dependent on a particular configuration of WebLogic Server, since destinations can easily be modified by simply changing the corresponding jms-destination or resource-env-ref description, without having to recompile the source code

Declaring JMS Destinations Using the jms-destination Element

<jms-destination> <description>JMS Destination definition</description> <name>java:app/MyJMSDestination</name> <interface-name>javax.jms.Queue</interface-name> <destination-name>myQueue1</destination-name> <property> <name>Property1</name> <value>10</value> </property> <property> <name>Property2</name> <value>20</value> </property></jms-destination>

Declaring JMS Destinations Using the resource-env-ref Element

<resource-env-ref> <resource-env-ref-name>jms/TESTQUEUE</resource-env-ref-name> <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type></resource-env-ref>

java:comp/env/jms/TESTQUEUE

<resource-env-description> <resource-env-ref-name>jms/TESTQUEUE</resource-env-ref-name> <jndi-name>jmstest.destinations.TESTQUEUE</jndi-name></resource-env-description>

When including JMS modules in an enterprise application, you must list each JMS module as a module element of type JMS in the weblogic-application.xml descriptor file packaged with the application, and a path that is relative to the root of the Java EE application. Here is an example of a reference to a JMS module name Workflows:

<module> <name>Workflows</name> <type>JMS</type> <path>jms/Workflows-jms.xml</path></module>

Within any weblogic-foo descriptor file, such as EJB (weblogic-ejb-jar.xml) or WebApp (weblogic.xml), the name of the JMS module is followed by a number (#) separator character, which is followed by the name of the resource inside the module. For example, a JMS module named Workflows that contains a queue named OrderQueue, would have a name of Workflows#OrderQueue.

<resource-env-description> <resource-env-ref-name>jms/OrderQueue</resource-env-ref-name> <resource-link>Workflows#OrderQueue</resource-link></resource-env-description>

Note that the <resource-link> element is unique to WebLogic Server, and is how the resources that are defined in a JMS module are referenced (linked) from the other Java EE Application components.

The name element of a JMS connection factory resource specified in the JMS module must match the res-ref-name element defined in the referring EJB or WebApp application descriptor file. The res-ref-name element maps the resource name (used by java:comp/env) to a module referenced by an EJB.

For queue or topic destination resources specified in the JMS module, the name element must match the resource-env-ref field defined in the referring module descriptor file.

That name is how the link is made between the resource referenced in the EJB or web application module and the resource defined in the JMS module. For example:

<resource-ref> <res-ref-name>jms/OrderQueueFactory</res-ref-name> <res-type>javax.jms.ConnectionFactory</res-type></resource-ref><resource-env-ref> <resource-env-ref-name>jms/OrderQueue</resource-env-ref-name> <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type> </resource-env-ref>

If you apply the @Resource to a class, then the resource is made available in the comp/env context. The following is an example of how to inject a WebLogic JMS destination and connection factory resource in a Java EE application, including EJBs, MDBs, and servlets.

Example 4-1 is a Wrapped JMS Pooling Annotation example:

...// The "name=" or "type=" are not always required,// "mappedName=" is usually sufficient.@Resource(name="ReplyQueue", type=javax.jms.Queue.class, mappedName="jms/ReplyQueue") Destination rq;...@Resource(name="ReplyConnectionFactory", type=javax.jms.ConnectionFactory.class, mappedName = "jms/ConnectionFactory") ConnectionFactory cf;...

Injected resource dependencies are resolved when the host EJB or servlet is instantiated. You may not want injected resource because:

• The injection may prevent applications from deploying successfully if the container attempts to resolve references during deployment.

• You might want to defer reference resolution until the application is first invoked.

You can setup a non-injected resource reference by placing the @Resources annotation above the class definition. An application can resolve such references at runtime by looking up the reference in the bean context. As a best practice, the bean or servlet should also cache the result in order to avoid the overhead of repeated lookups as shown in Example 4-2:

For a full example, see EJB 3.0 Wrapper Without Injection.

...@Resources ({ @Resource(name="targetCFRef", mappedName="TargetCFJNDIName", type=javax.jms.ConnectionFactory.class), @Resource(name="targetDestRef", mappedName="TargetDestJNDIName", type=javax.jms.Destination.class)}) @Stateless(mappedName="StatelessBean")public class MyStatelessBean implements MyStateless { @Resource private SessionContext sctx; // inject the bean context private ConnectionFactory targetCF; private Destination targetDest; public void completeWorkOrder() { // Lookup the JMS resources and cache for re-use. Note that a // "java:/comp/env" prefix isn't needed for EJB3.0 bean contexts. if (targetCF == null) targetCF = (javax.jms.ConnectionFactory)sctx.lookup("targetCFRef"); if (targetDest == null) targetDest = (javax.jms.Destination)sctx.lookup("targetDestRef");...