Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide

- Previous: Chapter 3 JDBC Resources
- Next: Chapter 5 Configuring JavaMail Resources

# 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

- Admin Console Tasks for JMS Connection Factories

- Admin Console Tasks for JMS Destination Resources

- Admin Console Tasks for JMS Physical Destinations

- Admin Console Tasks for the JMS Provider

# About JMS Resources

- The JMS Provider in the Application Server

- JMS Resources

- The Relationship Between JMS Resources and Connector 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) software 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 MQ-install-dir`/imq/bin` directory.

For details about administering Message Queue, see the Message Queue Administration Guide.

## JMS Resources

The Java Message Service (JMS) API uses two kinds of administered objects:

- Connection factories, objects that allow an application to create other JMS objects programmatically

- Destinations, which serve as the repositories for messages

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:

- Create a connection factory by creating a connection factory resource

- Create a destination by creating two objects:

  - A physical destination

  - A destination resource that refers to the physical destination

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:

- `QueueConnectionFactory` objects, used for point-to-point communication

- `TopicConnectionFactory` objects, used for publish-subscribe communication

- `ConnectionFactory` objects, which can be used for both point-to-point and publish-subscribe communications; these are recommended for new applications

There are two kinds of destinations:

- `Queue` objects, used for point-to-point communication

- `Topic` objects, used for publish-subscribe communication

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 an `mdb-connection-factory` element.

- Specify a destination resource JNDI name in the `ejb` element for a message-driven bean and in the `message-destination` element.

- 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. In addition, specify it in the `message-destination` element. (The `message-destination-ref` element replaces the `resource-env-ref` element, which is deprecated in new applications.) In the `message-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 7, Connector Resources for details.

# Admin Console Tasks for JMS Connection Factories

- To create a JMS connection factory resource

- To edit a JMS connection factory resource

- To delete a JMS connection factory resource

## To create a JMS connection factory resource

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.

   It is a recommended practice to use the naming subcontext prefix `jms/` for JMS resources. For example: `jms/ConnectionFactory1`.

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 To edit a JMS connection factory resource. 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.

9. In the Additional Properties area, provide values for properties required by applications. The following table lists the available properties.

   Property Name | Description
   --- | ---
   `ClientId` | Specifies a client ID for a connection factory that will be used by a durable subscriber.
   `AddressList` | Specifies the names (and, optionally, port numbers) of a message broker instance or instances 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). If the property setting specifies multiple hosts and ports in a clustered environment, the first available host on the list is used unless the `AddressListBehavior` property is set to `RANDOM`. For details, see the 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 reestablish) a connection). A value of -1 indicates that the number of attempts is unlimited. Default: 3

10. In the Targets area, do the following:

    1. From the Available column, select 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`.

    2. Click Add to move the target to the Selected column.

11. Click OK to save the connection factory.

##### Equivalent asadmin command

`create-jms-resource`

## To edit a JMS connection factory resource

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. Optionally, click the Targets tab to go to the JMS Connection Factory Resource Targets page. On this page, do the following:

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

   2. Select the checkbox for a target, then click Enable or Disable to enable or disable the resource for that target.

6. Click Save to save the changes.

## To delete a JMS connection factory resource

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

- To create a JMS destination resource

- To edit a JMS destination resource

- To delete a JMS destination resource

## To create a JMS destination resource

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.

   It is a recommended practice to use the naming subcontext prefix `jms/` for JMS resources. For example: `jms/Queue`.

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.

   Property Name | Description
   --- | ---
   `Name` | (Required) The name of the physical destination to which the resource refers.
   `Description` | A description of the physical destination.

8. In the Targets area, do the following:

   1. From the Available column, select 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`.

   2. Click Add to move the target to the Selected column.

9. Click OK.

##### Equivalent asadmin command

`create-jms-resource`

## To edit a JMS destination resource

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.

6. Optionally, click the Targets tab to go to the JMS Destination Resource Targets page. On this page, do the following:

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

   2. Select the checkbox for a target, then click Enable or Disable to enable or disable the resource for that target.

## To delete a JMS destination resource

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

- To create a JMS physical destination

- To delete a JMS physical destination

## To create 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.

1. In the tree component, expand the Configurations node, then expand the Java Message Service node.

2. Select the instance to configure:

   - To configure a particular instance, select the instance’s config node. For example, for the default instance, `server`, select the `server-config` node.

   - To configure the default settings for future instances that use a copy of `default-config`, select the `default-config` node.

3. Select the Physical Destinations node.

4. On the Physical Destinations page, click New.

   The Create Physical Destination page appears.

5. In the Physical Destination Name field, type the name of the destination (for example, `PhysicalQueue`).

6. From the Type drop-down list, choose either `topic` or `queue`.

7. In the Additional Properties area, click Add Property to add a property.

   The following table lists the one property currently available.

   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 if the destination is created for a standalone server instance and -1 if it is created for a cluster.

   To modify the value of this property or to specify other physical destination properties, use the MQ-install-dir`/imq/bin/imqcmd` command. See the Message Queue Administration Guide for more information.

8. Click OK.

##### Equivalent asadmin command

`create-jmsdest`

##### System Destination

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.

## To delete a JMS physical destination

1. In the tree component, expand the Configurations node, then expand the Java Message Service node.

2. Select the instance to configure:

   - To configure a particular instance, select the instance’s config node. For example, for the default instance, `server`, select the `server-config` node.

   - To configure the default settings for future instances that use a copy of `default-config`, select the `default-config` node.

3. Select the Physical Destinations node.

4. On the Physical Destinations page, select the checkbox next to the name of the destination to be deleted.

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

- To configure general properties for the JMS provider

- To create a JMS host

- To edit a JMS host

- To delete a JMS host

## To configure general properties for the JMS provider

Use the JMS Service page to configure properties to be used by all JMS connections.

For more information about configuring the JMS service, see the Application Server Developer’s Guide.

1. In the tree component, select the Configurations node.

2. Select the instance to configure:

   - To configure a particular instance, select the instance’s config node. For example, for the default instance, `server`, select the `server-config` node.

   - To configure the default settings for future instances that use a copy of `default-config`, select the `default-config` node.

3. Select the Java Message Service node to open the JMS Service page.

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

5. From the Type drop-down list:

   - Choose `LOCAL` (the default for the `server-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 the `default-config` configuration) to access the JMS service on another system or on a cluster. 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 Message Queue Administration Guide. If you choose this value and are using a remote host, follow the instructions in To edit a JMS host to specify the name of the remote host.

6. In the Start Arguments field, type arguments to customize the JMS service startup.

   Use any arguments available through the MQ-install-dir`/imq/bin/imqbrokerd` command.

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

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

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

10. Choose a host from the Default JMS Host drop-down list. The default is `default_JMS_host`.

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

12. In the Address List Iterations field, type the number of times the JMS service iterates through the AddressList in an effort to establish (or reestablish) a connection).

    A value of -1 indicates that the number of attempts is unlimited.

    The default value is 3.

13. In the MQ Scheme and MQ Service fields, type the Message Queue address scheme name and the Message Queue connection service name if a non-default 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.

    Scheme Name | Connection Service | Description | Address Syntax
    --- | --- | --- | ---
    `mq` | `jms` and `ssljms` | Message Queue 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 Message Queue 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` | Message Queue 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` | Message Queue 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` | Message Queue client runtime makes an HTTP connection to an Message Queue tunnel servlet at the specified URL. (The broker must be configured to access the HTTP tunnel servlet, as described in the Message Queue 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` | Message Queue client runtime makes a secure HTTPS connection to the specified Message Queue tunnel servlet URL. (The broker must be configured to access the HTTPS tunnel servlet, as described in the Message Queue 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

14. In the Additional Properties area, click Add Property to add a property.

    The following table lists the available Sun Java System Message Queue broker configuration properties.

    Property Name | Description
    --- | ---
    `instance-name` | Specifies the full Message Queue broker instance name. The default is `imqbroker`.
    `instance-name-suffix` | Specifies a suffix to add to the full 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 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`.

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

##### Accessing Remote Servers

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. See To create a JMS connection factory resource.

## To verify JMS Service settings

1. In the tree component, select the Configurations node.

2. Select the instance to configure:

   - To configure a particular instance, select the instance’s config node. For example, for the default instance, `server`, select the `server-config` node.

   - To configure the default settings for future instances that use a copy of `default-config`, select the `default-config` node.

3. Select the Java Message Service node to open the JMS Service page.

4. Click Ping.

   If the JMS service is up and running, the message “Ping succeeded: JMS service is running” appears.

##### Equivalent asadmin command

`jms-ping`

## To create a JMS host

The Application Server Platform Edition 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 Serverhas no way of knowing about them.

1. In the tree component, expand the Configurations node.

2. Select the instance to configure:

   - To configure a particular instance, select the instance’s config node. For example, for the default instance, `server`, select the `server-config` node.

   - To configure the default settings for future instances that use a copy of `default-config`, select the `default-config` node.

3. Expand the Java Message Service node.

4. Select the JMS Hosts node.

5. On the JMS Hosts page, click New. The Create JMS Host page appears.

6. In the Name field, type the name of the host. For example:

       NewJmsHost

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

8. 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 non-default port. (The default port is 7676.)

9. In the Admin Username and Admin Password fields, type the Message Queue broker user name and password.

   These are different from the Application Server user name and password. Edit these fields only if the Message Queue broker values have been changed using the MQ-install-dir`/imq/bin/imqusermgr` command. The default values are `admin` and `admin`.

10. Click OK.

##### Equivalent asadmin command

`create-jms-host`

## To edit a JMS host

1. In the tree component, expand the Configurations node.

2. Select the instance to configure:

   - To configure a particular instance, select the instance’s config node. For example, for the default instance, `server`, select the `server-config` node.

   - To configure the default settings for future instances that use a copy of `default-config`, select the `default-config` node.

3. Expand the Java Message Service node.

4. Select the JMS Hosts node.

5. On the JMS Hosts page, select the host to be edited.

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

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

## To delete a JMS host

1. In the tree component, expand the Configurations node.

2. Select the instance to configure:

   - To configure a particular instance, select the instance’s config node. For example, for the default instance, `server`, select the `server-config` node.

   - To configure the default settings for future instances that use a copy of `default-config`, select the `default-config` node.

3. Expand the Java Message Service node.

4. Select the JMS Hosts node.

5. On the JMS Hosts page, select the checkbox next to the name of the host to be deleted.

6. Click Delete.

   Caution –

   Do not delete all JMS hosts. Doing so will prevent Application Server from restarting. You must leave at least one JMS host.

##### Equivalent asadmin command

`delete-jms-host`

- Previous: Chapter 3 JDBC Resources
- Next: Chapter 5 Configuring JavaMail Resources

- © 2010, Oracle Corporation and/or its affiliates