Sun Java System Application Server Enterprise Edition 8.1 Administration Guide 2005Q1 |
Chapter 8
Configuring Java Message Service ResourcesThis chapter describes how to configure resources for applications that use the Java Message Service (JMS) API. It contains the following sections:
About JMS ResourcesThe 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) 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 install_dir
/imq/bin
directory.For details about administering Message Queue, see the Sun Java System 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:
- Specify a connection factory JNDI name in a
resource-ref
or anmdb-connection-factory
element.- Specify a destination resource JNDI name in the
ejb
element for a message-driven bean and in themessage-destination
element.- Specify a physical destination name in a
message-destination-link
element, within either amessage-driven
element of an enterprise bean deployment descriptor or amessage-destination-ref
element. In addition, specify it in themessage-destination
element. (Themessage-destination-ref
element replaces theresource-env-ref
element, which is deprecated in new applications.) In themessage-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 11, "Connector Resources," for details.
Admin Console Tasks for JMS Connection FactoriesCreating a JMS Connection Factory Resource
To create a JMS connection factory resource, follow these steps:
- In the tree component, expand the Resources node, then expand the JMS Resources node.
- Select the Connection Factories node.
- On the JMS Connection Factories page, click New. The Create JMS Connection Factory page appears.
- In the JNDI Name field, type the name of the connection factory. For example:
jms/ConnectionFactory1
It is a recommended practice to use the naming subcontext prefix
jms/
for JMS resources.- From the Type drop-down list, choose either
javax.jms.ConnectionFactory
,javax.jms.QueueConnectionFactory
, orjavax.jms.TopicConnectionFactory
.- Select the Enabled checkbox to enable the resource at run time.
- In the Advanced area, change values as needed for the connection factory attributes. For details about these attributes, see the table entitled “Pool Settings for a Connector Connection Pool” in "Editing a Connector Connection Pool". The Application Server applies these attributes to the connector connection pool created for the connection factory.
For a JMS connection factory resource, specify the Transaction Support value as follows:
- Specify
XATransaction
(the default value) for a resource that can be used for transactions that involve the use of more than one resource within a transaction scope (for example, this resource plus a JDBC resource, a connector resource, or another JMS connection factory resource). This value offers the most flexibility. A resource that is configured asXATransaction
will participate in two-phase commit operations.- Specify
LocalTransaction
for a resource that can be used either for transactions that involve only one resource within the transaction scope or as the last agent in a distributed transaction that involves more than one XA resource. This value offers significantly better performance. A resource that is configured asLocalTransaction
will not be used in two-phase commit operations.- Specify
NoTransaction
for a resource that can never participate in transactions; this setting is of limited use in JMS applications.- In the Additional Properties area, provide values for properties required by applications. The following table lists the available properties.
- In the Targets area, do the following:
- Click OK to save the connection factory.
Equivalent
asadmin
command:create-jms-resource
Editing a JMS Connection Factory Resource
To edit a JMS connection factory resource, follow these steps:
- In the tree component, expand the Resources node, then expand the JMS Resources node.
- Expand the Connection Factories node.
- Select the connection factory to be edited.
- On the Edit JMS Connection Factory page, you can perform these tasks:
- Optionally, click the Targets tab to go to the JMS Connection Factory Resource Targets page. On this page, do the following:
- Click Manage Targets to open the Manage Resource Targets page.
On this page, move targets between the Available column and the Selected column. Make sure to place in the Selected column the target or targets to which applications that use the resource will be deployed. The available targets include the available clusters and server instances, as well as the default server instance,
server
. Click OK to save the changes.- Select the checkbox for a target, then click Enable or Disable to enable or disable the resource for that target.
- Click Save to save the changes.
Deleting a JMS Connection Factory Resource
To delete a JMS connection factory resource, follow these steps:
Equivalent
asadmin
command:delete-jms-resource
Admin Console Tasks for JMS Destination ResourcesCreating a JMS Destination Resource
To create a JMS destination resource, follow these steps:
- In the tree component, expand the Resources node, then expand the JMS Resources node.
- Select the Destination Resources node.
- On the JMS Destination Resources page, click New. The Create JMS Destination Resource page appears.
- In the JNDI Name field, type the name of the resource. For example:
jms/Queue
It is a recommended practice to use the naming subcontext prefix
jms/
for JMS resources.- From the Type drop-down list, choose either
javax.jms.Topic
orjavax.jms.Queue
.- Select the Enabled checkbox to enable the resource at run time.
- In the Additional Properties area, provide values for properties. The following table lists the available properties.
- In the Targets area, do the following:
- Click OK.
Equivalent
asadmin
command:create-jms-resource
Editing a JMS Destination Resource
To edit a JMS destination resource, follow these steps:
- In the tree component, expand the Resources node, then expand the JMS Resources node.
- Expand the Destination Resources node.
- Select the destination resource to be edited.
- On the Edit JMS Destination Resource page, you can perform these tasks:
- Click Save to save the changes.
- Optionally, click the Targets tab to go to the JMS Destination Resource Targets page. On this page, do the following:
- Click Manage Targets to open the Manage Resource Targets page.
On this page, move targets between the Available column and the Selected column. Make sure to place in the Selected column the target or targets to which applications that use the resource will be deployed. The available targets include the available clusters and server instances, as well as the default server instance,
server
. Click OK to save the changes.- Select the checkbox for a target, then click Enable or Disable to enable or disable the resource for that target.
Deleting a JMS Destination Resource
To delete a JMS destination resource, follow these steps:
Equivalent
asadmin
command:delete-jms-resource
Admin Console Tasks for JMS Physical DestinationsCreating a JMS Physical Destination
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 create a JMS physical destination, follow these steps:
- In the tree component, expand the Configurations node, then expand the Java Message Service node.
- Select the instance to configure:
- Select the Physical Destinations node.
- On the Physical Destinations page, click New. The Create Physical Destination page appears.
- In the Physical Destination Name field, type the name of the destination (for example,
PhysicalQueue
).- From the Type drop-down list, choose either
topic
orqueue
.- In the Additional Properties area, click Add Property to add a property. The following table lists the one property currently available.
To modify the value of this property or to specify other physical destination properties, use the install_dir
/imq/bin/imqcmd
command. See the Sun Java System Message Queue Administration Guide for more information.- Click OK.
The Physical Destinations page shows the system destination, a queue named
mq.sys.dmq
, to which expired and undeliverable messages are redirected. You can create destination resources, consumers, and browsers for this destination. You cannot delete it or send messages to it.Equivalent
asadmin
command:create-jmsdest
Deleting a JMS Physical Destination
To delete a JMS physical destination, follow these steps:
If you try to delete the system destination
mq.sys.dmq
, an error message appears.Equivalent
asadmin
command:delete-jmsdest
Admin Console Tasks for the JMS ProviderConfiguring General Properties for the JMS Provider
Use the JMS Service page to configure properties to be used by all JMS connections. Follow these steps:
- In the tree component, select the Configurations node.
- Select the instance to configure:
- Select the Java Message Service node to open the JMS Service page.
- Edit the value in the Startup Timeout field to change the time the Application Server waits for the JMS service to start before aborting the startup. On a slow or overloaded system, increase the value from the default (60).
- From the Type drop-down list:
- Choose
LOCAL
(the default for theserver-config
configuration) to access the JMS service on the local host. The JMS service is started and managed by the Application Server.- Choose
REMOTE
(the default for thedefault-config
configuration) to access the JMS service on another system or on a cluster. If you chooseREMOTE
, the JMS service is not started by the Application Server the next time the server starts. Instead, the JMS service is started and managed via Message Queue, so you must start the Message Queue broker separately. For information about starting the broker, see the Sun Java System Message Queue Administration Guide. If you choose this value and are using a remote host, follow the instructions in "Editing a JMS Host" to specify the name of the remote host.- In the Start Arguments field, type arguments to customize the JMS service startup. Use any arguments available through the install_dir
/imq/bin/imqbrokerd
command.- Use the 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.
By default, reconnection is enabled.
- In the Reconnect Interval field, type the number of seconds between reconnect attempts. 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.
The default value is 60 seconds.
- In the Reconnect Attempts 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. A value of -1 indicates that the number of reconnect attempts is unlimited (the client runtime attempts to connect to the first address until it succeeds).
The default value is 3.
- Choose a host from the Default JMS Host drop-down list. The default is
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
).
priority
means that the reconnect always tries to connect to the first server address in the AddressList and uses another one only if the first broker is not available.If there are many clients attempting a connection using the same connection factory, specify
random
to prevent them from all being connected to the same address.The default is
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 re-establish) a connection). A value of -1 indicates that the number of attempts is unlimited.
The default value is 3.
- In the MQ Scheme and MQ Service fields, type the Message Queue address scheme name and the MQ connection service name if a nondefault scheme or service is to be used. The full syntax for a message service address is
scheme://address_syntax
where the scheme and address_syntax are described in the table below.
The MQ Scheme and MQ Service are the values shown in the first two columns of the following table.
- In the Additional Properties area, click Add Property to add a property. The following table lists the available Message Queue broker configuration properties.
- Click Save to save the changes, or click Load Defaults to restore the default values for the service.
Click Ping to see if the JMS service is up and running. If it is, the message “Ping succeeded: JMS service is running” appears.
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.For more information about configuring the JMS service, see the Sun Java System Application Server Developer’s Guide.
Equivalent
asadmin
command:jms-ping
Creating a JMS Host
To create a JMS host, follow these steps:
- In the tree component, expand the Configurations node.
- Select the instance to configure:
- Expand the Java Message Service node.
- Select the JMS Hosts node.
- On the JMS Hosts page, click New. The Create JMS Host page appears.
- In the Name field, type the name of the host. For example:
NewJmsHost
- In the Host field, type the name or Internet Protocol (IP) address of the system where the JMS host will run (
localhost
or the name of the local or remote system).- In the Port field, type the port number of the JMS service. Change this field only if the JMS service to be used is running on a nondefault port. (The default port is 7676.)
- In the Admin Username and Admin Password fields, type the MQ broker user name and password. These are different from the Application Server user name and password. Edit these fields only if the MQ broker values have been changed using the install_dir
/imq/bin/imqusermgr
command. The default values areadmin
andadmin
.- Click OK.
Equivalent
asadmin
command:create-jms-host
Editing a JMS Host
To edit a JMS host, follow these steps:
- In the tree component, expand the Configurations node.
- Select the instance to configure:
- Expand the Java Message Service node.
- Select the JMS Hosts node.
- On the JMS Hosts page, select the host to be edited.
- On the Edit JMS Host page, it is possible to perform these tasks:
- Click Save to save the changes, or click Load Defaults to restore the default values for the host.
Deleting a JMS Host
To delete a JMS host, follow these steps:
Equivalent
asadmin
command:delete-jms-host