![]() | |
Sun Java System Application Server Enterprise Edition 8 2004Q4 Beta Administration Guide |
Chapter 9
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 3 2004Q4 Administration Guide.
JMS Resources
The Java Message Service (JMS) API uses two kinds of administered objects:
These objects must be created administratively, and how they are created is specific to each implementation of JMS. In the Application Server, perform the following tasks:
A JMS application normally uses at least one connection factory and at least one destination. It is best to understand the application or consult with the application developer to learn what resources to create.
There are two categories of administered objects:
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 you create JMS resources, the Application Server automatically creates connector resources that appear when you expand the Connectors node in the Admin Console's tree view.For each JMS connection factory that you create, the Application Server creates a connector connection pool and connector resource. For each JMS destination you create, the Application Server creates an admin object resource. When you delete 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 12, "Connector Resources," for details. It is still necessary to use the JMS Resources node to create physical destinations.
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/QueueConnectionFactory
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.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 your application. 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, it is possible to 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 where you plan to deploy applications that use the resource. 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 required by your application. 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, it is possible to perform these tasks:
- Click Save to save your 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 where you plan to deploy applications that use the resource. 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 Resources node, then expand the JMS Resources node.
- 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
.- Click OK.
The Physical Destinations page shows the system destination, a queue named
mq.sys.dmq
, to which expired and undeliverable messages are redirected. It is possible to create destination resources, consumers, and browsers for this destination. It is not possible to delete it or to 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.- Choose
REMOTE
(the default for thedefault-config
configuration) to access the JMS service on another system. When choosing this value, follow the instructions in "Editing a JMS Host" to specify the name of the remote host. Selecting this value also means that the next time the server starts, the JMS service does not start on the local system.- Choose
NONE
to disable the JMS service the next time the server starts. This value is deprecated at this release.- 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 Behaviour 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 you need to use a nondefault scheme or service. 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.
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.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 a 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 you have used the install_dir
/imq/bin/imqusermgr
command to change the MQ broker values. 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
Deleting the default JMS host is not recommended.
To delete a JMS host, follow these steps:
Equivalent
asadmin
command:delete-jms-host