Sun Java™ System Application Server Platform Edition 8 Administration Guide |
Chapter 4
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 Sun Java System Application Server Platform Edition 8
The Sun Java System Application Server Platform Edition 8 implements the Java Message Service (JMS) API by integrating the Sun Java System Message Queue (formerly Sun ONE Message Queue) into the Application Server. You do not need to know anything about the Message Queue product in order to use the JMS API with the Application Server. However, if you are familiar with Message Queue, you can use the tools provided in the install_dir
/imq/bin
directory.For details about administering Message Queue, see the Sun ONE Message Queue 3.5 Administrator’s Guide at
http://docs.sun.com/db/doc/817-3727/
.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 Sun Java System Application Server Platform Edition 8, you perform the following tasks:
A JMS application normally uses at least one connection factory and at least one destination. You need 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 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 you create the resources does not matter.
For a J2EE application, you normally specify connection factory and destination resources in the Application Server deployment descriptors. You specify a connection factory JNDI name in a
resource-ref
or anmdb-connection-factory
element. You specify a destination resource JNDI name in theejb
element for a message-driven bean and in themessage-destination
element.You normally 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. You also specify it in themessage-destination
element. (Themessage-destination-ref
element replaces theresource-ref
element, which should not be used in new applications.) In themessage-destination
element of an Application Server deployment descriptor, you link the physical destination name with the destination resource name.The Relationship Between JMS Resources and Connector Resources
The Sun Java System Application Server Platform Edition 8 implements JMS by using a system resource adapter named
jmsra
. When you create JMS resources, the Application Server also automatically creates connector resources that you can see when you expand the Connectors node in the Admin Console’s tree view.For each JMS connection factory you create, the Application Server creates a corresponding 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 corresponding connector resources are also deleted automatically.
You can also create connector resources for the JMS system resource adapter by using the Connectors node of the Admin Console instead of the Java Message Service node. See Chapter 7, "Connector Resources", for details. You must still use the Java Message Service node to create physical destinations.
Admin Console Tasks for JMS Connection FactoriesCreating a JMS Connection Factory Resource
- In the tree component, expand the Java Message Service 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 combo box, choose either
javax.jms.QueueConnectionFactory
orjavax.jms.TopicConnectionFactory
.- Select the Enabled checkbox to enable the resource at run time.
- In the Additional Properties area, click Add Property to add a property required by your application. Table 4-1 lists the properties you are most likely to set. Others are listed in the Message Queue documentation.
- Click OK to save the connection factory.
Equivalent
asadmin
command:create-jms-resource
Editing a JMS Connection Factory Resource
Deleting a JMS Connection Factory Resource
Equivalent
asadmin
command:delete-jms-resource
Admin Console Tasks for JMS Physical DestinationsCreating a JMS Physical Destination
- In the tree component, expand the Java Message Service 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 combo box, choose either
topic
orqueue
.- Click OK.
Equivalent
asadmin
command:create-jmsdest
Deleting a JMS Physical Destination
Equivalent
asadmin
command:delete-jmsdest
Admin Console Tasks for JMS Destination ResourcesCreating a JMS Destination Resource
- In the tree component, expand the Java Message Service 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 combo box, choose either
javax.jms.Topic
orjavax.jms.Queue
.- Select the Enabled checkbox to enable the resource at run time.
- Under Additional Properties, click Add.
- In the Name field, type
Name
.- In the Value field, type the name of the physical destination to which the resource will refer.
- Click OK.
Equivalent
asadmin
command:create-jms-resource
Editing a JMS Destination Resource
Deleting a JMS Destination Resource
Equivalent
asadmin
command:delete-jms-resource
Admin Console Tasks for the JMS ProviderConfiguring General Properties for the JMS Provider
- In the tree component, select the Java Message Service node to open the JMS Service page.
- Edit the value in the Initial Timeout field if you want to change the time the application server waits for the JMS service to start before aborting the startup. On a slow or overloaded system, you may need to increase the value from the default (60).
- From the Type combo box:
- Choose LOCAL (the default) to access the JMS service on the local host.
- Choose NONE to disable the JMS service the next time the server starts.
- Choose REMOTE to access the JMS service on another system. If you choose this value, follow the instructions in Configuring the JMS Host to specify the name of the remote host. Selecting this value also means that the JMS service will not start on the local system the next time the server starts.
- In the Start Arguments field, type arguments to customize the JMS service startup. You can use any arguments that you can specify to the install_dir
/imq/bin/imqbrokerd
command.- In the Additional Properties area, click Add Property to add a property. You may specify Message Queue broker configuration properties here.
- When you have finished, click Save to save your 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. If you want to be able to use both the local server and a remote server, create a connection factory resource with the
MessageServiceAddressList
property to create connections that access the remote server.After you change properties of the JMS provider, you must stop and restart the server in order for the changes to take effect.
Configuring the JMS Host
- In the tree component, expand the Java Message Service node.
- Select the JMS Hosts node.
- On the JMS Hosts page, select
default_JMS_host
to display the Edit JMS Host page.- In the Host field, type the name or Internet Protocol (IP) address of the host. If you changed the type of the JMS Service to REMOTE, type the name of the remote host.
- In the Port field, type the port number of the JMS service. Change this field only if the JMS service you will use 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.- When you have finished, click Save to save your changes, or click Load Defaults to restore the default values for the host.
At this release, the Application Server expects there to be exactly one JMS host, named
default_JMS_host
. You could use the JMS Hosts page to create new hosts, but the Application Server would have no way of knowing about them. Deleting the default JMS host is not recommended.After you change properties of the JMS host, you must stop and restart the server in order for the changes to take effect.