test

Oracle GlassFish Server 3.0.1 Administration Guide

Chapter 19 Administering the Java Message Service (JMS)

Oracle implements the Java Message Service (JMS) API by integrating the OracleGlassFish Message Queue software into GlassFish Server. This chapter provides procedures for administering JMS resources in the GlassFish Server environment by using the asadmin command-line utility.

Note –

JMS resources are supported only in the Full Platform Profile of GlassFish Server, not in the Web Profile.

The following topics are addressed here:

Instructions for accomplishing the task in this chapter by using the Administration Console are contained in the Administration Console online help.

About the JMS

The JMS API is a messaging standard that allows Java EE applications and components to create, send, receive, and read messages. It enables distributed communication that is loosely coupled, reliable, and asynchronous.

GlassFish Server support for JMS messaging, in general, and for message-driven beans in particular, requires a JMS provider. GlassFish Server uses the Message Queue software as its native JMS provider, providing transparent JMS messaging support. This support is known within GlassFish Server as the JMS Service. JMS requires only minimal administration. When a JMS client accesses a JMS administered object for the first time, the client JVM retrieves the JMS configuration from GlassFish Server.

A JMS resource is a type of connector. Message Queue is integrated with GlassFish Server by means of a connector module, also known as a resource adapter, which is defined by the Java EE Connector Architecture Specification 1.6. Any Java EE components that are deployed to GlassFish Server exchange JMS messages by using the JMS provider that is integrated by the connector module. When a JMS resource is created in GlassFish Server, a connector resource is created in the background. Each JMS operation invokes the connector runtime and uses the Message Queue connector module in the background. GlassFish Server pools JMS connections automatically.

You can configure properties to be used by all JMS connections. If you update these properties at runtime, only those connection factories that are created after the properties are updated will apply the updated values. The existing connection factories will continue to have the original property values. For most values to take effect, GlassFish Server must be restarted. For instructions, see To Restart a Domain. The only property that can be updated without restarting GlassFish Server is the default JMS host.

Message Queue Broker Modes

Message Queue can be integrated with GlassFish Server in LOCAL, REMOTE, or EMBEDDED mode. These modes are represented by the JMS type attribute.

For information about administering Message Queue, see Oracle GlassFish Message Queue 4.4.2 Administration Guide.

Administering JMS Physical Destinations

Messages are delivered for routing and delivery to consumers by using physical destinations in the JMS provider. A physical destination is identified and encapsulated by an administered object (such as a Topic or Queue destination resource) that an application component uses to specify the destination of messages it is producing and the source of messages it is consuming. For instructions on configuring a destination resource, see To Create a Connection Factory or Destination Resource.

If a message-driven bean is deployed and the physical destination it listens to does not exist, GlassFish Server automatically creates the physical destination and sets the value of the maxNumActiveConsumers property to -1. However, it is good practice to create the physical destination beforehand. The first time that 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.

The following topics are addressed here:

ProcedureTo Create a JMS Physical Destination

For production purposes, always create physical destinations. During the development and testing phase, however, this step is not required. Use the create-jmsdest subcommand in remote mode to create a physical destination.

Because a physical destination is actually a Message Queue object rather than a server object, you use Message Queue broker commands to update properties. For information on Message Queue properties, see Oracle GlassFish Message Queue 4.4.2 Administration Guide.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create a JMS physical destination by using the create-jmsdest(1) subcommand.

    Information about the properties for the subcommand is included in this help page.

  3. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

Example 19–1 Creating a JMS Physical Destination

This example creates a queue named PhysicalQueue.


asadmin> create-jmsdest --desttype queue --property 
User=public:Password=public PhysicalQueue
Command create-jmsdest executed successfully.
See Also

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

ProcedureTo List JMS Physical Destinations

Use the list-jmsdest subcommand in remote mode to list the existing JMS physical destinations.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the existing JMS physical destinations by using the list-jmsdest(1) subcommand.

Example 19–2 Listing JMS Physical Destinations

This example lists the physical destinations for the default server instance.


asadmin> list-jmsdest
PhysicalQueue queue {} 
PhysicalTopic topic {}
Command list-jmsdest executed successfully.
See Also

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

ProcedureTo Purge Messages From a Physical Destination

Use the flush-jmsdest subcommand in remote mode to purge the messages from a physical destination in the specified target's JMS service configuration.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Purge messages from the a JMS physical destination by using the flush-jmsdest(1) subcommand.

  3. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

Example 19–3 Flushing Messages From a JMS Physical Destination

This example purges messages from the queue named PhysicalQueue.


asadmin> flush-jmsdest --desttype queue PhysicalQueue
Command flush-jmsdest executed successfully
See Also

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

ProcedureTo Delete a JMS Physical Destination

Use the delete-jmsdest subcommand in remote mode to remove the specified JMS physical destination.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. List the existing JMS physical destinations by using the list-jmsdest(1) subcommand.

  3. Delete the physical resource by using the delete-jmsdest(1) subcommand.

Example 19–4 Deleting a Physical Destination

This example deletes the queue named PhysicalQueue.


asadmin> delete-jmsdest --desttype queue PhysicalQueue
Command delete-jmsdest executed successfully
See Also

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

Administering JMS Connection Factories and Destinations

The JMS API uses two kinds of administered objects. Connection factory objects allow an application to create other JMS objects programmatically. Destination objects serve as repositories for messages. How these objects are created is specific to each implementation of JMS. In GlassFish Server, JMS is implemented by performing the following tasks:

JMS applications use the Java Naming and Directory Interface (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. By studying the application or consulting with the application developer, you can determine what resources must be created. The order in which the resources are created does not matter.

GlassFish Server provides the following types of connection factory objects:

GlassFish Server provides the following types of destination objects:

The following topics are addressed here:

The subcommands in this section can be used to administer both the connection factory resources and the destination resources. For instructions on administering physical destinations, see Administering JMS Physical Destinations.

ProcedureTo Create a Connection Factory or Destination Resource

For each JMS connection factory that you create, GlassFish Server creates a connector connection pool and connector resource. For each JMS destination that you create, GlassFish Server creates a connector admin object resource. If you delete a JMS resource, GlassFish Server automatically deletes the connector resources.

Use the create-jms-resource command in remote mode to create a JMS connection factory resource or a destination resource.

Tip –

To specify the addresslist property (in the format host:mqport,host2:mqport,host3:mqport) for the asadmin create-jms-resource command, escape the : by using \\. For example, host1\\:mqport,host2\\:mqport,host3\\:mpqport. For more information about using escape characters, see the asadmin(1M) concepts page.

To update a JMS connection factory, use the set subcommand for the underlying connector connection pool, See To Update a Connector Connection Pool.

To update a destination, use the set subcommand for the admin object resource. See To Update an Administered Object.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

  2. Create a JMS resource by using the create-jms-resource(1) command.

    Information about the properties for the subcommand is included in this help page.

  3. (Optional) If needed, restart the server.

    Some properties require server restart. See Configuration Changes That Require Server Restart. If your server needs to be restarted, see To Restart a Domain.

Example 19–5 Creating a JMS Connection Factory

This example creates a connection factory resource of type javax.jms.ConnectionFactory whose JNDI name is jms/DurableConnectionFactory. The ClientId property sets a client ID on the connection factory so that it can be used for durable subscriptions. The JNDI name for a JMS resource customarily includes the jms/ naming subcontext. 


asadmin> create-jms-resource --restype javax.jms.ConnectionFactory
--description "connection factory for durable subscriptions"
--property ClientId=MyID jms/DurableConnectionFactory
Command create-jms-resource executed successfully.
Example 19–6 Creating a JMS Destination

This example creates a destination resource whose JNDI name is jms/MyQueue.


asadmin> create-jms-resource --restype javax.jms.Queue 
--property Name=PhysicalQueue jms/MyQueue
Command create-jms-resource executed successfully.
See Also

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

ProcedureTo List JMS Resources

Use the list-jms-resources subcommand in remote mode to list the existing connection factory and destination resources.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

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

Example 19–7 Listing All JMS Resources

This example lists all the existing JMS connection factory and destination resources.


asadmin> list-jms-resources
jms/Queue
jms/ConnectionFactory
jms/DurableConnectionFactory
jms/Topic
Command list-jms-resources executed successfully
Example 19–8 Listing a JMS Resources of a Specific Type

This example lists the resources for the resource type javax.


asadmin> list-jms-resources --restype javax.jms.TopicConnectionFactory 
jms/DurableTopicConnectionFactory 
jms/TopicConnectionFactory 
Command list-jms-resources executed successfully.
See Also

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

ProcedureTo Delete a Connection Factory or Destination Resource

Use the delete-jms-resource subcommand in remote mode to remove the specified connection factory or destination resource.

Before You Begin

Ensure that you remove all references to the specified JMS resource before running this subcommand.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

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

  3. Delete the JMS resource by using the delete-jms-resource(1) subcommand.

Example 19–9 Deleting a JMS Resource

This example deletes the jms/Queue resource.


asadmin> delete-jms-resource jms/Queue
Command delete-jms-resource executed successfully
See Also

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

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.

One of the hosts in the JMS hosts list is designated the default JMS host. GlassFish Server starts the default JMS host when the Message Queue broker mode is configured as type LOCAL.

The following topics are addressed here:

ProcedureTo Create a JMS Host

A default JMS host, default_JMS_host, is provided by GlassFish Server. The default JMS host is used by GlassFish Server to perform all Message Queue broker administrative operations, such as creating and deleting JMS destinations.

Creating a new JMS host is not often necessary and is a task for advanced users. Use the create-jms-host subcommand in remote mode to create an additional JMS host.

Because a JMS is actually a Message Queue object rather than a server object, you use Message Queue broker commands to update properties. For information on Message Queue properties, see Oracle GlassFish Message Queue 4.4.2 Administration Guide.

  1. Ensure that the server is running.

    Remote subcommands require a running server.

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

    Information about the properties for this the subcommand is included in this help page.

Example 19–10 Creating a JMS Host

This example creates a JMS host named MyNewHost.


asadmin> create-jms-host --mqhost pigeon --mqport 7677 MyNewHost
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.

ProcedureTo List JMS Hosts

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

  1. Ensure that the server is running.

    Remote subcommands require a running server.

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

Example 19–11 Listing JMS Hosts

The following subcommand lists the existing JMS hosts.


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

ProcedureTo Update a JMS Host

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

  2. Use the set(1) subcommand to modify a JMS host.

Example 19–12 Updating a JMS Host

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


asadmin>  set server-config.jms-service.jms-host.default_JMS_host.host=
"archie.india.sun.com"
See Also

You can also view the full syntax and options of the subcommand by typing asadmin help set at the command line.

ProcedureTo Delete a JMS Host

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

  1. Ensure that the server is running.

    Remote 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 19–13 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.

Administering Connection Addressing

Certain JMS resources use the JMS host list (AddressList) configuration, which is populated with the hosts and ports of the JMS hosts defined in GlassFish Server. The JMS host list is updated whenever a JMS host configuration changes. The JMS host list is inherited by any JMS resource when it is created, and by any message-driven bean when it is deployed.

In the Message Queue software, the AddressList property is called imqAddressList.

The following topics are addressed here:

Setting JMS Connection Pooling

GlassFish Server pools JMS connections automatically. When a JMS connection pool is created, there is one ManagedConnectionFactory instance associated with it. If you configure the AddressList property as a ManagedConnectionFactory property, the AddressList configuration in the ManagedConnectionFactory value takes precedence over the value defined in GlassFish Server.

Use the create-connector-connection-pool subcommand to manage an existing pool. For instructions, see Administering Connector Connection Pools.

By default, the addresslist-behavior JMS service attribute is set to random. This means that each physical connection (ManagedConnection) created from the ManagedConnectionFactory selects its primary broker in a random way from the AddressList property.

To specify whether GlassFish Server tries to reconnect to the primary broker if the connection is lost, set the reconnect-enabled attribute in the JMS service by using the set(1) subcommand. To specify the number of retries and the time between retries, set the reconnect-attempts and reconnect-interval-in-seconds attributes, respectively.

If reconnection is enabled and the primary broker fails, GlassFish Server tries to reconnect to another broker in the JMS host list (AddressList). The logic for scanning is decided by two JMS service attributes, addresslist-behavior and addresslist-iterations. You can override these settings by using JMS connection factory settings. The Oracle Message Queue software transparently transfers the load to another broker when the failover occurs. JMS semantics are maintained during failover.

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. This creates connections that access remote servers.

Configuring Resource Adapters for JMS

GlassFish Server implements JMS by using a system resource adapter named jmsra. When you create JMS resources, GlassFish Server automatically creates connector resources. The resource adapter can be configured to indicate whether the JMS provider supports XA or not. It is possible to indicate what mode of integration is possible with the JMS provider.

Two modes of integration are supported by the resource adapter. The first one uses JNDI as the means of integration. In this situation, administered objects are set up in the JMS provider's JNDI tree and will be looked up for use by the generic resource adapter. If that mode is not suitable for integration, it is also possible to use the Java reflection of JMS administered object javabean classes as the mode of integration.

Generic resource adapter 1.6 for JMS is a Java EE connector 2.0 resource adapter that can wrap the JMS client library of external JMS providers such as IBM WebSphere MQ, Tibco EMS, and Sonic MQ among others. This integrates any JMS provider with a Java EE 6 application server, such as GlassFish Server. The adapter is a .rar archive that can be deployed and configured using Java EE 6 application server administration tools.

ProcedureTo Configure the Generic Resource Adapter

Before deploying the generic resource adapter, JMS client libraries must be made available to GlassFish Server. For some JMS providers, client libraries might also include native libraries. In such cases, these native libraries must be made available to any GlassFish Server JVMs.

  1. Deploy the generic resource adapter the same way you would deploy a connector module.

  2. Create a connector connection pool.

    See To Create a Connector Connection Pool.

  3. Create a connector resource.

    See To Create a Connector Resource.

  4. Create an administered object resource.

    See To Create an Administered Object.

  5. Make the following changes to the security GlassFish Server policy files:

    • Modify the sjsas_home/domains/domain1/config/server.policy file to add the following:


      java.util.logging.LoggingPermission "control"

    • Modify the sjsas_home/lib/appclient/client.policy file to add permission:


      javax.security.auth.PrivateCredentialPermission 
"javax.resource.spi.security.PasswordCredential ^ \"^\"","read":

Troubleshooting JMS

When you start GlassFish Server, the JMS service is available but is not loaded until it is needed (for example, when you create a JMS resource). Use the jms-ping(1)subcommand to check if the JMS service is running or, if it is not yet running, to start it. If thejms-ping subcommand is unable to contact a built-in JMS service, an error message is displayed.

If you encounter problems, consider the following: