Sun Java System Application Server Enterprise Edition 8.2 Administration Guide

Chapter 4 Configuring Java Message Service Resources

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

About JMS Resources

The JMS Provider in the Application Server

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 Administration Console. For advanced tasks, including administering a Message Queue cluster, use the tools provided in the MQ-install-dir/imq/bin directory.

For details about administering Message Queue, see the Message Queue Administration Guide.

JMS Resources

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

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:

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:

There are two kinds of destinations:

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

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

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

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 Administration 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 Administration 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:

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.

ProcedureTo Create a JMS Physical Destination

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. Physical destinations are attached to Message Queue instances and not to Application Server instances. Any Application Server instance can talk to any Message Queue instance because there is no tight coupling between Message Queue and Application Server.

  1. In the Admin Console, select Configuration >Physical Destinations.

  2. In the Create Physical Destinations page, specify a name for the physical destination.

  3. Choose the type of destination, which can be topic or queue.

See Also

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

For more details about the fields and properties of the Physical Destinations page, see the Admin Console online help.

ProcedureTo Create a Configuration-Specific JMS Physical Destination

By default, all the instances in Application Server share the same Default JMS Host which is used by the domain administration server (DAS). In other words, all physical destinations are the same. If your environment requires configuration-specific physical destinations, you must create a separate JMS host for each instance or cluster as described in the following steps:

  1. In the Edit JMS Hosts page of the Admin Console, create a new JMS host with its own port.

  2. In the JMS Service page, create a JMS Host as follows:

    1. Set the Type to LOCAL.

    2. In the Default JMS Host field, specify the host that you created in Step 1.

    You can also set other options on this page if needed.

  3. Save the changes and restart the instance or cluster.

    Now you are ready to create configuration-specific physical destinations.

JMS Providers

Configuring General Properties for the JMS Provider

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.

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 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 1.4 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 1.4 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. First one uses JNDI as the means of integration. In this case, administered objects are set up in 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 Java reflection of JMS administered object javabean classes as the mode of integration. You can use the Sun Java System Application Server's Administration Console or the CLI 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.

    For steps to do this, refer to the Admin Console Online Help. During deployment, make sure that you specify install-dir/lib/addons/resourceadapters/genericjmsra/genericra.rar as the location of the generic resource adapter. Also, you must specify the properties explained in the section Resource Adapter Properties.

  2. Create a connector connection pool.

    For steps to do this, refer to the Admin Console Online help. In the New Connector Connection Pool page, from the Resource Adapter combo box, select genericra. Also, in the Connection Definition combo box, select javax.jms.QueueConnectionFactory. Additionally, specify the properties explained in the section ManagedConnectionFactory Properties.

  3. Create a connector resource.

    For detailed procedure to do this, you can refer the Admin Console Online Help. In the New Connector Resource page, select the pool you created in the previous step.

  4. Create an administered object resource.

    For detailed procedure to do this, you can refer the Admin Console Online Help. In the New Admin Object Resource page, select genericra as the Resource Adapter and javax.jms.Queue as the Resource Type. Click Next and in the second page, click Add Property. In the Additional Properties table, specify a new property called DestinationProperties with the value Name\\=clientQueue. For information on more properties, see the section Administered Object Resource Properties.

  5. Make the following changes to the security policy in Sun Java System 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. This is 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. This is 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. This is 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. This is 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. This is 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. This is 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. This is 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 

This specifies the javabean property names and values of the ConnectionFactory of the JMS client. This is required only if ProviderIntegrationMode is javabean.

JndiProperties

Name value pairs separated by comma. 

none 

This specifies the JNDI provider properties to be used for connecting to the JMS provider's JNDI. This is used only if ProviderIntegrationMode is jndi.

CommonSetterMethodName

Method name 

none 

This specifies the common setter method name that some JMS vendors use to set the properties on their administered objects. This property is 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. 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. 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 

This 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 

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 

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

 

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 

This specifies the javabean property names and values of the destination of the JMS client. Required only if ProviderIntegrationMode is javabean.

RedeliveryAttempts

integer 

 

Number of times a message will be delivered if a message causes a runtime exception in the MDB. 

RedeliveryInterval

time in seconds 

 

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 

This specifies the javabean property names and values of the destination of the JMS client. This is required only if ProviderIntegrationMode is javabean.

ReconnectAttempts

integer 

 

Number of times a reconnect will be attempted in case exception listener catches an error on connection. 

ReconnectInterval

time in seconds 

 

interval between reconnects.