Chapter 4 Configuring Java Message Service Resources

The Application Server implements the Java Message Service (JMS) API by integrating the Sun Java System Message Queue (formerly Sun ONE Message Queue) software into the Application Server. For basic JMS API administration tasks, use the Application Server Admin Console. For advanced tasks, including administering a Message Queue cluster, use the tools provided in the MQ-as-install/imq/bin directory. For details about administering Message Queue, see the Message Queue Administration Guide.

This chapter describes how to configure resources for applications that use the Java Message Service (JMS) API. It contains the following sections:

JMS Resources

The Java Message Service (JMS) API uses two kinds of administered objects:

• Connection factories, objects that allow an application to create other JMS objects programmatically

• Destinations, which serve as the repositories for messages

These objects are created administratively, and how they are created is specific to each implementation of JMS. In the Application Server, perform the following tasks:

• Create a connection factory by creating a connection factory resource

• Create a destination by creating two objects:

  • A physical destination

  • A destination resource that refers to the physical destination

JMS applications use the JNDI API to access the connection factory and destination resources. A JMS application normally uses at least one connection factory and at least one destination. To learn what resources to create, study the application or consult with the application developer.

There are three types of connection factories:

• QueueConnectionFactory objects, used for point-to-point communication

• TopicConnectionFactory objects, used for publish-subscribe communication

• ConnectionFactory objects, which can be used for both point-to-point and publish-subscribe communications; these are recommended for new applications

There are two kinds of destinations:

• Queue objects, used for point-to-point communication

• Topic objects, used for publish-subscribe communication

The chapters on JMS in the Java EE 5 Tutorial provide details on these two types of communication and other aspects of JMS (see http://java.sun.com/javaee/5/docs/tutorial/doc/index.html).

The order in which the resources are created does not matter.

For a Java EE application, specify connection factory and destination resources in the Application Server deployment descriptors as follows:

• Specify a connection factory JNDI name in a resource-ref or an mdb-connection-factory element.

• Specify a destination resource JNDI name in the ejb element for a message-driven bean and in the message-destination element.

• Specify a physical destination name in a message-destination-link element, within either a message-driven element of an enterprise bean deployment descriptor or a message-destination-ref element. In addition, specify it in the message-destination element. (The message-destination-ref element replaces the resource-env-ref element, which is deprecated in new applications.) In the message-destination element of an Application Server deployment descriptor, link the physical destination name with the destination resource name.

The Relationship Between JMS Resources and Connector Resources

The Application Server implements JMS by using a system resource adapter named jmsra. When a user creates JMS resources, the Application Server automatically creates connector resources that appear under the Connectors node in the Admin Console’s tree view.

For each JMS connection factory that a user creates, the Application Server creates a connector connection pool and connector resource. For each JMS destination a user creates, the Application Server creates an admin object resource. When the user deletes the JMS resources, the Application Server automatically deletes the connector resources.

It is possible to create connector resources for the JMS system resource adapter by using the Connectors node of the Admin Console instead of the JMS Resources node. See Chapter 7, Connector Resources for details.

JMS Connection Factories

JMS connection factories are objects that allow an application to create other JMS objects programmatically. These administered objects implement the ConnectionFactory, QueueConnectionFactory, and TopicConnectionFactory interfaces. Using the Application Server Admin Console, you can create, edit, or delete a JMS Connection Factory. The creation of a new JMS connection factory also creates a connector connection pool for the factory and a connector resource.

To manage JMS connection factories using the command-line utility, use create-jms-resource, list-jms-resources, or delete-jms-resource command.

JMS Destination Resources

JMS destinations serve as the repositories for messages. Using the Admin Console, you can create, modify or delete JMS Destination Resources. To create a new JMS Destination Resource, select Resources >JMS Resources >Destination Resources. In the Destination Resources page, you can specify the following:

• JNDI Name for the resource. It is a recommended practice to use the naming subcontext prefix jms/ for JMS resources. For example: jms/Queue.

• The resource type, which can be javax.jms. Topic or javax.jms.Queue.

• Additional properties for the destination resource. For more details about all these settings and the additional properties, refer to the Admin Console Online Help.

To manage JMS destinations using the command-line utility, use create-jms-resource, or delete-jms-resource command.

---

Tip –

To specify the addresslist property (in the format host:mqport,host2:mqport,host3:mqport) for asadmin create-jms-resource command, escape the : by using \\. For example, host1\\:mqport,host2\\:mqport,host3\\:mpqport.

For more information on using escape characters, see the asadmin(8) man page.

---

JMS Physical Destinations

For production purposes, always create physical destinations. During the development and testing phase, however, this step is not required. The first time that an application accesses a destination resource, Message Queue automatically creates the physical destination specified by the Name property of the destination resource. The physical destination is temporary and expires after a period specified by a Message Queue configuration property.

To create a physical destination from the Admin Console, select Configuration >Physical Destinations. In the Create Physical Destinations page, specify a name for the physical destination and choose the type of destination, which can be topic or queue. For more details about the fields and properties in the Physical Destinations page, refer the Admin Console Online Help.

For production purposes, always create physical destinations. During the development and testing phase, however, this step is not required. The first time an application accesses a destination resource, Message Queue automatically creates the physical destination specified by the Name property of the destination resource. The physical destination is temporary and expires after a period specified by a Message Queue configuration property.

To manage JMS physical destinations using the command-line utility, use create-jmsdest, flush-jmsdest, or delete-jmsdest command.

Configuring JMS Provider Properties

Use the JMS Service page in the Admin Console to configure properties to be used by all JMS connections. In the Admin Console, select Configurations >Java Message Service. In the JMS Service page, you can control the following general JMS settings.

• Select Startup Timeout interval, which indicates the time that Application Server waits for the JMS service to start before aborting the startup.

• Select JMS Service type, which decides whether you manage a JMS Service on a local or a remote host.

• Specify Start Arguments to customize the JMS service startup.

• Select Reconnect checkbox to specify whether the JMS service attempts to reconnect to a message server (or the list of addresses in the AddressList) when a connection is lost.

• Specify Reconnect Interval in terms of number of seconds. This applies for attempts on each address in the AddressList and for successive addresses in the list. If it is too short, this time interval does not give a broker time to recover. If it is too long, the reconnect might represent an unacceptable delay.

• Specify the number of reconnect attempts. In the field, type the number of attempts to connect (or reconnect) for each address in the AddressList before the client runtime tries the next address in the list.

• Choose the default JMS host.

• In the Address List Behavior drop-down list, choose whether connection attempts are in the order of addresses in the AddressList (priority) or in a random order (random).

• In the Address List Iterations field, type the number of times the JMS service iterates through the AddressList in an effort to establish (or reestablish) a connection.

• In the MQ Scheme and MQ Service fields, type the Message Queue address scheme name and the Message Queue connection service name if a non-default scheme or service is to be used.

Values of all these properties can be updated at run time too. However, only those connection factories that are created after the properties are updated, will get the updated values. The existing connection factories will continue to have the original property values. Also, for almost all of the values to take effect, the application server needs to be restarted. The only property that can be updated without having to restart the application server is the default JMS host.

To manage JMS providers using the command-line utility, use the set or jms-ping commands.

Accessing Remote Servers

Changing the provider and host to a remote system causes all JMS applications to run on the remote server. To use both the local server and one or more remote servers, create a connection factory resource with the AddressList property to create connections that access remote servers.

Foreign JMS Providers

Generic Resource Adapter 1.5 for JMS is a Java EE Connector 1.5 resource adapter that can wrap the JMS client library of external JMS providers such as IBM Websphere MQ, Tibco EMS, and Sonic MQ among others, and thus integrate any JMS provider with a Java EE 5 application server such as Sun Java System Application Server. The adapter is a.rar archive that can be deployed and configured using a Java EE 5 application server's administration tools.

Configuring the Generic Resource Adapter for JMS

Application Server's administration tools can be used to deploy and configure the generic resource adapter for JMS. This section explains how to configure Generic Resource Adapter for JMS with Sun Java System Application Server.

Overall, the Resource Adapter can be configured to indicate whether the JMS provider supports XA or not. It is also possible to indicate what mode of integration is possible with the JMS provider. Two modes of integration are supported by the resource adapter. The first one uses JNDI as the means of integration. In this case, administered objects are set up in the JMS provider's JNDI tree and will be looked up for use by the generic resource adapter. If that mode is not suitable for integration, it is also possible to use the Java reflection of JMS administered object javabean classes as the mode of integration.

You can use the Admin Console or the command-line to configure the resource adapter. This is not different from configuring any other resource adapter.

Configuring the Generic Resource Adapter

Prior to deploying the resource adapter, JMS client libraries should be made available to the application server. For some JMS providers, client libraries may also include native libraries. In such cases, these native libraries should also be made available to the application server JVM(s).

1. Deploy the generic resource adapter the same way you would deploy a connector module.

2. Create a connector connection pool.

3. Create a connector resource.

4. Create an administered object resource.

5. Make the following changes to the security policy in the Application Server:

   • Modify sjsas_home/domains/domain1/config/server.policy to add java.util.logging.LoggingPermission "control"

   • Modify sjsas_home/lib/appclient/client.policy to add permission javax.security.auth.PrivateCredentialPermission "javax.resource.spi.security.PasswordCredential ^ \"^\"","read":

Resource Adapter Properties

The following table presents the properties to be used while creating the resource adapter.

Property Name	Valid Values	Default Value	Description
ProviderIntegrationMode	javabean/jndi	javabean	Decides the mode of integration between the resource adapter and the JMS client.
ConnectionFactoryClassName	Name of the class available in the application server classpath, for example: com.sun.messaging.ConnectionFactory	None	Class name of javax.jms.ConnectionFactory implementation of the JMS client. Used if ProviderIntegrationMode is javabean.
QueueConnectionFactoryClassName	Name of the class available in the application server classpath, for example: com.sun.messaging.QueueConnectionFactory	None	Class name of javax.jms.QueueConnectionFactory implementation of the JMS client. Used if ProviderIntegrationMode is javabean.
TopicConnectionFactoryClassName	Name of the class available in the application server classpath , for example: com.sun.messaging.TopicConnectionFactory	None	Class name of javax.jms.TopicConnectionFactory implementation of the JMS client. Used if ProviderIntegrationMode is specified as javabean.
XAConnectionFactoryClassName	Name of the class available in application server classpath , for example: com.sun.messaging.XAConnectionFactory	None	Class name of javax.jms.ConnectionFactory implementation of the JMS client. Used if ProviderIntegrationMode is specified as javabean.
XAQueueConnectionFactoryClassName	Name of the class available in application server classpath , for example: com.sun.messaging.XAQueueConnectionFactory	None	Class name of javax.jms.XAQueueConnectionFactory implementation of the JMS client. Used if ProviderIntegrationMode is specified as javabean.
XATopicConnectionFactoryClassName	Name of the class available in application server classpath , for example: com.sun.messaging.XATopicConnectionFactory	None	Class name of javax.jms.XATopicConnectionFactory implementation of the JMS client. Used if ProviderIntegrationMode is javabean.
TopicClassName	Name of the class available in application server classpath , for example: com.sun.messaging.Topic	None	Class Name of javax.jms.Topic implementation of the JMS client. Used if ProviderIntegrationMode is javabean.
QueueClassName	Name of the class available in application server classpath , for example: com.sun.messaging.Queue	None	Class Name of javax.jms.Queue implementation of the JMS client. Used if ProviderIntegrationMode is specified as a javabean.
SupportsXA	True/false	FALSE	Specifies whether the JMS client supports XA or not.
ConnectionFactoryProperties	Name value pairs separated by comma	None	Specifies the javabean property names and values of the ConnectionFactory of the JMS client. Required only if ProviderIntegrationMode is javabean.
JndiProperties	Name value pairs separated by comma	None	Specifies the JNDI provider properties to be used for connecting to the JMS provider's JNDI. Used only if ProviderIntegrationMode is jndi.
CommonSetterMethodName	Method name	None	Specifies the common setter method name that some JMS vendors use to set the properties on their administered objects. Used only if ProviderIntegrationMode is javabean. In the case of Sun Java System Message Queue, this property is named setProperty.
UserName	Name of the JMS user	None	User name to connect to the JMS Provider.
Password	Password for the JMS user	None	Password to connect to the JMS provider.
RMPolicy	ProviderManaged or OnePerPhysicalConnection	ProviderManaged	The isSameRM method on an XAResource is used by the Transaction Manager to determine if the Resource Manager instance represented by two XAResources are the same. When RMPolicy is set to ProviderManaged (the default value), the JMS provider is responsible for determining the RMPolicy and the XAResource wrappers in the Generic Resource Adapter merely delegate the isSameRM call to the message queue provider's XA resource implementations. This should ideally work for most message queue products. Some XAResource implementations such as IBM MQ Series rely on a resource manager per physical connection and this causes issues when there is inbound and outbound communication to the same queue manager in a single transaction (for example, when an MDB sends a response to a destination). When RMPolicy is set to OnePerPhysicalConnection, the XAResource wrapper implementation's isSameRM in Generic Resource Adapter would check if both the XAResources use the same physical connection, before delegating to the wrapped objects.

ManagedConnectionFactory Properties

ManagedConnectionFactory properties are specified when a connector-connection-pool is created. All the properties specified while creating the resource adapter can be overridden in a ManagedConnectionFactory. Additional properties available only in ManagedConnectionFactory are given below.

Property Name	Valid Value	Default Value	Description
ClientId	A valid client ID	None	ClientID as specified by JMS 1.1 specification.
ConnectionFactoryJndiName	JNDI Name	None	JNDI name of the connection factory bound in the JNDI tree of the JMS provider. The administrator should provide all connection factory properties (except clientID) in the JMS provider itself. This property name will be used only if ProviderIntegratinMode is jndi.
ConnectionValidationEnabled	true/false	FALSE	If set to true, the resource adapter will use an exception listener to catch any connection exception and will send a CONNECTION_ERROR_OCCURED event to application server.

Administered Object Resource Properties

Properties in this section are specified when an administered object resource is created. All the resource adapter properties can be overridden in an administered resource object. Additional properties available only in the administered object resource are given below.

Property Name	Valid Value	Default Value	Description
DestinationJndiName	JNDI Name	None	JNDI name of the destination bound in the JNDI tree of the JMS provider. The Administrator should provide all properties in the JMS provider itself. This property name will be used only if ProviderIntegrationMode is jndi.
DestinationProperties	Name value pairs separated by comma	None	Specifies the javabean property names and values of the destination of the JMS client. Required only if ProviderIntegrationMode is javabean.

Activation Spec Properties

Properties in this section are specified in the Sun-specific deployment descriptor of MDB as activation-config-properties. All the resource adapter properties can be overridden in an Activation Spec. Additional properties available only in ActivationSpec are given below.

Property Name	Valid Value	Default Value	Description
MaxPoolSize	An integer	8	Maximum size of server session pool internally created by the resource adapter for achieving concurrent message delivery. This should be equal to the maximum pool size of MDB objects.
MaxWaitTime	An integer	3	The resource adapter will wait for the time in seconds specified by this property to obtain a server session from its internal pool. If this limit is exceeded, message delivery will fail.
SubscriptionDurability	Durable or Non-Durable	Non-Durable	SubscriptionDurability as specified by JMS 1.1 specification.
SubscriptionName	deferrinf	None	SubscriptionName as specified by JMS 1.1 specification.
MessageSelector	A valid message selector	None	MessageSelector as specified by JMS 1.1 specification.
ClientID	A valid client ID	None	ClientID as specified by JMS 1.1 specification.
ConnectionFactoryJndiName	A valid JNDI Name	None	JNDI name of connection factory created in JMS provider. This connection factory will be used by resource adapter to create a connection to receive messages. Used only if ProviderIntegrationMode is configured as jndi.
DestinationJndiName	A valid JNDI Name	None	JNDI name of destination created in JMS provider. This destination will be used by resource adapter to create a connection to receive messages from. Used only if ProviderIntegrationMode is configured as jndi.
DestinationType	javax.jms.Queue or javax.jms.Topic	Null	Type of the destination the MDB will listen to.
DestinationProperties	Name-value pairs separated by comma	None	Specifies the javabean property names and values of the destination of the JMS client. Required only if ProviderIntegrationMode is javabean.
RedeliveryAttempts	integer	3	Number of times a message will be delivered if a message causes a runtime exception in the MDB.
RedeliveryInterval	time in seconds	1	Interval between repeated deliveries, if a message causes a runtime exception in the MDB.
SendBadMessagesToDMD	true/false	False	Indicates whether the resource adapter should send the messages to a dead message destination, if the number of delivery attempts is exceeded.
DeadMessageDestinationJndiName	a valid JNDI name.	None	JNDI name of the destination created in the JMS provider. This is the target destination for dead messages. This is used only if ProviderIntegrationMode is jndi.
DeadMessageDestinationClassName	class name of destination object.	None	Used if ProviderIntegrationMode is javabean.
DeadMessageDestinationProperties	Name Value Pairs separated by comma	None	Specifies the javabean property names and values of the destination of the JMS client. This is required only if ProviderIntegrationMode is javabean.
ReconnectAttempts	integer	1000	Number of times a reconnect will be attempted in case exception listener catches an error on connection.
ReconnectInterval	time in seconds	1	Interval between reconnects.