Using JMS Resource Adapters in Java CAPS 6

There are three JMS resource adapters installed as part of CAPS 6 to be aware of:

• CAPS 6 ships with GlassFish V2 which bundles jmsra for use with Java MQ (also known as MQRA).
• CAPS 6 installation adds sun-jms-adapter into GlassFish V2. This is part of the JMSJCA project and is often referred to interchangeably as JMSJCA.
• GlassFish V2 also bundles genericjmsra for use with other JMS providers.

The recommendation is to always use sun-jms-adapter but there is no effective way to disable jmsra since it is tightly integrated into the GlassFish configuration and asadmin commands. There is no reason for CAPS users to use genericjmsra since sun-jms-adapter also supports other JMS providers.

Gotchas and recommendations for JMS usage in CAPS 6

1. Always use JMSJCA MDBs instead of 'standard' MDBs

If you require Message Driven Beans support, always use JCA MDBs within your EJB Modules rather than a standard Message Driven Bean. The activation config used in any standard MDBs you create will automatically use jmsra. The JCA MDB does not appear in the context-sensitive menu for your Enterprise Beans. You will find it under the Enterprise category:

2. Avoid use of asadmin jms commands

The jms commands available in asadmin assume jmsra is being used and are not yet compatible with sun-jms-adapter. As an example, you should not use

asadmin create-jms-resource

to create your connection pool and resource. Why would you want to do this? Let's assume we wish to create another connection factory and connection pool for external standalone clients to access the broker. We may do this because those clients require different redelivery settings than the standard resource pool connection settings inserted during the CAPS 6 installation.

You would start by defining the pool:

asadmin create-connector-connection-pool --raname sun-jms-adapter --connectiondefinition javax.jms.ConnectionFactory 
--property ConnectionURL=mq\://(default_JMS_host):UserName=admin:Password=admin ext-client-pool

Note the above syntax for specifying custom properties.

You would then bind the connector resource in JNDI:

asadmin create-connector-resource --poolname ext-client-pool jms/ext-client-resource

If you require managed destinations, you can create these destinations with:

asadmin create-admin-object --raname sun-jms-adapter --restype javax.jms.Queue --property DestinationProperties=Name\\=jmsqueue jms/jmsqueue

You can use the Admin Console to perform the above or to change any advanced settings.

3. Do not retrieve managed connection resource pools or destinations when using jndi:// or lookup:// with sun-jms-adapter

The sun-jms-adapter provides two ways to retrieve pre-configured connection factories and destinations, by lookup:// or by jndi://

a) by jndi:// - for JMS provider administered objects

This method may be used from repository-based configuration for UnifiedJMS and/or when retrieving JMSJCA managed resources in your JMSJCA MDBs. It will also be supported for JBI BC use.

You can use a connection URL of jndi:// to retrieve a non-managed JMS provider Connection Factory and specify the following associated options:

JMSJCA.UnifiedCF=<JNDI name of javax.jms.ConnectionFactory>
JMSJCA.TopicCF=<JNDI name of javax.jms.TopicConnectionFactory>
JMSJCA.QueueCF=<JNDI name of javax.jms.QueueConnectionFactory>
java.naming.factory.initial=com.sun.jndi.fscontext.RefFSContextFactory (for example)
java.naming.provider.url=file:///c:/temp/bindings (for example)
java.naming.security.principal=<username to connect to JNDI provider>
java.naming.security.credentials=<password to connect to JNDI provider>

Note 1: JMSJCA.TopicCF and JMSJCA.QueueCF are required for projects that still use JMS 1.0.2 such as all repository-based CAPS deployments.

NB: If you are using this method to retrieve connection factories from JMSJCA ensure that the factory you are attempting to retrieve is a bound connection factory of the intended JMS provider, and not a managed connection factory resource pool of another resource adapter such as MQRA. Anything created under JMS resources in the GlassFish Admin Console or using the asadmin jms commands will assume MQRA and should not be retrieved in this manner. You would normally use the admin tools provided by the desired JMS provider in order to bind these objects into JNDI.

If jndi:// is used for the connection URL, it may also be used for the destination retrieval. Again, the queue or topic specified must not be a non-managed JMS destination, and the actual destination name may be different to the lookup context name. You can always just use a destination name that is not looked up and if supported by your JMS provider, this will be created dynamically.

b) by lookup:// - for JMSJCA managed resources in the 'local' app server

This method may be used when retrieving JMSJCA managed resources in your JMSJCA MDBs and/or for JBI BC use. It is possible to use with repository-based CAPS but I would not recommend this since multiple connection factories may be required depending on whether queue or topic connections are required.

Using the lookup:// notation in the connection URL also requires a lookup context i.e. you must specify lookup://<resource_pool_name>. This will search in the JNDI default context of your app server. The resource pool name must be for a sun-jms-adapter / JMSJCA managed resource that is bound in the default context. Do not use this method to retrieve MQRA or genericra managed factories.

Some default sun-jms-adapter / JMSJCA managed resources are installed as part of CAPS 6 which can be looked up in this manner. More sun-jms-adapter resource pools can be created using the method described in point 2 above, if necessary.

The same applies again for destinations retrieved using lookup://<destination_name> - they must be JMSJCA managed.

Again, you can always specify a destination name that is not looked up and if supported by your JMS provider, this will be created dynamically.

Examples of valid connection URLs include: