Sun logo      Previous      Contents      Next     

Sun Java™ System Application Server Platform Edition 8 Administration Guide

Chapter 4
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 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 an mdb-connection-factory element. You specify a destination resource JNDI name in the ejb element for a message-driven bean and in the message-destination element.

You normally 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. You also specify it in the message-destination element. (The message-destination-ref element replaces the resource-ref element, which should not be used in new applications.) In the message-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 Factories

Creating a JMS Connection Factory Resource

  1. In the tree component, expand the Java Message Service node.
  2. Select the Connection Factories node.
  3. On the JMS Connection Factories page, click New. The Create JMS Connection Factory page appears.
  4. In the JNDI Name field, type the name of the connection factory. For example:
    5. jms/QueueConnectionFactory

    It is a recommended practice to use the naming subcontext prefix jms/ for JMS resources.

  5. From the Type combo box, choose either javax.jms.QueueConnectionFactory or javax.jms.TopicConnectionFactory.
  6. Select the Enabled checkbox to enable the resource at run time.
  7. 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.
  8. Click OK to save the connection factory.

Equivalent asadmin command: create-jms-resource

Table 4-1  Additional Properties for JMS Connection Factories

Property Name

Description

ClientId

Specifies a client ID for a connection factory that will be used by a durable subscriber.

MessageServiceAddressList

Specifies the name (and, optionally, port number) of a remote system with which your application will communicate. For example, the value could be earth or earth:7677. Specify the port number if the JMS service on the remote system is running on a port other than the default (7676).

Editing a JMS Connection Factory Resource

  1. In the tree component, expand the Java Message Service node.
  2. Expand the Connection Factories node.
  3. Select the connection factory to be edited.
  4. On the Edit JMS Connection Factory page, you can perform these tasks:
    • Modify the text in the Description field.
    • Select or deselect the Enabled checkbox to enable or disable the resource.
    • Add, remove, or modify properties.
  5. Click Save to save your changes.

Deleting a JMS Connection Factory Resource

  1. In the tree component, expand the Java Message Service node.
  2. Select the Connection Factories node.
  3. On the JMS Connection Factories page, select the checkbox next to the name of the connection factory to be deleted.
  4. Click Delete.

Equivalent asadmin command: delete-jms-resource

Admin Console Tasks for JMS Physical Destinations

Creating a JMS Physical Destination

  1. In the tree component, expand the Java Message Service node.
  2. Select the Physical Destinations node.
  3. On the Physical Destinations page, click New. The Create Physical Destination page appears.
  4. In the Physical Destination Name field, type the name of the destination (for example, PhysicalQueue).
  5. From the Type combo box, choose either topic or queue.
  6. Click OK.

Equivalent asadmin command: create-jmsdest

Deleting a JMS Physical Destination

  1. In the tree component, expand the Java Message Service node.
  2. Select the Physical Destinations node.
  3. On the Physical Destinations page, select the checkbox next to the name of the destination to be deleted.
  4. Click Delete.

Equivalent asadmin command: delete-jmsdest

Admin Console Tasks for JMS Destination Resources

Creating a JMS Destination Resource

  1. In the tree component, expand the Java Message Service node.
  2. Select the Destination Resources node.
  3. On the JMS Destination Resources page, click New. The Create JMS Destination Resource page appears.
  4. In the JNDI Name field, type the name of the resource. For example:
    5. jms/Queue

    It is a recommended practice to use the naming subcontext prefix jms/ for JMS resources.

  5. From the Type combo box, choose either javax.jms.Topic or javax.jms.Queue.
  6. Select the Enabled checkbox to enable the resource at run time.
  7. Under Additional Properties, click Add.
  8. In the Name field, type Name.
  9. In the Value field, type the name of the physical destination to which the resource will refer.
  10. Click OK.

Equivalent asadmin command: create-jms-resource

Editing a JMS Destination Resource

  1. In the tree component, expand the Java Message Service node.
  2. Expand the Destination Resources node.
  3. Select the destination resource to be edited.
  4. On the Edit JMS Destination Resource page, you may perform the following tasks:
    • Change the type of the resource.
    • Modify the text in the Description field.
    • Select or deselect the Enabled checkbox to enable or disable the resource.
    • Add, remove, or modify the Name property.
  5. Click Save to save your changes.

Deleting a JMS Destination Resource

  1. In the tree component, expand the Java Message Service node.
  2. Select the Destination Resources node.
  3. On the JMS Destination Resources page, select the checkbox next to the name of the destination resource to be deleted.
  4. Click Delete.

Equivalent asadmin command: delete-jms-resource

Admin Console Tasks for the JMS Provider

Configuring General Properties for the JMS Provider

  1. In the tree component, select the Java Message Service node to open the JMS Service page.
  2. 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).
  3. From the Type combo box:
    1. Choose LOCAL (the default) to access the JMS service on the local host.
    2. Choose NONE to disable the JMS service the next time the server starts.
    3. 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.
  4. 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.
  5. In the Additional Properties area, click Add Property to add a property. You may specify Message Queue broker configuration properties here.
  6. 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

  1. In the tree component, expand the Java Message Service node.
  2. Select the JMS Hosts node.
  3. On the JMS Hosts page, select default_JMS_host to display the Edit JMS Host page.
  4. 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.
  5. 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.)
  6. 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.
  7. 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.



Previous      Contents      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.