set configs.config.config-name.jms-service.attribute-name=attribute-value17 Administering the Java Message Service (JMS)
The Java Message Service (JMS) API is a messaging standard that allows Java EE applications and components, including message-driven beans (MDBs), to create, send, receive, and read messages. It enables distributed communication that is loosely coupled, reliable, and asynchronous.
GlassFish Server supports JMS messaging by communicating with a JMS
provider through a Java EE Connector resource adapter. By default,
GlassFish Server provides JMS messaging through its built-in jmsra
resource adapter communicating with Open Message Queue, which is
included with GlassFish Server. This combination, known as the JMS
Service, is tightly integrated with GlassFish Server, providing a rich
set of asadmin subcommands and Administration Console pages to
simplify JMS messaging administration tasks.
GlassFish Server also supports the Generic Resource Adapter for JMS (GenericJMSRA) for use as a resource adapter to connect to other JMS providers. The last section in this chapter, Using the Generic Resource Adapter for JMS to Integrate Supported External JMS Providers, describes the GenericJMSRA and provides instructions for using it to make other supported JMS providers available to GlassFish Server.
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 Service
To support JMS messaging, the JMS Service provides the following administrative objects:
- JMS Service Configuration
-
The JMS service configuration is part of the overall configuration for a GlassFish standalone instance or cluster. It specifies how the JMS Service is to create and maintain connections with JMS Hosts.
- JMS Hosts
-
JMS hosts are the message servers that host destinations, store messages, and interact with applications to send and receive messages across connections. In Message Queue, JMS hosts are called brokers.
The JMS service supports these types of JMS hosts:-
Embedded type, in which the JMS host runs in the same JVM as the GlassFish instance; its configuration and lifecycle are managed by the JMS service
-
Local type, in which the JMS host runs separately on the same host as the GlassFish instance; its configuration and lifecycle are managed by the JMS service
-
Remote type, in which the JMS host represents a Message Queue broker or broker cluster that is external to the JMS service; its operation is managed using Message Queue administrative tools
For more information about JMS host types, see About JMS Host Types.
-
- JMS Connection Factory Resources
-
JMS connection factory resources house the information that applications use to connect to a JMS provider. For each JMS connection factory, the JMS service automatically maintains a GlassFish connector resource and a GlassFish connector connection pool in order to support connection pooling and failover.
- JMS Destination Resources
-
JMS destination resources house the information that applications use to specify the target destination of messages they produce and the source destination of messages they consume. For each JMS destination resource, the JMS service automatically maintains a GlassFish administered object.
- JMS Physical Destinations
-
JMS physical destinations provide a means to create and manage JMS destinations administratively instead of having them created dynamically when needed by an application. While dynamic creation of destinations is often sufficient during application development, administratively created physical destinations are more suitable for production environments.
JMS Service High Availability
Just as GlassFish Server supports clusters of instances to provide high availability, Message Queue supports clusters of brokers to provide service availability or service and data availability, depending on the type of broker cluster, as described in "Broker Clusters" in Open Message Queue Technical Overview.
The JMS service takes advantage of this Message Queue capability and automatically creates and manages a Message Queue broker cluster when a GlassFish cluster’s configuration specifies Embedded or Local type JMS hosts. Additionally, both GlassFish clusters and standalone instances can use Message Queue broker clusters as Remote type JMS hosts.
For information about how the JMS service supports GlassFish clusters and Message Queue broker clusters, see "Configuring Java Message Service High Availability" in GlassFish Server Open Source Edition High Availability Administration Guide.
Updating the JMS Service Configuration
Because the JMS service configuration is part of the overall
configuration for a standalone instance or cluster, it is created when
the standalone instance or cluster is created. You can then update the
JMS service configuration by using the Java Message Service page for the
configuration in the Administration Console, or by using a set
subcommand of the following form:
The attributes you can set are:
type-
The JMS host type the service is to use. Available choices are
EMBEDDED,LOCALandREMOTE. See About JMS Host Types for more information. init-timeout-in-seconds-
The number of seconds GlassFish Server waits for the JMS service to start before aborting the startup.
start-args-
A list of arguments the JMS service passes to Embedded and Local type JMS hosts on startup. Permissible arguments are the options supported by the Message Queue
imqbrokerdcommand, as described in "Broker Utility" in Open Message Queue Administration Guide. default-jms-host-
The name of the default JMS host.
reconnect-enabled-
When set to
true, the JMS service attempts to reconnect to a JMS host (or one of the JMS hosts in the AddressList) when a connection is lost. reconnect-attempts-
The number of attempts to connect (or reconnect) for each JMS host in the AddressList before the JMS service tries the next address in the list. A value of -1 indicates that the number of reconnect attempts is unlimited (the JMS service attempts to connect to the first address until it succeeds).
reconnect-interval-in-seconds-
The number of seconds between reconnect attempts. This interval applies for attempts on each JMS host in the AddressList and for successive addresses in the list. If it is too short, this time interval does not give a JMS host time to recover. If it is too long, the reconnect might represent an unacceptable delay.
addresslist-behavior-
The order of connection attempts. Available choices are:
random-
Select a JMS host from the AddressList randomly. If there are many clients attempting a connection using the same connection factory, specify
randomto prevent them from all being connected to the same JMS host. priority-
Always try to connect to the first JMS host in the AddressList and use another one only if the first one is not available.
addresslist-iterations-
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.
mq-schememq-service-
The Message Queue address scheme name and connection service name to use for the AddressList if a non-default scheme or service is to be used. See "Connection Handling" in Open Message Queue Administration Guide for syntax information.
|
Note
|
After making changes to the JMS service configuration, GlassFish Server instances that use the configuration must be restarted in order for the changes to be propagated. |
Setting Message Queue Broker Properties in the JMS Service Configuration
You can specify any Message Queue broker property in the JMS service
configuration by adding it by name to the Additional Properties table on
the Java Message Service page for the configuration in the
Administration Console, or by using a set subcommand of the following
form:
set configs.config.config-name.jms-service.property.broker-property-name=valueIf the broker property name includes dots, preface the dots with two
backslashes (\\); for example, to set 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 host. If you set the same broker property in both the JMS service configuration and the JMS host, the value specified in the JMS host is used. |
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:
For information about administering JMS hosts that are servicing GlassFish clusters, see "Configuring GlassFish Clusters to Use Message Queue Broker Clusters" in GlassFish Server Open Source Edition 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
typeattribute isEMBEDDED, 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 thejms-pingcommand.
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
typeattribute isLOCAL, 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, thestart-argsproperty of the JMS service configuration can be used to specify Message Queue broker startup options. - Remote Type
-
When the JMS service configuration’s
typeattribute isREMOTE, 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 Open Message Queue 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), theIMQ_VARHOMElocation is:
domain-root-dir/domain-dir/imq
-
For any other GlassFish instance, the
IMQ_VARHOMElocation 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-dir/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`.
|
Note
|
When using Message Queue utilities on the Windows platform, you must
explicitly use the Windows executable ( |
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.
-
Ensure that the server is running.
Remoteasadminsubcommands require a running server. -
Create the JMS host by using the
create-jms-hostsubcommand:
asadmin> create-jms-host --mqhost hostName --mqport portNumber --mquser adminUser --mqpassword adminPassword --target glassfishTarget --property mqBrokerPropList --force trueFalse 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 theimq.system.max_countproperty, specifyimq\\.system\\.max_countin the--propertyoption.
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. |
--force-
Specifies whether the subcommand overwrites the existing JMS host of the same name. The default value is
false. - 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.
-
Ensure that the server is running.
Remoteasadminsubcommands require a running server. -
List the JMS hosts by using the
list-jms-hostssubcommand.
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 successfullyTo Update a JMS Host
Use the set subcommand in remote asadmin mode to update an existing
JMS host.
-
Ensure that the server is running.
Remoteasadminsubcommands require a running server. -
Use the
getsubcommand 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 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 theimq.system.max_countproperty, specifyimq\\.system\\.max_countin thesetsubcommand.
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.
-
Ensure that the server is running.
Remoteasadminsubcommands require a running server. -
List the JMS hosts by using the
list-jms-hostssubcommand. -
Delete a JMS host by using the
delete-jms-hostsubcommand.
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.
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:
-
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.
The Java EE standard specifies that certain default resources be made
available to applications, and defines specific JNDI names for these
default resources. GlassFish Server makes these names available through
the use of logical JNDI names, which map Java EE standard JNDI names to
specific GlassFish Server resources. For JMS connection factory
resources, the Java EE standard name
java:comp/DefaultJMSConnectionFactory is mapped to the
jms/__defaultConnectionFactory resource.
GlassFish Server provides the following types of connection factory objects:
-
QueueConnectionFactoryobjects, used for point-to-point communication -
TopicConnectionFactoryobjects, used for publish-subscribe communication -
ConnectionFactoryobjects, which can be used for both point-to-point and publish-subscribe communications (recommended for new applications)
GlassFish Server provides the following types of destination objects:
-
Queueobjects, used for point-to-point communication -
Topicobjects, 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 information on JMS service support of connection pooling and failover, see "Connection Failover" in GlassFish Server Open Source Edition High Availability Administration Guide. For instructions on administering physical destinations, see Administering JMS Physical Destinations.
To 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 asadmin mode to create
a JMS connection factory resource or a destination resource.
|
Tip
|
To specify the |
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.
Remoteasadminsubcommands require a running server. -
Create a JMS resource by using the
create-jms-resourcecommand.
Information about the properties for the subcommand is included in this help page. -
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Example 17-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 17-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.
To List JMS Resources
Use the list-jms-resources subcommand in remote asadmin mode to list
the existing connection factory and destination resources.
-
Ensure that the server is running.
Remoteasadminsubcommands require a running server. -
List the existing JMS resources by using the
list-jms-resourcessubcommand.
Example 17-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 successfullyExample 17-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.
To Delete a Connection Factory or Destination Resource
Use the delete-jms-resource subcommand in remote asadmin 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.
-
Ensure that the server is running.
Remoteasadminsubcommands require a running server. -
List the existing JMS resources by using the
list-jms-resourcessubcommand. -
Delete the JMS resource by using the
delete-jms-resourcesubcommand.
Example 17-9 Deleting a JMS Resource
This example deletes the jms/Queue resource.
asadmin> delete-jms-resource jms/Queue
Command delete-jms-resource executed successfullySee 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 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.
This automatically created physical destination is temporary and expires
after a period specified by a Message Queue configuration property,
provided that there are no messages in it and no message producers or
consumers connected to it.
The following topics are addressed here:
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. Use
the create-jmsdest subcommand in remote asadmin 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 the Open Message Queue Administration Guide.
-
Ensure that the server is running.
Remoteasadminsubcommands require a running server. -
Create a JMS physical destination by using the
create-jmsdestsubcommand.
Information about the properties for the subcommand is included in this help page. -
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Example 17-10 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.
To List JMS Physical Destinations
Use the list-jmsdest subcommand in remote asadmin mode to list the
existing JMS physical destinations.
-
Ensure that the server is running.
Remoteasadminsubcommands require a running server. -
List the existing JMS physical destinations by using the
list-jmsdestsubcommand.
Example 17-11 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.
To Purge Messages From a Physical Destination
Use the flush-jmsdest subcommand in remote asadmin mode to purge the
messages from a physical destination in the specified target’s JMS
service configuration.
-
Ensure that the server is running.
Remoteasadminsubcommands require a running server. -
Purge messages from the a JMS physical destination by using the
flush-jmsdestsubcommand. -
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Example 17-12 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 successfullySee Also
You can also view the full syntax and options of the subcommand by
typing asadmin help flush-jmsdest at the command line.
To Delete a JMS Physical Destination
Use the delete-jmsdest subcommand in remote asadmin mode to remove
the specified JMS physical destination.
-
Ensure that the server is running.
Remoteasadminsubcommands require a running server. -
List the existing JMS physical destinations by using the
list-jmsdestsubcommand. -
Delete the physical resource by using the
delete-jmsdestsubcommand.
Example 17-13 Deleting a Physical Destination
This example deletes the queue named PhysicalQueue.
asadmin> delete-jmsdest --desttype queue PhysicalQueue
Command delete-jmsdest executed successfullySee Also
You can also view the full syntax and options of the subcommand by
typing asadmin help delete-jmsdest at the command line.
Special Situations When Using the JMS Service
As mentioned earlier, Message Queue, through the built-in jmsra
resource adapter, is tightly integrated with GlassFish Server to provide
JMS messaging managed through a rich set of asadmin subcommands and
Administration Console pages to simplify JMS messaging administration
tasks. In most instances, this tight integration is transparent and
automatic, requiring no special effort on the part of an administrator.
In certain special situations, though, an administrator must perform a
task such a setting a Message Queue broker property or a GlassFish
object attribute to enable or disable a capability of the integration.
The topics in this section describe these situations.
- Restarting an Embedded or Local Broker That Has Failed
-
Because the JMS service, not Message Queue, manages the lifecycle of brokers acting as Embedded and Local JMS hosts, do not use the
imqbrokerdMessage Queue utility to start such a broker that has failed. Instead, restart the GlassFish instance that the broker is servicing. - Changing the Admin User Password for an Embedded or Local Broker
-
Follow these steps to change the
adminuser password for an Embedded or Local broker:-
Use theimqusermgrMessage Queue utility to change the password of theadminuser. -
Edit the configuration of the JMS host, changing the password of theadminuser to the new password. -
Restart the GlassFish instance that the broker is servicing.
When changing the password for the brokers in a broker cluster, first perform steps 1 and 2 on each broker. Then, perform step 3. Finally, perform step 4 on each broker. Using SSL to Connect to an Oracle Internet Directory (OID) or Oracle
- Virtual Directory (OVD) User Respository
-
When using SSL to connect to an OID or OVD user repository, you must set the
imq.user_repository.ldap.ssl.socketfactoryMessage Queue broker property tocom.sun.enterprise.security.auth.realm.ldap.CustomSocketFactory.
Troubleshooting the JMS Service
If you encounter problems, consider the following:
-
Use the
jms-pingsubcommand to confirm that the Message Queue broker is running. -
View the GlassFish Server log file. For
server, the Domain Administrations Server (DAS), the log is available at domain-dir`/logs/server.log`; for other GlassFish instances, the log is available at as-install`/nodes/node-name/instance-name/logs/server.log`.
If the log file indicates that a Message Queue broker acting as a Remote JMS host did not respond to a message, stop the broker and then restart it. -
View the broker log. For a broker associated with the Domain Administration Server (DAS), the log is available at domain-dir`/imq/instances/imqbroker/log/log.txt`; for brokers associated with other GlassFish instances, the log is available at as-install`/nodes/
node-name/instance-name/imq/instances/mq-instance-name/log/log.txt`. -
For Remote type JMS hosts, be sure to start Message Queue brokers first, then GlassFish Server instances.
-
If all Message Queue brokers are down, it can take up to 30 minutes for GlassFish 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
Using the Generic Resource Adapter for JMS to Integrate Supported External JMS Providers
GlassFish Server supports the integration and use of Oracle WebLogic JMS
and IBM WebSphere MQ JMS providers through the use of the Generic
Resource Adapter for JMS (GenericJMSRA). This Java EE connector 1.5
resource adapter can wrap the JMS client library of Oracle WebLogic JMS
and IBM WebSphere MQ and make it available for use by GlassFish. The
adapter is a .rar archive that can be deployed and configured using
GlassFish Server administration tools.
The following topics are addressed here:
Configuring GenericJMSRA for Supported External JMS Providers
GenericJMSRA has three main properties that need to be configured:
SupportXA, DeliveryType, and ProviderIntegrationMode. The values
that need to be set for them depends on the capabilities of the JMS
provider being used, as follows:
-
SupportXA— indicates whether the JMS provider supports XA or not. -
DeliveryType— indicates whether an MDB should use aConnectionConsumerorConsumer.receive()when consuming messages. -
ProviderIntegrationMode— indicates what mode of integration is required. The available integration modes are jndi and javabean. Some JMS providers support only one integration mode while others may offer the choice of both-
If jndi is specified, then the resource adapter will obtain JMS connection factories and destinations from the JMS provider’s JNDI repository.
-
If javabean is specified then the resource adapter will obtain JMS connection factories and destinations by instantiating the appropriate classes directly.
Which option is specified determines which other properties need to be set.
-
To Deploy and Configure GenericJMSRA
Before deploying GenericJMSRA, 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.
-
Download the
genericra.rararchive. -
Deploy GenericJMSRA the same way you would deploy a connector module.
See "Deploying a Connector Module" in GlassFish Server Open Source Edition Application Deployment Guide. -
Configure the resource adapter’s properties.
See GenericJMSRA Configuration Properties. -
Create a connector connection pool.
See To Create a Connector Connection Pool. -
Create a connector resource.
See To Create a Connector Resource. -
Create an administered object resource.
See To Create an Administered Object.
GenericJMSRA Configuration Properties
The following table describes the properties that can be set to when configuring the resource adapter.
| Property Name | Valid Values | Default Value | Description |
|---|---|---|---|
|
|
false |
Specifies whether the JMS client supports XA transactions. |
|
|
Asynchronous |
Specifies whether an MDB should use a
|
|
A valid class name |
None |
Class name
of |
|
A valid class name |
None |
Class name
of |
|
A valid class name |
None |
Class name of
|
|
A valid class name |
None |
Class
name of |
|
A valid class name |
None |
Class
name of |
|
A valid class name |
None |
Class Name of
|
|
A valid class name |
None |
Class Name of
|
|
Name value pairs separated by comma |
None |
Specifies the |
|
Name value pairs separated by comma |
None |
Specifies
the JNDI provider properties to be used for connecting to the JMS
provider’s JNDI. Used only if |
|
Method name |
None |
Specifies the common
setter method name that some JMS vendors use to set the properties on
their administered objects. Used only if |
|
Name of the JMS user |
None |
User name to connect to the JMS Provider. |
|
Password for the JMS user |
None |
Password to connect to the JMS provider. |
|
|
|
The Some |
Connection Factory Properties
ManagedConnectionFactory properties are specified when a
connector-connection-pool is created. All the properties specified
while creating the resource adapter can be overridden in a
ManagedConnectionFactory. Additional properties available only in
ManagedConnectionFactory are given below.
| Property Name | Valid Value | Default Value | Description |
|---|---|---|---|
|
A valid client ID |
None |
|
|
JNDI Name |
None |
JNDI name of the
connection factory bound in the JNDI tree of the JMS provider. The
administrator should provide all connection factory properties (except
|
|
true/false |
false |
If set to true, the
resource adapter will use an exception listener to catch any connection
exception and will send a |
Destination Properties
Properties in this section are specified when a destination (queue or topic) is created. All the resource adapter properties can be overridden in a destination. Additional properties available only in the destination are given below.
| Property Name | Valid Value | Default Value | Description |
|---|---|---|---|
|
JNDI Name |
None |
JNDI name of the destination
bound in the JNDI tree of the JMS provider. The Administrator should
provide all properties in the JMS provider itself. This property name
will be used only if |
|
Name value pairs separated by a comma |
None |
Specifies the |
Activation Spec Properties
Properties in this section are specified in the GlassFish Server
glassfish-ejb-jar.xml deployment descriptor of an MDB as
activation-config-properties. All the resource adapter properties can
be overridden in an Activation Spec. Additional properties available
only in ActivationSpec are given below.
| Property Name | Valid Value | Default Value | Description |
|---|---|---|---|
|
An integer |
8 |
Maximum size of server session pool internally created by the resource adapter for achieving concurrent message delivery. This should be equal to the maximum pool size of MDB objects. |
|
An integer |
3 |
The resource adapter will wait for the time in seconds specified by this property to obtain a server session from its internal pool. If this limit is exceeded, message delivery will fail. |
|
Durable or Non-Durable |
Non-Durable |
|
|
+ |
None |
|
|
A valid message selector |
None |
|
|
A valid client ID |
None |
|
|
A valid JNDI Name |
None |
JNDI name of
connection factory created in JMS provider. This connection factory will
be used by resource adapter to create a connection to receive messages.
Used only if |
|
A valid JNDI Name |
None |
JNDI name of
destination created in JMS provider. This destination will be used by
resource adapter to create a connection to receive messages from. Used
only if |
|
|
Null |
Type of the destination the MDB will listen to. |
|
Name-value pairs separated by comma |
None |
Specifies the |
|
integer |
+ |
Number of times a message will be delivered if a message causes a runtime exception in the MDB. |
|
time in seconds |
+ |
Interval between repeated deliveries, if a message causes a runtime exception in the MDB. |
|
true/false |
False |
Indicates whether the resource adapter should send the messages to a dead message destination, if the number of delivery attempts is exceeded. |
|
a valid JNDI name. |
None |
JNDI name
of the destination created in the JMS provider. This is the target
destination for dead messages. This is used only if
|
|
class name of destination object. |
None |
Used if |
|
Name Value Pairs separated by comma |
None |
Specifies the |
|
a valid JNDI name |
None |
JNDI
name of the connection factory created in the JMS provider. This is the
target connection factory for dead messages. This is used only if
|
|
queue or topic destination |
None |
The destination type for dead messages. |
|
integer |
0 |
Number of times a reconnect will be attempted in case exception listener catches an error on connection. |
|
time in seconds |
0 |
Interval between reconnects. |
Using GenericJMSRA with WebLogic JMS
You can configure GenericJMSRA to enable applications running in GlassFish Server to send messages to, and receive messages from, Oracle WebLogic JMS.
GenericJMSRA should be used in conjunction with the WebLogic Server Thin T3 Client. Due to the nature of this client, messages exchanged between GlassFish Server and WebLogic Server cannot be sent or received in XA transactions. There is also only limited support for asynchronous receipt of messages in an MDB, as described in detail in Limitations When Using GenericJMSRA with WebLogic JMS.
The following topics are addressed here:
Deploy the WebLogic Thin T3 Client JAR in GlassFish Server
WebLogic Server provides several different clients for use by standalone
applications that run outside of WebLogic Server. These client are
summarized in
"http://www.oracle.com/pls/as1111/lookup?id=SACLT117[Overview of
Stand-alone Clients"] in Programming Stand-alone Clients for Oracle
WebLogic Server. When connecting from GlassFish Server to WebLogic JMS
resources you must use the WebLogic Thin T3 client,
wlthint3client.jar.
There are a couple of methods to deploy the WebLogic Thin T3 client in GlassFish Server and make it available to GenericJMSRA:
-
To make the Thin T3 client available to all applications, copy the
wlthint3client.jarto the as-install`/lib` directory under your GlassFish Server installation. The Thin T3 client can be found in a WebLogic Server installation in a directory similar to MW_HOME`/server/lib`. -
It is also possible to deploy the Thin T3 client in a less global manner, so that it is specific to an individual application. For information on how to do this, see "Application-Specific Class Loading" in GlassFish Server Open Source Edition Application Development Guide.
Configure WebLogic JMS Resources for Integration
If you need to configure the necessary WebLogic JMS resources on the WebLogic Server from which you want to access messages using GlassFish Server, then follow the instructions in the WebLogic Server documentation for configuring the necessary resources, such as destinations, and connection factories.
-
JMS System Module Configuration
-
Queue and Topic Destination Configuration
-
Connection Factory Configuration
The example code snippets in this section refer to a WebLogic JMS
connection factory named WLoutboundQueueFactory and queue destination
named WLoutboundQueue. For conceptual overviews on configuring
WebLogic JMS resources, refer to
"http://www.oracle.com/pls/as1111/lookup?id=JMSAD123[Understanding JMS
Resource Configuration]" in Configuring and Managing JMS for Oracle
WebLogic Server. For detailed instructions on configuring WebLogic JMS
resources, refer to
"http://www.oracle.com/pls/as1111/lookup?id=WLACH01854[Configure JMS
system modules and add JMS resources]" in the WebLogic Administration
Console Online Help.
Create a Resource Adapter Configuration for GenericJMSRA to Work With WebLogic JMS
When you deploy GenericJMSRA, you also need to create a resource adapter
configuration in GlassFish Server. You can do this using either the
Administration Console or the asadmin command. If you use
theAdministration Console then you need deploy the GenericJMSRA resource
archive first. Here’s an example using asadmin:
asadmin create-resource-adapter-config --host localhost --port 4848 --property
SupportsXA=false:DeliveryType=Synchronous:ProviderIntegrationMode
=jndi:JndiProperties=java.naming.factory.initial\
=weblogic.jndi.WLInitialContextFactory,java.naming.provider.url\
=t3\://localhost\:7001,java.naming.factory.url.pkgs\
=weblogic.corba.client.naming genericraThis creates a resource adapter configuration with the name genericra,
and Oracle recommends not changing the default name. The resource
adapter configuration is configured with the properties specified using
the --properties argument; multiple properties are configured as a
colon-separated list of name-value pairs that are entered as a single
line. You will also need to change the host and port that WebLogic
Server is running on to suit your installation.
In this example, the following properties are configured:
| Property | Value |
|---|---|
|
|
|
|
|
|
|
|
You must use the same values for SupportsXA, DeliveryType and
ProviderIntegrationMode as the required values that are used in this
table. The JndiProperties value must be set to a list of JNDI
properties needed for connecting to WebLogic JNDI.
|
Note
|
When using |
For a description of all the resource adapter properties that are relevant for WebLogic JMS, see the Configuration Reference of GenericJMSRA Properties for WebLogic JMS.
Deploy the GenericJMSRA Resource Archive
-
Download the GenericJMSRA resource archive (genericra.rar).
-
Deploy the resource adapter. You can do this using either the Administration Console or the
asadmindeploy command. Here’s an example using theasadmindeploy command:
$ asadmin deploy --user admin --password adminadmin <location of the generic resource adapter rar file>
If you deploy the resource adapter using the Administration Console, then after deployment you need to create a resource adapter configuration as described in Create a Resource Adapter Configuration for GenericJMSRA to Work With WebLogic JMS.
Configuring an MDB to Receive Messages from WebLogic JMS
In this example, all configuration information is defined in two
deployment descriptor files: ejb-jar.xml and the GlassFish Server
glassfish-ejb-jar.xml file. To configure a MDB to receive messages
from WebLogic JMS, you would configure these deployment descriptor files
as follows:
-
Configure the ejb-jar.xml deployment descriptor:
<ejb-jar>
<enterprise-beans>
<message-driven>
<ejb-name>SimpleMessageEJB</ejb-name>
<ejb-class>test.simple.queue.ejb.SimpleMessageBean</ejb-class>
<transaction-type>Container</transaction-type>
</message-driven>
</enterprise-beans>
<assembly-descriptor>
<container-transaction>
<method>
<ejb-name>SimpleMessageEJB</ejb-name>
<method-name>onMessage</method-name>
<method-params>
<method-param>javax.jms.Message</method-param>
</method-params>
</method>
<trans-attribute>NotSupported</trans-attribute>
</container-transaction>
</assembly-descriptor>
</ejb-jar>
|
Note
|
If container-managed transactions are configured, then the transactional
attribute must be set to |
-
Configure the glassfish-ejb-jar.xml deployment descriptor:
<sun-ejb-jar>
<enterprise-beans>
<ejb>
<ejb-name>SimpleMessageEJB</ejb-name>
<mdb-resource-adapter>
<resource-adapter-mid>genericra</resource-adapter-mid>
<activation-config>
<activation-config-property>
<activation-config-property-name>
ConnectionFactoryJndiName
</activation-config-property-name>
<activation-config-property-value>
jms/WLInboundQueueFactory
</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>
DestinationJndiName
</activation-config-property-name>
<activation-config-property-value>
jms/WLInboundQueue
</activation-config-property-value>
</activation-config-property>
</activation-config>
</mdb-resource-adapter>
</ejb>
</enterprise-beans>
</sun-ejb-jar>
where:
The <resource-adapter-mid>genericra</resource-adapter-mid> element is
used to specify the resource adapter and resource adapter configurations
that was deployed in the Create a Resource Adapter
Configuration for GenericJMSRA to Work With WebLogic JMS instructions.
It is recommended you stick to genericra as is used here.
The activation-config element in glassfish-ejb-jar.xml is the one
which defines how and where the MDB receives messages, as follows:
* The ConnectionFactoryJndiName property must be set to the JNDI name
of the connection factory in the WebLogic JNDI store that will be used
to receive messages. Therefore, replace jms/WLInboundQueueFactory in
the example above with the JNDI name used in your environment.
* The DestinationJndiName property must be set to the JNDI name of the
destination (the queue or topic from which messages will be consumed) in
the WebLogic JNDI store. Therefore, replace jms/WLInboundQueue in the
example above with the JNDI name used in your environment.
For a description of all the ActivationSpec properties that are relevant
for WebLogic JMS, see the Configuration Reference of
GenericJMSRA Properties for WebLogic JMS.
Make sure to use the appropriate WebLogic administration tools, such as
the WebLogic Administration Console or the WebLogic Scripting Tool
(WLST). For more information, see
"http://www.oracle.com/pls/as1111/lookup?id=WLACH01853[Configure
Messaging]" in WebLogic Server Administration Console Online Help and
WebLogic Server WLST
Online and Offline Command Reference.
Accessing Connections and Destinations Directly
When configuring a MDB to consume messages from WebLogic JMS your code does not need to access the WebLogic JMS connection factory and destination directly. You simply define them in the activation configuration, as shown in Configuring an MDB to Receive Messages from WebLogic JMS. However when configuring an MDB to send messages, or when configuring a EJB, Servlet, or application client to either send or receive messages, your code needs to obtain these objects using a JNDI lookup.
|
Note
|
If you want configure connections and destination resources using the
Administration Console, this is explained in the Administration Console
online help. When using Administration Console, follow the instructions
for creating a new Connector Connection Pool and Admin Object Resources,
and not the instructions for creating a JMS Connection Pool and
Destination Resources. For more information about using |
-
Looking up the connection factory and destination
The following code looks up a connection factory with the JNDI namejms/QCFactoryand a queue with the name`jms/outboundQueue` from the GlassFish Server JNDI store:
Context initialContect = new InitialContext();
QueueConnectionFactory queueConnectionFactory = (QueueConnectionFactory)
jndiContext.lookup("java:comp/env/jms/MyQCFactory");
Queue queue = (Queue) jndiContext.lookup("java:comp/env/jms/outboundQueue");
Note that the resources used are GlassFish Server resources, not
WebLogic JMS resources. For every connection factory or destination that
you want to use in the WebLogic JMS JNDI store, you need to create a
corresponding connection factory or destination in the GlassFish Server
JNDI store and configure the GlassFish Server object to point to the
corresponding WebLogic JMS object.
2. Declaring the connection factory and destination
In accordance with standard Java EE requirements, these resources need
to be declared in the deployment descriptor for the MDB, EJB or other
component. For example, for a session bean, configure the ejb-jar.xml
with <resource-env-ref> elements, as follows:
<ejb-jar>
<enterprise-beans>
<session>
. . .
<resource-env-ref>
<resource-env-ref-name>jms/QCFactory</resource-env-ref-name>
<resource-env-ref-type>javax.jms.QueueConnectionFactory</resource-env-ref-type>
</resource-env-ref>
<resource-env-ref>
<resource-env-ref-name>jms/outboundQueue</resource-env-ref-name>
<resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
</resource-env-ref>-
Create a Connector Connection Pool and Connector Resource by entering the following
asadmincommands, both all in one line:
In order to configure a JMS Connection Factory using GenericJMSRA, a Connector connection pool and resource need to be created in GlassFish Server using names that map to the corresponding connection factory in the WebLogic JNDI store.
asadmin create-connector-connection-pool --host localhost --port 4848
--raname genericra --connectiondefinition javax.jms.QueueConnectionFactory
--target server --transactionsupport LocalTransaction
--property ConnectionFactoryJndiName=jms/WLOutboundQueueFactory
qcpool
asadmin create-connector-resource --host localhost --port 4848
--poolname qcpool --target server jms/QCFactory
These asadmin commands together creates a connection factory in
GlassFish Server and its corresponding connection pool.
* The connection pool has the JNDI name jms/WLoutboundQueueFactory and
obtains connections from a connection pool named qcpool.
* The connection pool qcpool uses the resource adapter genericra and
contains objects of type javax.jms.QueueConnectionFactory.
* The transactionsupport argument is set to LocalTransaction, which
specifies that the connection will be used in local transactions only.
You can also specify NoTransaction. However, the default setting of
XATransaction cannot be used. For more information, see
Limitations When Using GenericJMSRA with WebLogic JMS.
* The connection pool is configured with the properties specified using
the properties argument; multiple properties are configured as a
colon-separated list of name-value pairs. Only one property is
configured in this example, as follows:
ConnectionFactoryJndiName=jms/WLOutboundQueueFactoryThe ConnectionFactoryJndiName property must be set to the JNDI name of
the corresponding connection factory in the WebLogic JMS JNDI store.
Therefore, replace jms/WLOutboundQueueFactory in the example above
with the JNDI name used in your environment.
* For a description of the ManagedConnectionFactory properties that
are relevant for WebLogic JMS, see the Configuration
Reference of GenericJMSRA Properties for WebLogic JMS.
4. Create a destination object that refers to a corresponding WebLogic
JMS destination by entering the following asadmin command, all in one
line:
asadmin create-admin-object --host localhost --port 4848 --target server
--restype javax.jms.Queue --property DestinationJndiName=jms/WLOutboundQueue
--raname genericra jms/outboundQueueThis asadmin command creates a destination in GlassFish Server.
* The destination has the JNDI name jms/outboundQueue, uses the
resource adapter genericra, and is of type javax.jms.Queue.
* The destination is configured with the properties specified using the
properties argument; multiple properties are configured as a
colon-separated list of name-value pairs. Only one property is
configured in this example, as follows:
DestinationJndiName=jms/WLOutboundQueueThe DestinationJndiName property must be set to the JNDI name of the
corresponding destination in the WebLogic JMS JNDI store. Therefore,
replace jms/WLOutboundQueue in the example above with the JNDI name
used in your environment.
* For a description of the destination properties that are relevant for
WebLogic JMS, see the Configuration Reference of
GenericJMSRA Properties for WebLogic JMS.
Limitations When Using GenericJMSRA with WebLogic JMS
Due to the nature of the WebLogic T3 Thin Client there are a number of limitations in the way in which it can be used with GenericJMSRA.
No Support for XA Transactions
WebLogic JMS does not support the optional JMS "Chapter 8" interfaces
for XA transactions in a form suitable for use outside of WebLogic
Server. Therefore, the GenericJMSRA configuration must have the
SupportsXA property set to -false. This has a number of implications
for the way in which applications may be used, as described in this
section.
Using a MDB to Receive Messages: Container-managed Transactions (CMT)
-
If container-managed transactions are used, the transactional attribute of a MDB should be set to
NotSupported. No transaction will be started. Messages will be received in a non-transacted session with an acknowledgeMode ofAUTO_ACKNOWLEDGE. -
A transactional
Requiredattribute should not be used; otherwise, MDB activation will fail with an exception:javax.resource.ResourceException: MDB is configured to use container managed transaction. But SupportsXA is configured to false in the resource adapter.
The remaining transactional attributes are normally considered inappropriate for use with a MDB. If used, the following behavior will occur:
-
If the transactional attribute is
RequiresNew, then MDB activation will fail with an exception:javax.resource.ResourceException: MDB is configured to use container managed transaction But SupportsXA is configured to false in the resource adapter. -
If the transactional attribute is
Mandatory, the MDB can be activated but aTransactionRequiredException(or similar) will always be thrown by the server. -
If the transactional attribute is
Supports, then no transaction will be started and the MDB will work as ifNotSupportedhad been used. -
If the transactional attribute is
Never, then no transaction will be started and the MDB will work as ifNotSupportedhad been used.
Using a MDB to Receive Messages: Bean-managed Transactions (BMT)
-
If bean-managed transactions are configured in accordance with the EJB specification any
UserTransactionstarted by the bean will have no effect on the consumption of messages. -
Messages will be received in a non-transacted session with an acknowledgeMode of
AUTO_ACKNOWLEDGE.
Accessing Connections and Destinations Directly - Container-managed Transactions (CMT)
When accessing connections directly (such as when sending messages from
a MDB or an EJB) and container-managed transactions are being used, the
connection pool’s transaction-support property should be set to either
LocalTransaction or NoTransaction. If the default value of
XATransaction is used, an exception will be thrown at runtime when
createConnection() is called. This is the case irrespective of the
transactional attribute of the MDB or EJB. Note that MDBs must have
their transactional attribute set to NotSupported as specified above;
whereas, an EJB can use any transactional attribute.
If there is no transaction in progress within the bean method (for
example, notSupported is being used) then it does not make any
difference whether the connection pool’s transaction-support property
is set to LocalTransaction or NoTransaction; the transactional
behavior will be determined by the arguments to createSession(). If
you want the outbound message to be sent without a transaction, call
createSession(false, ...). If you want the outbound message to be sent
in a local transaction call
createSession(true, Session.SESSION_TRANSACTED), remembering to call
session.commit() or `session.rollback()`after the message is sent.
If there is a transaction in progress within the bean method (which will
only be possible for EJBs), then setting the connection pool’s
transaction-support property to LocalTransaction or NoTransaction
gives different results:
-
If it is set to
NoTransactionthen a non-transacted session will be used. -
If it is set to
LocalTransactionthen a (local, non-XA) transacted session will be used, which will be committed or rolled back when theUserTransactionis committed or rolled back. In this case, callingsession.commit()orsession.rollback()will cause an exception.
No Support for Redelivery Limits and Dead Message Queue
Due to the lack of XA support when using WebLogic JMS, there is no support for GenericJMSRA’s dead message queue feature, in which a message that has been redelivered to a MDB a defined number of times is sent to a dead message queue.
Limited Support for Asynchronous Receipt of Messages In a MDB
WebLogic JMS does not support the optional JMS "Chapter 8" interfaces
for "Concurrent Processing of a Subscription’s Messages" (that is,
ServerSession, ServerSessionPool and ConnectionConsumer) in a form
suitable for use outside of WebLogic Server. Therefore, the generic
JMSRA configuration must set the property DeliveryType to
Synchronous.
This affects the way in which MDBs consume messages from a queue or topic as follows:
-
When messages are being received from a queue, each MDB instance will have its own session and consumer, and it will consume messages by repeatedly calling
receive(timeout). This allows the use of a pool of MDBs to process messages from the queue. -
When messages are being received from a topic, only one MDB instance will be used irrespective of the configured pool size. This means that a pool of multiple MDBs cannot be used to share the load of processing messages, which may reduce the rate at which messages can be received and processed.
This restriction is a consequence of the semantics of synchronously consuming messages from topics in JMS: In the case of non-durable topic subscriptions, each consumer receives a copy of all the messages on the topic, so using multiple consumers would result in multiple copies of each message being received rather than allowing the load to be shared among the multiple MDBs. In the case of durable topic subscriptions, only one active consumer is allowed to exist at a time.
Configuration Reference of GenericJMSRA Properties for WebLogic JMS
The tables in this section list the properties that need to be set to configure the resource adapter and any activation specs, managed connections, and other administered objects that are relevant only when using GenericJMSRA to communicate with WebLogic JMS. For a complete list of properties, see the comprehensive table in GenericJMSRA Configuration Properties
Resource Adapter Properties
These properties are used to configure the resource adapter itself when
it is deployed, and can be specified using the
create-resource-adapter-config command.
| Property Name | Required Value | Description |
|---|---|---|
|
|
Specifies whether the JMS client supports XA transactions. Set to |
|
|
Specifies whether an MDB should use a Set to |
|
|
Specifies that connection factories and destinations in GlassFish’s JNDI store are configured to refer to connection factories and destinations in WebLogic’s JNDI store. Set to |
|
|
JNDI properties for connect to WebLogic JNDI, specified as comma-separated list of name=value pairs without spaces. |
|
|
User name to connect to
WebLogic JMS. The user name can be overridden in |
|
|
Password to connect
to WebLogic JMS. The password can be overridden in |
|
|
Used to specify the level of logging. |
Connection Factory Properties
ManagedConnectionFactory objects are created in the GlassFish Server
JNDI store using the Administration Console or the
asadmin connector-connection-pool command. All the properties that can
be set on a resource adapter configuration can be overridden by setting
them on a destination object. The properties specific to
ManagedConnectionFactory objects are listed in the following table.
| Property Name | Valid Value | Default Value | Description |
|---|---|---|---|
|
A valid client ID |
None |
|
|
A valid JNDI Name |
None |
JNDI name of connection factory in the GlassFish Server JNDI store. This connection factory should be configured to refer to the physical connection factory in the WebLogic JNDI store. |
|
|
FALSE |
If set to
|
Destination Properties
Destination (queue or topic) objects are created in the GlassFish Server
JNDI store using the Administration Console or the
asadmin connector-admin-object command. All the properties that can be
set on a resource adapter configuration can be overridden by setting
them on a destination object. The properties specific to destination
objects are listed in the following table.
| Property Name | Valid Value | Default Value | Description |
|---|---|---|---|
|
A valid JNDI name |
None |
JNDI name of the destination object in the GlassFish Server JNDI store. This destination object should be configured to refer to the corresponding physical destination in the WebLogic JNDI store. |
ActivationSpec Properties
An ActivationSpec is a set of properties that configures a MDB. It is
defined either in the MDB’s GlassFish Server deployment descriptor
glassfish-ejb-jar.xml using activation-config-property elements or
in the MDB itself using annotation. All the resource adapter properties
listed in the table above can be overridden in an ActivationSpec.
Additional properties available only to a ActivationSpec are given
below.
| Property Name | Valid Value | Default Value | Description |
|---|---|---|---|
|
An integer |
8 |
Maximum size of server session pool internally created by the resource adapter for achieving concurrent message delivery. This should be equal to the maximum pool size of MDB objects. Only used for queues; ignored for topics, when a value of 1 is always used. |
|
|
|
Only used for topics. Specifies whether the subscription is durable or non-durable. |
|
+ |
None |
Only used for topics when
|
|
A valid message selector |
None |
JMS message selector. |
|
A valid client ID |
None |
JMS ClientID. |
|
A valid JNDI Name |
None |
JNDI name of connection factory in the GlassFish Server JNDI store. This connection factory should be configured to refer to the physical connection factory in the WebLogic JNDI store. |
|
A valid JNDI Name |
None |
JNDI name of destination in the GlassFish Server JNDI store. This destination should be configured to refer to the physical destination in the WebLogic JNDI store. |
|
|
Null |
Specifies whether the configured |
|
integer |
0 |
Number of times a reconnect will be attempted in case exception listener catches an error on connection. |
|
time in seconds |
0 |
Interval between reconnection attempts. |
Using GenericJMSRA with IBM WebSphere MQ
You can configure GenericJMSRA to enable applications running in GlassFish Server to send messages to, and receive messages from, IBM WebSphere MQ. GlassFish Serveronly supports using GenericJMSRA with WebSphere MQ version 6.0 and WebSphere MQ version 7.0
These instructions assume that the WebSphere MQ broker and GlassFish Server are deployed and running on the same physical host/machine. If you have the WebSphere MQ broker running on a different machine and need to access it remotely, refer to the WebSphere MQ documentation for configuration details. The resource adapter configuration and other application server related configuration remains unchanged.
The following topics are addressed here:
Preliminary Setup Procedures for WebSphere MQ Integration
Before you can configure WebSphere MQ to exchange messages with GlassFish Server, you must complete the following tasks:
-
The following permissions must be added to the
server.policyand theclient.policyfile to deploy GenericJMSRA and to run the client application.-
Use a text editor to modify the
server.policyfile in the `${appserver-install-dir}/domains/domain1/config/`directory by adding the following line to the default grant block:
-
permission java.util.logging.LoggingPermission "control"; permission java.util.PropertyPermission "*", "read,write";
-
If you use an application client in your application, edit the client’s
client.policyfile in the${appserver-install-dir}/lib/appclient/directory by adding the following permission:
permission javax.security.auth.PrivateCredentialPermission "javax.resource.spi.security.PasswordCredential * \"*\"","read";
-
To integrate GlassFish Serverwith WebSphere MQ 6.0 or 7.0, copy the necessary JAR files to the as-install`/lib` directory:
-
For WebSphere MQ 6.0, copy these JAR files to the as-install`/lib` directory:
-
/opt/mqm/java/lib/com.ibm.mq.jar /opt/mqm/java/lib/com.ibm.mq.jms.Nojndi.jar /opt/mqm/java/lib/com.ibm.mq.soap.jar /opt/mqm/java/lib/com.ibm.mqjms.jar /opt/mqm/java/lib/com.ibm.mqetclient.jar /opt/mqm/java/lib/commonservices.jar /opt/mqm/java/lib/dhbcore.jar /opt/mqm/java/lib/rmm.jar /opt/mqm/java/lib/providerutil.jar /opt/mqm/java/lib/CL3Export.jar /opt/mqm/java/lib/CL3Nonexport.jar
where /opt/mqm is the location of the WebSphere MQ 6.0 installation.
-
For WebSphere MQ 7.0, copy these JAR files to the as-install`/lib` directory:
/opt/mqm/java/lib/com.ibm.mq.jar, /opt/mqm/java/lib/com.ibm.mq.jms.Nojndi.jar, /opt/mqm/java/lib/com.ibm.mq.soap.jar, /opt/mqm/java/lib/com.ibm.mqjms.jar, /opt/mqm/java/lib/com.ibm.mq.jmqi.jar, /opt/mqm/java/lib/com.ibm.mq.commonservices.jar, /opt/mqm/java/lib/dhbcore.jar, /opt/mqm/java/lib/rmm.jar, /opt/mqm/java/lib/providerutil.jar, /opt/mqm/java/lib/CL3Export.jar, /opt/mqm/java/lib/CL3Nonexport.jar
where /opt/mqm is the location of the WebSphere MQ 7.0 installation.
* Set the LD_LIBRARY_PATH environment variable to the java/lib
directory, and then restart GlassFish Server. For example, in a
UNIX—based system, with WebSphere MQ installed under /opt/mqm, you
would enter:
$ export LD_LIBRARY_PATH=/opt/mqm/java/libConfigure the WebSphere MQ Administered Objects
This section provides an example of how you could configure the necessary administered objects, such as destinations and connection factories, on the WebSphere MQ instance from which you want to access messages using GlassFish Server. Therefore, you will need to change the administered object names to suit your installation.
Before You Begin
If WebSphere MQ created a user and a group named mqm during the
installation, then you must specify a password for the mqm user using
the $ passwd mqm command.
-
Switch to the
mqmuser:
$ su mqm -
For Linux, set the following kernel version:
$ export LD_ASSUME_KERNEL=2.2.5 -
Create a new MQ queue manager named "QM1":
$ crtmqm QM1 -
Start the new MQ queue manager.
In the image above,QM1is associated with the IBM WebSphere MQ broker.
$ strmqm QM1 -
Start the MQ listener:
$ runmqlsr -t tcp -m QM1 -p 1414 & -
Modify the default JMSAdmin console configuration as follows:
-
Edit the JMSAdmin script in the
/opt/mqm/java/bindirectory to change the JVM to a location of a valid JVM your system. -
Set the relevant environment variable required for JMSAdmin by sourcing the
setjmsenvscript located in the/opt/mqm/java/bindirectory.
$ cd /opt/mqm/java/bin $ source setjmsenv
where /opt/mqm is the location of the WebSphere MQ installation.
3. Change the JMSAdmin.config file to indicate the Initial Context
Factory you will be using by setting the following name-value pairs and
commenting out the rest:
INITIAL_CONTEXT_FACTORY=com.sun.jndi.fscontext.RefFSContextFactory
PROVIDER_URL=file:/opt/tmp-
Create WebSphere MQ queues using the runmqsc console and MQJMS_PSQ.mqsc script.
$ runmqsc QM1 < MQJMS_PSQ.mqsc -
Create user defined physical queue for your application using runmqsc console and an appropriate physical queue name. An example of how this could be done is shown below.
In the image above,ORANGE.LOCAL.QUEUEis associated withQM1.
$ runmqsc QM1
> DEFINE QLOCAL(ORANGE.LOCAL.QUEUE)
> end
-
Start the WebSphere MQ Broker:
$ strmqbrk -m QM1 -
In the WebSphere MQ JMSAdmin console, use the following commands to create the connection factories, XA connection factories, and destinations for your application, as shown in the following sample, which lists each of the various JMS administered objects.
In the image above,QCF(forQM1) andTQueue(associated withORANGE.LOCAL.QUEUE) are defined in theFileSystem Naming Context.
$ ./JMSAdmin
InitCtx>def qcf<JNDI name to be given to the Queue Connection Factory>
hostname<IBM MQ server hostname> port(1414) channel(SYSTEM.DEF.SVRCONN)
transport(CLIENT) qmanager<name of queue manager defined>
For example:
def qcf(QCF) hostname(localhost) port(1414) channel(SYSTEM.DEF.SVRCONN)
transport(CLIENT) qmanager(QM1)
InitCtx%def xaqcf<JNDI name to be given to the XA Queue Connection Factory>
hostname<IBM MQ server hostname> port(1414) channel(SYSTEM.DEF.SVRCONN)
transport(CLIENT) qmanager<name of queue manager defined>
For example:
def xaqcf(XAQCF) hostname(localhost) port(1414) channel(SYSTEM.DEF.SVRCONN)
transport(CLIENT) qmanager(QM1)
InitCtx%def q<JNDI Name to be given to the Queue> queue<physical queue name>
qmanager(name of queue manager defined )
For example: def q(TQueue) queue(ORANGE.LOCAL.QUEUE) qmanager(QM1)
InitCtx%def tcf<JNDI Name to be given to the Topic Connection Factory>
qmanager(name of queue manager defined )
For example: def tcf(TCF) qmanager(QM1)
InitCtx%def xatcf<JNDI Name to be given to the XA Topic Connection Factory>
qmanager(name of queue manager defined )
For example: def xatcf(XATCF) qmanager(QM1)
InitCtx%def t<JNDI Name to be given to the Topic> topic<sample topic name>
For example: def t(TTopic) topic(topic)
Create a Resource Adapter Configuration for GenericJMSRA to Work With WebSphere MQ
Before deploying GenericJMSRA, you need to create a resource adapter
configuration in GlassFish Server. You can do this using either the
Administration Console or the asadmin command. Use the following
asadmin command to create a resource adapter configuration for
genericra to configure it to work with WebSphere MQ.
asadmin> create-resource-adapter-config
--user <adminname> --password <admin password>
--property SupportsXA=true:ProviderIntegrationMode
=jndi:UserName=mqm:Password=###:RMPolicy
=OnePerPhysicalConnection:JndiProperties
=java.naming.factory.url.pkgs\\
=com.ibm.mq.jms.naming,java.naming.factory.initial\\
=com.sun.jndi.fscontext.RefFSContextFactory,java.naming.provider.url\\
=file\\:\\/\\/opt\\/tmp:LogLevel=finest genericra|
Note
|
When using |
This creates a resource adapter configuration with the name genericra,
and Oracle recommends not changing the default name. The resource
adapter configuration is configured with the properties specified using
the --properties argument; multiple properties are configured as a
colon-separated list of name-value pairs that are entered as a single
line.
In this example, the following properties are configured:
|
Note
|
The tables in this section describe the GenericJMSRA properties that are relevant only when integrating with WebSphere MQ. For a complete list of properties, see the comprehensive table in GenericJMSRA Configuration Properties. |
| Property Name | Required Value | Description |
|---|---|---|
|
|
Set the supports distributed transactions
attribute to |
|
|
Specifies that connection factories and destinations in GlassFish’s JNDI store are configured to refer to connection factories and destinations in WebSphere MQ’s JNDI store. |
|
|
JNDI properties for connecting to WebSphere MQ’s JNDI, specified as comma-separated list of name=value pairs without spaces. |
|
|
User name to connect to WebSphere MQ. The user name can be overridden in |
|
|
Password to connect to WebSphere MQ. The password can be overridden in |
|
|
Some XAResource implementations, such as WebSphere MQ, rely on a Resource Manager per Physical Connection, and this causes issues when there is inbound and outbound communication to the same queue manager in a single transaction (for example, when an MDB sends a response to a destination). When RMPolicy is set to |
|
|
Used to specify the level of logging. |
|
Note
|
You must use the values for |
Deploy the GenericJMSRA Archive
For instructions on downloading and deploying GenericJMSRA, see Deploy the GenericJMSRA Resource Archive.
Create the Connection Factories and Administered Objects in GlassFish Server
In order to configure a JMS Connection Factory using GenericJMSRA, a Connector Connection Pool and resource needs to be created in GlassFish Server, as described in this section.
Using the example WebSphere MQ configuration in Configure
the WebSphere MQ Administered Objects, you will see mypool (pointing
to GenericJMSRA and QCF) and jms/MyQCF (for mypool) created in
GlassFish Server.
|
Note
|
If you want configure connections and destination resources using the
Administration Console, this is explained in the Administration Console
online help. When using Administration Console, following the,
instructions for creating a new Connector Connection Pool and Admin
Object Resources, and not the instructions for creating a JMS Connection
Pool and Destination Resources. For more information about using
|
Creating Connections and Destinations
In order to configure a JMS Connection Factory, using GenericJMSRA, a Connector Connection Pool and Destination resources need to be created in GlassFish Server using names that map to the corresponding connection and destination resources in WebSphere MQ. The connections and destination name in these steps map to the example WebSphere MQ configuration in Configure the WebSphere MQ Administered Objects.
-
Create connection pools that point to the connection pools in WebSphere MQ.
The followingasadmincommand creates a Connection Pool calledmypooland points to theXAQCFcreated in WebSphere MQ:
asadmin create-connector-connection-pool -- raname genericra connectiondefinition
javax.jms.QueueConnectionFactory --transactionsupport XATransaction
--property ConnectionFactoryJndiName=QCF mypool
The following asadmin command creates a Connection Pool called
mypool2 and points to the XATCF created in WebSphere MQ:
asadmin create-connector-connection-pool
-- raname genericra connectiondefinition javax.jms.TopicConnectionFactory
--transactionsupport XATransaction
--property ConnectionFactoryJndiName=XATCF mypool2-
Create the connector resources.
The followingasadmincommand creates a connector resource namedjms/MyQCFand binds this resource to JNDI for applications to use:
asadmin create-connector-resource --poolname mypool jms/MyQCF
The following asadmin command creates a connector resource named
jms/MyTCF and binds this resource to JNDI for applications to use:
asadmin create-connector-resource --poolname mypool2 jms/MyTCF-
Create the JMS destination resources as administered objects.
In the image above,jms/MyQueue(pointing toGenericJMSRAandTQueue) is created in GlassFish Server.
The followingasadmincommand creates ajavax.jms.Queueadministered object and binds it to the GlassFish Server JNDI tree atjms/MyQueueand points to thejms/TQueuecreated in WebSphere MQ.
asadmin create-admin-object --raname genericra --restype javax.jms.Queue
--property DestinationJndiName=TQueue jms/MyQueue
The following asadmin command creates a javax.jms.Topic administered
object and binds it to the GlassFish Server JNDI tree at jms/MyTopic
and points to the jms/TTopic created in WebSphere MQ.
asadmin create-admin-object --raname genericra --restype javax.jms.Topic
--property DestinationJndiName=TTopic jms/MyTopicConfiguring an MDB to Receive Messages from WebSphere MQ
The administered object names in the sample deployment descriptor below
map to the example WebSphere MQ configuration in Configure
the WebSphere MQ Administered Objects. The deployment descriptors need
to take into account the resource adapter and the connection resources
that have been created. A sample sun-ejb-jar.xml for a Message Driven
Bean that listens to a destination called TQueue in WebSphere MQ, and
publishes back reply messages to a destination resource named
jms/replyQueue in GlassFish Server, as shown below.
<sun-ejb-jar>
<enterprise-beans>
<unique-id.1</unique-id>
<ejb>
<ejb-name>SimpleMessageEJB</ejb-name>
<jndi-name>jms/SampleQueue</jndi-name>
<!-- QCF used to publish reply messages -->
<resource-ref>
<res-ref-name>jms/MyQueueConnectionFactory</res-ref-name>
<jndi-name>jms/MyQCF</jndi-name>
<default-resource-principal>
<name>mqm</name>
<password>mqm</password>
</default-resource-principal>
</resource-ref>
<!-- reply destination resource> Creating of this replyQueue destination resource is not
shown above, but the steps are similar to creating the "jms/MyQueue" resource -->
<resource-env-ref>
<resource-env-ref-name>jms/replyQueue</resource-env-ref-name>
<jndi-name>jms/replyQueue</jndi-name>
</resource-env-ref>
<!-- Activation related RA specific configuration for this MDB -->
<mdb-resource-adapter>
<!-- resource-adapter-mid points to the Generic Resource Adapter for JMS -->
<resource-adapter-mid>genericra</resource-adapter-mid>
<activation-config>
<activation-config-property>
<activation-config-property-name>DestinationType</activation-config-property-name>
<activation-config-property-value>javax>jms>Queue</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>ConnectionFactoryJndiName</activation-config-property-name>
<activation-config-property-value>QCF</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>DestinationJndiName</activation-config-property-name>
<activation-config-property-value>TQueue</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>MaxPoolSize</activation-config-property-name>
<activation-config-property-value>32</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>RedeliveryAttempts</activation-config-property-name>
<activation-config-property-value>0</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>ReconnectAttempts</activation-config-property-name>
<activation-config-property-value>4</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>ReconnectInterval</activation-config-property-name>
<activation-config-property-value>10</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>RedeliveryInterval</activation-config-property-name>
<activation-config-property-value>1</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>SendBadMessagesToDMD</activation-config-property-name>
<activation-config-property-value>false</activation-config-property-value>
</activation-config-property>
</activation-config>
</mdb-resource-adapter>
</ejb>
</enterprise-beans>
</sun-ejb-jar>The business logic encoded in Message Driven Bean could then lookup the
configured QueueConnectionFactory/Destination resource to create a
connection as shown below.
Context context = null;
ConnectionFactory connectionFactory = null;
logger>info("In PublisherBean>ejbCreate()");
try {
context = new InitialContext();
queue = (javax>jms>Queue) context>lookup ("java:comp/env/jms/replyQueue");
connectionFactory = (ConnectionFactory) context>lookup("java:comp/env/jms/MyQueueConnectionFactory");
connection = connectionFactory>createConnection();
} catch (Throwable t) {
logger>severe("PublisherBean>ejbCreate:" + "Exception: " +
t>toString());
}