Sun logo      Previous      Contents      Next     

Sun Java System Application Server Platform Edition 8.1 2005Q1 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) into the Application Server. For basic JMS API administration tasks, use the Application Server Admin Console. For advanced tasks, 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:

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 7, "Connector Resources," for details.

Admin Console Tasks for JMS Connection Factories

Creating a JMS Connection Factory Resource

To create a JMS connection factory resource, follow these steps:

  1. In the tree component, expand the Resources node, then expand the JMS Resources 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/ConnectionFactory1

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

  5. From the Type drop-down list, choose either javax.jms.ConnectionFactory, javax.jms.QueueConnectionFactory, or javax.jms.TopicConnectionFactory.
  6. Select the Enabled checkbox to enable the resource at run time.
  7. 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.

    8. 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 as XATransaction 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 as LocalTransaction 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.
  8. In the Additional Properties area, provide values for properties required by applications. The following table lists the available properties.

    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.

    AddressList

    Specifies the name (and, optionally, port number) of a message broker instance with which applications will communicate. Each address in the list specifies the host name (and, optionally, host port and connection service) for the connection. For example, the value might be earth or earth:7677. Specify the port number if the message broker is running on a port other than the default (7676).

    For details, see the Sun Java System Message Queue Developer’s Guide for Java Clients.

    Default: The local host and default port number (7676). The client will attempt a connection to a broker on port 7676 of the local host.

    MessageServiceAddressList

    Same as AddressList. This property name is deprecated. Use AddressList instead.

    UserName

    The user name for the connection factory.

    Default: guest

    Password

    The password for the connection factory.

    Default: guest

    ReconnectEnabled

    If enabled (value = true), specifies that the client runtime attempts to reconnect to a message server (or the list of addresses in the AddressList) when a connection is lost.

    Default: true

    ReconnectAttempts

    Specifies 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).

    Default: 3

    ReconnectInterval

    Specifies the interval in milliseconds between reconnect attempts. This applies for attempts on each address in the AddressList and for successive addresses in the list. If the interval is too short, the broker does not have time to recover. If it is too long, the reconnect might represent an unacceptable delay.

    Default: 30000

    AddressListBehavior

    Specifies whether connection attempts are in the order of addresses in the AddressList attribute (PRIORITY) or in a random order (RANDOM).

    RANDOM means that the reconnect chooses a random address from the AddressList. If many clients are likely to attempt a connection using the same connection factory, this value prevents them from all being connected to the same address.

    PRIORITY means that the reconnect always tries to connect to the first server address in the AddressList and uses another address only if the first broker is not available.

    Default: RANDOM

    AddressListIterations

    Specifies the number of times the client runtime 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.

    Default: 3

  9. 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:

  1. In the tree component, expand the Resources node, then expand the JMS Resources 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.
    • Change the values of the attributes in the Advanced area.
    • Add, remove, or modify properties.
  5. Click Save to save the changes.

Deleting a JMS Connection Factory Resource

To delete a JMS connection factory resource, follow these steps:

  1. In the tree component, expand the Resources node, then expand the JMS Resources 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 Destination Resources

Creating a JMS Destination Resource

To create a JMS destination resource, follow these steps:

  1. In the tree component, expand the Resources node, then expand the JMS Resources 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 drop-down list, choose either javax.jms.Topic or javax.jms.Queue.
  6. Select the Enabled checkbox to enable the resource at run time.
  7. In the Additional Properties area, provide values for properties. The following table lists the available properties.

    Table 4-2  Additional Properties for JMS Destination Resources

    Property Name

    Description

    Name

    (Required) The name of the physical destination to which the resource refers.

    Description

    A description of the physical destination.

  8. Click OK.

Equivalent asadmin command: create-jms-resource

Editing a JMS Destination Resource

To edit a JMS destination resource, follow these steps:

  1. In the tree component, expand the Resources node, then expand the JMS Resources node.
  2. Expand the Destination Resources node.
  3. Select the destination resource to be edited.
  4. On the Edit JMS Destination Resource page, you can perform these 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 or Description property.
  5. Click Save to save the changes.

Deleting a JMS Destination Resource

To delete a JMS destination resource, follow these steps:

  1. In the tree component, expand the Resources node, then expand the JMS Resources 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 JMS Physical Destinations

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

  1. In the tree component, expand the Configuration node, then 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 drop-down list, choose either topic or queue.
  6. In the Additional Properties area, click Add Property to add a property. The following table lists the one property currently available.

    Table 4-3  Additional Property for JMS Physical Destinations

    Property Name

    Description

    maxNumActiveConsumers

    The maximum number of consumers that can be active in load-balanced delivery from a queue destination. A value of -1 means an unlimited number. The default is 1. (Platform Edition limits this value to 2.)

    7. 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.

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

  1. In the tree component, expand the Configuration node, then 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.

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 Provider

Configuring General Properties for the JMS Provider

Use the JMS Service page to configure properties to be used by all JMS connections. Follow these steps:

  1. In the tree component, select the Configuration node.
  2. Select the Java Message Service node to open the JMS Service page.
  3. 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).
  4. From the Type drop-down list:
    • Choose LOCAL (the default) to access the JMS service on the local host. The JMS service is started and managed by the Application Server.
    • Choose REMOTE to access the JMS service on another system. If you choose REMOTE, 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.
  5. 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.
  6. 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.

    7. By default, reconnection is enabled.

  7. 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.

    8. The default value is 60 seconds.

  8. 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).

    9. The default value is 3.

  9. Choose a host from the Default JMS Host drop-down list. The default is default_JMS_host.
  10. 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).

    11. 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.

  11. 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.

    12. The default value is 3.

  12. 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
    13. 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.

    Table 4-4  Message Server Address Schemes and Syntax 

    Scheme Name

    Connection Service

    Description

    Address Syntax

    mq

    jms and ssljms

    MQ client runtime makes a connection to the MQ Port Mapper at the specified host and port. The Port Mapper returns a list of the dynamically established connection service ports, and the MQ client runtime then makes a connection to the port hosting the specified connection service.

    [hostName][:port][/serviceName]

    Defaults:
    hostName = localhost
     port = 7676
     serviceName = jms

    Defaults only apply to the jms connection service. For the ssljms connection service, all variables need to be specified

    Example:
    mq:MyHost:7677/ssljms

    mqtcp

    jms

    MQ client runtime makes a TCP connection to the specified host and port (bypassing the MQ Port Mapper) to establish a connection.

    hostName:port/jms

    Example:
    mqtcp:localhost:7676/jms

    mqssl

    ssljms

    MQ client runtime makes a secure SSL connection to the specified host and port (bypassing the MQ Port Mapper) to establish a connection.

    hostName:port/ssljms

    Example:
    mqssl:localhost:7676/ssljms

    http

    httpjms

    MQ client runtime makes an HTTP connection to an MQ tunnel servlet at the specified URL. (The broker must be configured to access the HTTP tunnel servlet, as described in the MQ Administrator’s Guide.)

    hostName:port/
    contextRoot/tunnel

    If multiple broker instances are using the same tunnel servlet, then the syntax for connecting to a specific broker instance (rather than a randomly selected one) is: http://hostName:port/
    contextRoot/tunnel?serverName=hostName:instanceName

    https

    httpsjms

    MQ client runtime makes a secure HTTPS connection to the specified MQ tunnel servlet URL. (The broker must be configured to access the HTTPS tunnel servlet, as described in the MQ Administrator’s Guide.)

    hostName:port/
    contextRoot/tunnel

    If multiple broker instances are using the same tunnel servlet, then the syntax for connecting to a specific broker instance (rather than a randomly selected one) is: http://hostName:port/
    contextRoot/tunnel?serverName=hostName:instanceName

  13. In the Additional Properties area, click Add Property to add a property. The following table lists the available Message Queue broker configuration properties.

    Table 4-5  Additional Properties for JMS Providers 

    Property Name

    Description

    instance-name

    Specifies the full Sun Java System Message Queue broker instance name. The default is imqbroker.

    instance-name-suffix

    Specifies a suffix to add to the full Sun Java System Message Queue broker instance name. The suffix is separated from the instance name by an underscore character (_). For example, if the instance name is imqbroker, appending the suffix xyz changes the instance name to imqbroker_xyz.

    append-version

    If true, appends the major and minor version numbers, preceded by underscore characters (_), to the full Sun Java System Message Queue broker instance name. For example, if the instance name is imqbroker, appending the version numbers changes the instance name to imqbroker_8_0. The default is false.

  14. Click Save to save the changes, or click Load Defaults to restore the default values for the service.

    15. 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

The Application Server expects there to be exactly one JMS host, whose default name is default_JMS_host. It is possible to create additional hosts, but the Application Server has no way of knowing about them.

To create a JMS host, follow these steps:

  1. In the tree component, expand the Configuration node.
  2. Expand the Java Message Service node.
  3. Select the JMS Hosts node.
  4. On the JMS Hosts page, click New. The Create JMS Host page appears.
  5. In the Name field, type the name of the host. For example:
    6. NewJmsHost
  6. 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).
  7. 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.)
  8. 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 are admin and admin.
  9. Click OK.

Equivalent asadmin command: create-jms-host

Editing a JMS Host

To edit a JMS host, follow these steps:

  1. In the tree component, expand the Configuration node.
  2. Expand the Java Message Service node.
  3. Select the JMS Hosts node.
  4. On the JMS Hosts page, select the host to be edited.
  5. On the Edit JMS Host page, it is possible to perform these tasks:
    • Change the host name or Internet Protocol (IP) address in the Host field.
    • Change the port number of the JMS service in the Port field.
    • Change the values in the Admin Username and Admin Password fields.
  6. 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:

  1. In the tree component, expand the Configuration node.
  2. Expand the Java Message Service node.
  3. Select the JMS Hosts node.
  4. On the JMS Hosts page, select the checkbox next to the name of the host to be deleted.
  5. Click Delete.

Equivalent asadmin command: delete-jms-host



Previous      Contents      Next     

Copyright 2004-2005 Sun Microsystems, Inc. All rights reserved.