Sun implements the JavaTM Message Service (JMS) API by integrating the Sun GlassFishTM Message Queue software into Sun GlassFish Enterprise Server. This chapter provides procedures for administering JMS resources in the Enterprise Server environment by using the asadmin command-line utility.
JMS resources are supported only in the Full Platform Profile of Enterprise 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.
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.
Enterprise Server support for JMS messaging, in general, and for message-driven beans in particular, requires a JMS provider. Enterprise Server uses the Sun GlassFish Message Queue software as its native JMS provider, providing transparent JMS messaging support. This support is known within Enterprise 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 Enterprise Server.
A JMS resource is a type of connector. Message Queue is integrated with Enterprise 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 Enterprise Server exchange JMS messages by using the JMS provider that is integrated by the connector module. When a JMS resource is created in Enterprise 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. Enterprise 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, Enterprise Server must be restarted. For instructions, see To Restart a Domain. The only property that can be updated without restarting Enterprise Server is the default JMS host.
Message Queue can be integrated with Enterprise Server in LOCAL, REMOTE, or EMBEDDED mode. These modes are represented by the JMS type attribute.
LOCAL Mode. Enterprise Server starts and stops the Message Queue broker that is specified as the default JMS host. The Message Queue process is started in a separate virtual machine from the Enterprise Server process. Enterprise Server supplies an additional port to the broker, which is used by the broker to start the RMI registry. This port number will be equal to the configured JMS port for that instance, plus 100. For example, if the JMS port number is 37676, then this additional port number is 37776.
In LOCAL mode, use the Start Arguments attribute to specify Message Queue broker startup parameters.
REMOTE Mode. When the type attribute is set to REMOTE, the Message Queue broker must be started and stopped separately from Enterprise Server. Message Queue tools must be used to configure and tune the broker. In this situation, Enterprise Server uses an externally–configured broker or broker cluster. REMOTE type is most suitable for clusters.
In REMOTE mode, you must specify Message Queue broker startup parameters using Message Queue tools. The Start Arguments attribute is ignored.
EMBEDDED Mode (default). When the JMS type attribute is set to EMBEDDED, Enterprise Server and the JMS broker are colocated in the same virtual machine. The JMS Service is started in-process and managed by Enterprise Server.
In EMBEDDED mode, the JMS operations bypass the networking stack, which leads to performance optimization.
For information about administering Message Queue, see Sun GlassFish Message Queue 4.4 Administration Guide.
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, Enterprise 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:
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 Sun GlassFish Message Queue 4.4 Administration Guide.
Ensure that the server is running.
Remote subcommands require a running server.
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.
(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.
This example creates a queue named PhysicalQueue.
asadmin> create-jmsdest --desttype queue --property User=public:Password=public PhysicalQueue Command create-jmsdest executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-jmsdest at the command line.
Use the list-jmsdest subcommand in remote mode to list the existing JMS physical destinations.
Ensure that the server is running.
Remote subcommands require a running server.
List the existing JMS physical destinations by using the list-jmsdest(1) subcommand.
This example lists the physical destinations for the default server instance.
asadmin> list-jmsdest PhysicalQueue queue {} PhysicalTopic topic {} Command list-jmsdest executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help list-jmsdest at the command line.
Use the flush-jmsdest subcommand in remote mode to purge the messages from a physical destination in the specified target's JMS service configuration.
Ensure that the server is running.
Remote subcommands require a running server.
Purge messages from the a JMS physical destination by using the flush-jmsdest(1) subcommand.
(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.
This example purges messages from the queue named PhysicalQueue.
asadmin> flush-jmsdest --desttype queue PhysicalQueue Command flush-jmsdest executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help flush-jmsdest at the command line.
Use the delete-jmsdest subcommand in remote mode to remove the specified JMS physical destination.
Ensure that the server is running.
Remote subcommands require a running server.
List the existing JMS physical destinations by using the list-jmsdest(1) subcommand.
Delete the physical resource by using the delete-jmsdest(1) subcommand.
This example deletes the queue named PhysicalQueue.
asadmin> delete-jmsdest --desttype queue PhysicalQueue Command delete-jmsdest executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-jmsdest at the command line.
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 Enterprise Server, JMS is implemented by performing the following tasks:
Creating a connection factory
Creating a destination, which requires creating a physical destination and a destination resource that refers to the physical destination
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.
Enterprise Server provides the following types of connection factory objects:
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 (recommended for new applications)
Enterprise Server provides the following types of destination objects:
Queue objects, used for point-to-point communication
Topic objects, used for publish-subscribe communication
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.
For each JMS connection factory that you create, Enterprise Server creates a connector connection pool and connector resource. For each JMS destination that you create, Enterprise Server creates a connector admin object resource. If you delete a JMS resource, Enterprise 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.
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.
Ensure that the server is running.
Remote subcommands require a running server.
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.
(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.
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. |
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-jms-resource at the command line.
Use the list-jms-resources subcommand in remote mode to list the existing connection factory and destination resources.
Ensure that the server is running.
Remote subcommands require a running server.
List the existing JMS resources by using the list-jms-resources(1) subcommand.
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 |
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. |
You can also view the full syntax and options of the subcommand by typing asadmin help list-jms-resources at the command line.
Use the delete-jms-resource subcommand in remote mode to remove the specified connection factory or destination resource.
Ensure that you remove all references to the specified JMS resource before running this subcommand.
Ensure that the server is running.
Remote subcommands require a running server.
List the existing JMS resources by using the list-jms-resources(1) subcommand.
Delete the JMS resource by using the delete-jms-resource(1) subcommand.
This example deletes the jms/Queue resource.
asadmin> delete-jms-resource jms/Queue Command delete-jms-resource executed successfully |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-jms-resource at the command line.
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 Enterprise 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. Enterprise Server starts the default JMS host when the Message Queue broker mode is configured as type LOCAL.
The following topics are addressed here:
A default JMS host, default_JMS_host, is provided by Enterprise Server. The default JMS host is used by Enterprise 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 Sun GlassFish Message Queue 4.4 Administration Guide.
Ensure that the server is running.
Remote subcommands require a running server.
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.
This example creates a JMS host named MyNewHost.
asadmin> create-jms-host --mqhost pigeon --mqport 7677 MyNewHost Command create-jms-host executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help create-jms-host at the command line.
Use the list-jms-hosts subcommand in remote mode to list the existing JMS hosts.
Ensure that the server is running.
Remote subcommands require a running server.
List the JMS hosts by using the list-jms-hosts(1) subcommand.
The following subcommand lists the existing JMS hosts.
asadmin> list-jms-hosts default_JMS_host MyNewHost Command list-jmsdest executed successfully |
List the JMS hosts by using the list-jms-hosts(1) subcommand.
Use the set(1) subcommand to modify 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" |
You can also view the full syntax and options of the subcommand by typing asadmin help set at the command line.
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.
Ensure that the server is running.
Remote subcommands require a running server.
List the JMS hosts by using the list-jms-hosts(1) subcommand.
Delete a JMS host by using the delete-jms-host(1) subcommand.
This example deletes a JMS host named MyNewHost.
asadmin> delete-jms-host MyNewHost Command delete-jms-host executed successfully. |
You can also view the full syntax and options of the subcommand by typing asadmin help delete-jms-host at the command line.
Certain JMS resources use the JMS host list (AddressList) configuration, which is populated with the hosts and ports of the JMS hosts defined in Enterprise 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:
Enterprise 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 Enterprise 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 Enterprise 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, Enterprise 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 Sun GlassFish Message Queue software transparently transfers the load to another broker when the failover occurs. JMS semantics are maintained during failover.
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.
Enterprise Server implements JMS by using a system resource adapter named jmsra. When you create JMS resources, Enterprise 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 the Sun GlassFish Enterprise Server. The adapter is a .rar archive that can be deployed and configured using Java EE 6 application server administration tools.
Before deploying the generic resource adapter, JMS client libraries must be made available to Enterprise Server. For some JMS providers, client libraries might also include native libraries. In such cases, these native libraries must be made available to any Enterprise Server JVMs.
Deploy the generic resource adapter the same way you would deploy a connector module.
Create a connector connection pool.
Create a connector resource.
Create an administered object resource.
Make the following changes to the security Enterprise 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": |
When you start Enterprise 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:
View the Enterprise Server log file, typically located at domain-dir/logs/server.log.
If a the log file indicates that a Message Queue broker did not respond to a message, stop the broker and then restart it.
View the broker log, typically available at as-install/domains/domain1/imq/instances/imqbroker/log/log.txt.
For JMS REMOTE mode, be sure to start Message Queue brokers first, then Enterprise Server.
If all Message Queue brokers are down, it takes 30 minutes for Enterprise Server to go down or up when you are using the default values in JMS. You can change the default values for this timeout. For example:
asadmin set domain1.jms-service.reconnect-interval-in-seconds=5 |