Administering JMS Hosts

A JMS host represents a Message Queue broker. JMS contains a JMS hosts list (the AddressList property) that contains all the JMS hosts that are used by GlassFish Server. The JMS hosts list is populated with the hosts and ports of the specified Message Queue brokers and is updated whenever a JMS host configuration changes. When you create JMS resources or deploy message driven beans, the resources or beans inherit the JMS hosts list.

The following topics are addressed here:

• About JMS Host Types

• Configuring Embedded and Local JMS Hosts

• To Create a JMS Host

• To List JMS Hosts

• To Update a JMS Host

• To Delete a JMS Host

For information about administering JMS hosts that are servicing GlassFish clusters, see Configuring GlassFish Clusters to Use Message Queue Broker Clusters in Oracle GlassFish Server 3.1-3.1.1 High Availability Administration Guide.

About JMS Host Types

The JMS service uses Message Queue (MQ) brokers as JMS hosts, integrating them in three ways:

Embedded Type

When the JMS service configuration's type attribute is EMBEDDED, the MQ broker is co-located in the same JVM as the GlassFish server instance it services. The JMS service starts it in-process and manages its configuration and lifecycle.

For this type, the JMS service uses lazy initialization to start the broker when the first JMS operation is requested instead of immediately when the GlassFish instance is started. If necessary, you can force startup of the broker by using the jms-ping(1) command.

Additionally, if the GlassFish instance is a standalone instance (not a clustered instance), JMS operations use a Message Queue feature called direct mode to bypass the networking stack, leading to performance optimization.

Local Type

When the JMS service configuration's type attribute is LOCAL, the JMS service starts the MQ broker specified in the configuration as the default JMS host in a separate process on the same host as the GlassFish server instance. The JMS service manages its configuration and lifecycle.

For this type, the JMS service starts the broker immediately when the GlassFish instance is started.

The JMS service provides the Message Queue broker an additional port to start the RMI registry. This port number is equal to the broker's JMS port plus 100. For example, if the JMS port number is 37676, then the additional port's number will be 37776. Additionally, the start-args property of the JMS service configuration can be used to specify Message Queue broker startup options.

Remote Type

When the JMS service configuration's type attribute is REMOTE, the JMS service uses the information defined by the default JMS host to communicate with an MQ broker or broker cluster that has been configured and started using Message Queue tools, as described in the Oracle GlassFish Server Message Queue 4.5 Administration Guide. Ongoing administration and tuning of the broker or broker cluster are also performed using Message Queue tools.

Configuring Embedded and Local JMS Hosts

Because the JMS service, not Message Queue, manages Embedded and Local JMS hosts automatically, you should avoid using Message Queue utilities to configure them. Instead, specify broker properties in the JMS service configuration or in the JMS host.

Should the need to use Message Queue utilities arise, you must use the -varhome option when running certain Message Queue utilities to specify the IMQ_VARHOME location of the Embedded or Local JMS host. This location depends on which GlassFish instance the JMS host is servicing:

• For server, the Domain Administration Server (DAS), the IMQ_VARHOME location is:

  domain-root-dir/domain-name/imq

• For any other GlassFish instance, the IMQ_VARHOME location is:

  as-install/nodes/node-name/instance-name/imq

For example, the broker log file for an Embedded or Local JMS host servicing the DAS is available at domain-root-dir/domain-name/imq/instances/imqbroker/log/log.txt, and the broker log file for an Embedded or Local JMS host servicing any other GlassFish instance is available at as-install/nodes/node-name/instance-name/imq/instances/mq-instance-name/log/log.txt.

To Create a JMS Host

The default JMS service configuration includes a JMS host, default_JMS_host. For most situations, this host is sufficient, so replacing it or creating additional JMS hosts is not often necessary and is a task for advanced users. Use the create-jms-host subcommand in remote asadmin mode to create an additional JMS host.

1. Ensure that the server is running.

   Remote asadmin subcommands require a running server.

2. Create the JMS host by using the create-jms-host(1) subcommand:

   asadmin> create-jms-host --mqhost hostName --mqport portNumber
   --mquser adminUser --mqpassword adminPassword --target glassfishTarget
   --property mqBrokerPropList jms-host-name

   --mqhost

   The host name of the Message Queue broker.

   --mqport

   The port number of the Message Queue broker.

   --mquser

   The user name of the administrative user of the Message Queue broker.

   --mqpassword

   The password of the administrative user of the Message Queue broker.

   --target

   The GlassFish Server object for which the JMS host is being created. For details, see create-jms-host(1).

   --property

   A list of one or more Message Queue broker properties to configure the broker. The list is colon-separated (:) and has the form:

   prop1Name=prop1Value:prop2Name=prop2Value:...

   If a broker property name includes dots, preface the dots with two backslashes (\\); for example, to include the imq.system.max_count property, specify imq\\.system\\.max_count in the --property option.

   ---

   Note - You can also set broker properties in the JMS service configuration. If you set the same broker property in both the JMS host and the JMS service configuration, the value specified in the JMS host is used.

   ---

   jms-host-name

   The unique name of the JMS host.

Example 17-1 Creating a JMS Host

This example creates a JMS host named MyNewHost.

asadmin> create-jms-host --mqhost pigeon --mqport 7677
--mquser admin --mqpassword admin MyNewHost
Jms Host MyNewHost created.
Command create-jms-host executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-jms-host at the command line.

To List JMS Hosts

Use the list-jms-hosts subcommand in remote asadmin mode to list the existing JMS hosts.

1. Ensure that the server is running.

   Remote asadmin subcommands require a running server.

2. List the JMS hosts by using the list-jms-hosts(1) subcommand.

Example 17-2 Listing JMS Hosts

The following subcommand lists the existing JMS hosts.

asadmin> list-jms-hosts
default_JMS_host
MyNewHost
Command list-jmsdest executed successfully

To Update a JMS Host

Use the set subcommand in remote asadmin mode to update an existing JMS host.

1. Ensure that the server is running.

   Remote asadmin subcommands require a running server.

2. Use the get(1) subcommand to list the current attribute values of the desired JMS host:

   asadmin> get configs.config.config-name.jms-service.jms-host.jms-host-name.*

   For information about JMS host attributes, see create-jms-host(1).

3. Use the set(1) subcommand to modify a JMS host attribute:

   asadmin> set configs.config.config-name.jms-service.jmshost.
   jms-host-name.attribute-name=attribute-value

   The attributes you can set are:

   host

   The host name of the Message Queue broker.

   port

   The port number of the Message Queue broker.

   admin-user-name

   The user name of the administrative user of the Message Queue broker.

   admin-password

   The password of the administrative user of the Message Queue broker.

   property.broker-property-name

   A Message Queue broker property. The property, and the value assigned to it, are used to configure the Message Queue broker.

   If the broker property name includes dots, preface the dots with two backslashes (\\); for example, to include the imq.system.max_count property, specify imq\\.system\\.max_count in the set subcommand.

   ---

   Note - You can also set broker properties in the JMS service configuration. If you set the same broker property in both the JMS host and the JMS service configuration, the value specified in the JMS host is used.

   ---

Example 17-3 Updating a JMS Host

This example changes the value of the host attribute of the JMS host default_JMS_Host. By default this value is localhost.

asadmin> set configs.config.server-config.jms-service.jms-host.default_JMS_host.host=
"server1.middleware.example.com"

To Delete a JMS Host

Use the delete-jms-host subcommand in remote asadmin mode to delete a JMS host from the JMS service. If you delete the only JMS host, the JMS service will not be able to start until you create a new JMS host.

1. Ensure that the server is running.

   Remote asadmin subcommands require a running server.

2. List the JMS hosts by using the list-jms-hosts(1) subcommand.
3. Delete a JMS host by using the delete-jms-host(1) subcommand.

Example 17-4 Deleting a JMS Host

This example deletes a JMS host named MyNewHost.

asadmin> delete-jms-host MyNewHost
Command delete-jms-host executed successfully.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-jms-host at the command line.