Administering the Java Message Service (JMS)

17 Administering the Java Message Service (JMS)

The Java Message Service (JMS) API is a messaging standard that allows Jakarta 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.

Eclipse GlassFish supports JMS messaging by communicating with a JMS provider through a Jakarta EE Connector resource adapter. By default, Eclipse GlassFish provides JMS messaging through its built-in jmsra resource adapter communicating with Open Message Queue, which is included with Eclipse GlassFish. This combination, known as the JMS Service, is tightly integrated with Eclipse GlassFish, providing a rich set of asadmin subcommands and Administration Console pages to simplify JMS messaging administration tasks.

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

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 Eclipse GlassFish 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 Eclipse GlassFish 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:

set configs.config.config-name.jms-service.attribute-name=attribute-value

The attributes you can set are:

type

The JMS host type the service is to use. Available choices are EMBEDDED, LOCAL and REMOTE. See About JMS Host Types for more information.

init-timeout-in-seconds

The number of seconds Eclipse GlassFish 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 imqbrokerd command, 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 random to 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-scheme
mq-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.

After making changes to the JMS service configuration, Eclipse GlassFish 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=value

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

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 Eclipse GlassFish. 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 Eclipse GlassFish High Availability Administration Guide.

About JMS Host Types

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

Embedded Type

When the JMS service configuration’s type attribute is EMBEDDED, the MQ broker is co-located in the same JVM as the Eclipse GlassFish instance it services. The JMS service starts it in-process and manages its configuration and lifecycle.
For this type, the JMS service uses lazy initialization to start the broker when the first JMS operation is requested instead of immediately when the GlassFish instance is started. If necessary, you can force startup of the broker by using the jms-ping command.
Additionally, if the GlassFish instance is a standalone instance (not a clustered instance), JMS operations use a Message Queue feature called direct mode to bypass the networking stack, leading to performance optimization.

Local Type

When the JMS service configuration’s type attribute is LOCAL, the JMS service starts the MQ broker specified in the configuration as the default JMS host in a separate process on the same host as the Eclipse GlassFish instance. The JMS service manages its configuration and lifecycle.
For this type, the JMS service starts the broker immediately when the GlassFish instance is started.
The JMS service provides the Message Queue broker an additional port to start the RMI registry. This port number is equal to the broker’s JMS port plus 100. For example, if the JMS port number is 37676, then the additional port’s number will be 37776. Additionally, the start-args property of the JMS service configuration can be used to specify Message Queue broker startup options.

Remote Type

When the JMS service configuration’s type attribute is REMOTE, the JMS service uses the information defined by the default JMS host to communicate with an MQ broker or broker cluster that has been configured and started using Message Queue tools, as described in the 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), the IMQ_VARHOME location is:

    domain-root-dir/domain-dir/imq

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

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

For example, the broker log file for an Embedded or Local JMS host servicing the DAS is available at domain-root-dir/domain-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``.

When using Message Queue utilities on the Windows platform, you must explicitly use the Windows executable (.exe) versions of the utilities, even when running command shells such as Cygwin. For example, instead of running imqcmd, you must run imqcmd.exe.

To Create a JMS Host

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

  1. Ensure that the server is running.

    Remote asadmin subcommands require a running server.

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

    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 Eclipse GlassFish object for which the JMS host is being created. For details, see create-jms-host(1).

    --property

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

    prop1Name=prop1Value:prop2Name=prop2Value:...

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

    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.

  1. Ensure that the server is running.

    Remote asadmin subcommands require a running server.

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

Example 17-2 Listing JMS Hosts

The following subcommand lists the existing JMS hosts.

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

To Update a JMS Host

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

  1. Ensure that the server is running.

    Remote asadmin subcommands require a running server.

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

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

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

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

    asadmin> set configs.config.config-name.jms-service.jmshost.
jms-host-name.attribute-name=attribute-value
    The attributes you can set are
    host

    The host name of the Message Queue broker.

    port

    The port number of the Message Queue broker.

    admin-user-name

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

    admin-password

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

    `property.`broker-property-name

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

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

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

Example 17-3 Updating a JMS Host

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

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

To Delete a JMS Host

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

  1. Ensure that the server is running.

    Remote asadmin subcommands require a running server.

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

  3. Delete a JMS host by using the delete-jms-host subcommand.

Example 17-4 Deleting a JMS Host

This example deletes a JMS host named MyNewHost.

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

See Also

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

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 Eclipse GlassFish, 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 Jakarta EE standard specifies that certain default resources be made available to applications, and defines specific JNDI names for these default resources. Eclipse GlassFish makes these names available through the use of logical JNDI names, which map Jakarta EE standard JNDI names to specific Eclipse GlassFish resources. For JMS connection factory resources, the Jakarta EE standard name java:comp/DefaultJMSConnectionFactory is mapped to the jms/__defaultConnectionFactory resource.

Eclipse GlassFish 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)

Eclipse GlassFish 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 information on JMS service support of connection pooling and failover, see "Connection Failover" in Eclipse GlassFish 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, Eclipse GlassFish creates a connector connection pool and connector resource. For each JMS destination that you create, Eclipse GlassFish creates a connector admin object resource. If you delete a JMS resource, Eclipse GlassFish 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.

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

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

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

  1. Ensure that the server is running.

    Remote asadmin subcommands require a running server.

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

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

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

  1. Ensure that the server is running.

    Remote asadmin subcommands require a running server.

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

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 successfully

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

  1. Ensure that the server is running.

    Remote asadmin subcommands require a running server.

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

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

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 successfully

See Also

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

Administering JMS 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, Eclipse GlassFish 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.

  1. Ensure that the server is running.

    Remote asadmin subcommands require a running server.

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

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

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

  1. Ensure that the server is running.

    Remote asadmin subcommands require a running server.

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

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.

  1. Ensure that the server is running.

    Remote asadmin subcommands require a running server.

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

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

See Also

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

To Delete a JMS Physical Destination

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

  1. Ensure that the server is running.

    Remote asadmin subcommands require a running server.

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

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

Example 17-13 Deleting a Physical Destination

This example deletes the queue named PhysicalQueue.

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

See Also

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

Special Situations When Using the JMS Service

As mentioned earlier, Message Queue, through the built-in jmsra resource adapter, is tightly integrated with Eclipse GlassFish 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 imqbrokerd Message 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 admin user password for an Embedded or Local broker:

  1. Make sure the broker is running.

  2. Use the imqusermgr Message Queue utility to change the password of the admin user.

  3. Edit the configuration of the JMS host, changing the password of the admin user to the new password.

  4. 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.socketfactory Message Queue broker property to com.sun.enterprise.security.auth.realm.ldap.CustomSocketFactory.

Troubleshooting the JMS Service

If you encounter problems, consider the following:

  • Use the jms-ping subcommand to confirm that the Message Queue broker is running.

  • View the Eclipse GlassFish 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 Eclipse GlassFish instances.

  • If all Message Queue brokers are down, it can take up to 30 minutes for Eclipse GlassFish 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

Eclipse GlassFish 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 Jakarta 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 Eclipse GlassFish 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 a ConnectionConsumer or Consumer.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 Eclipse GlassFish. For some JMS providers, client libraries might also include native libraries. In such cases, these native libraries must be made available to any Eclipse GlassFish JVMs.

  1. Download the genericra.rar archive.

  2. Deploy GenericJMSRA the same way you would deploy a connector module.

    See "Deploying a Connector Module" in Eclipse GlassFish Application Deployment Guide.

  3. Configure the resource adapter’s properties.

    See GenericJMSRA Configuration Properties.

  4. Create a connector connection pool.

    See To Create a Connector Connection Pool.

  5. Create a connector resource.

    See To Create a Connector Resource.

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

SupportsXA

true/false

false

Specifies whether the JMS client supports XA transactions.

DeliveryType

Synchronous/

Asynchronous

Asynchronous

Specifies whether an MDB should use a ConnectionConsumer (Asynchronous) or consumer.receive() (Synchronous) when consuming messages.

QueueConnectionFactoryClassName

A valid class name

None

Class name of jakarta.jms.QueueConnectionFactory implementation of the JMS client. This class must be made available on the application server classpath. Used if ProviderIntegrationMode is javabean.

TopicConnectionFactoryClassName

A valid class name

None

Class name of jakarta.jms.TopicConnectionFactory implementation of the JMS client. This class must be made available on the application server classpath. Used if ProviderIntegrationMode is specified as javabean.

XAConnectionFactoryClassName

A valid class name

None

Class name of jakarta.jms.ConnectionFactory implementation of the JMS client. This class must be made available on the application server classpath. Used if ProviderIntegrationMode is specified as javabean.

XAQueueConnectionFactoryClassName

A valid class name

None

Class name of jakarta.jms.``XAQueueConnectionFactory implementation of the JMS client. This class must be made available on the application server classpath. Used if ProviderIntegrationMode is specified as javabean.

XATopicConnectionFactoryClassName

A valid class name

None

Class name of jakarta.jms.``XATopicConnectionFactory implementation of the JMS client. This class must be made available on the application server classpath. Used if ProviderIntegrationMode is javabean.

TopicClassName

A valid class name

None

Class Name of jakarta.jms.Topic implementation of the JMS client. This class must be made available on the application server classpath. Used if ProviderIntegrationMode is javabean.

QueueClassName

A valid class name

None

Class Name of jakarta.jms.Queue implementation of the JMS client. This class must be made available on the application server classpath. Used if ProviderIntegrationMode is specified as a javabean.

ConnectionFactoryProperties

Name value pairs separated by comma

None

Specifies the javabean property names and values of the ConnectionFactory of the JMS client. Required only if ProviderIntegrationMode is javabean.

JndiProperties

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 ProviderIntegrationMode is jndi.

CommonSetterMethodName

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 ProviderIntegrationMode is javabean. For example, in the case of Message Queue, this would be setProperty.

UserName

Name of the JMS user

None

User name to connect to the JMS Provider.

Password

Password for the JMS user

None

Password to connect to the JMS provider.

RMPolicy

ProviderManaged or OnePerPhysicalConnection

Provider``Managed

The isSameRM method on an XAResource is used by the Transaction Manager to determine if the Resource Manager instance represented by two XAResources are the same. When RMPolicy is set to ProviderManaged (the default value), the JMS provider is responsible for determining the RMPolicy and the XAResource wrappers in GenericJMSRA merely delegate the isSameRM call to the JMS provider’s XA resource implementations. This should ideally work for most JMS providers.

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 OnePerPhysicalConnection, the XAResource wrapper implementation’s isSameRM in GenericJMSRA would check if both the XAResources use the same physical connection, before delegating to the wrapped objects.
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

ClientId

A valid client ID

None

ClientID as specified by JMS 1.1 specification.

ConnectionFactoryJndiName

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 clientID) in the JMS provider itself. This property name will be used only if ProviderIntegratinMode is jndi.

ConnectionValidationEnabled

true/false

false

If set to true, the resource adapter will use an exception listener to catch any connection exception and will send a CONNECTION_ERROR_OCCURED event to application server.
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

DestinationJndiName

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 ProviderIntegrationMode is jndi.

DestinationProperties

Name value pairs separated by a comma

None

Specifies the javabean property names and values of the destination of the JMS client. Required only if ProviderIntegrationMode is javabean.
Activation Spec Properties

Properties in this section are specified in the Eclipse GlassFish 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

MaxPoolSize

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.

MaxWaitTime

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.

SubscriptionDurability

Durable or Non-Durable

Non-Durable

SubscriptionDurability as specified by JMS 1.1 specification.

SubscriptionName

+

None

SubscriptionName as specified by JMS 1.1 specification.

MessageSelector

A valid message selector

None

MessageSelector as specified by JMS 1.1 specification.

ClientID

A valid client ID

None

ClientID as specified by JMS 1.1 specification.

ConnectionFactoryJndiName

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 ProviderIntegrationMode is configured as jndi.

DestinationJndiName

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 ProviderIntegrationMode is configured as jndi.

DestinationType

jakarta.jms.Queue or jakarta.jms.Topic

Null

Type of the destination the MDB will listen to.

DestinationProperties

Name-value pairs separated by comma

None

Specifies the javabean property names and values of the destination of the JMS client. Required only if ProviderIntegrationMode is javabean.

RedeliveryAttempts

integer

+

Number of times a message will be delivered if a message causes a runtime exception in the MDB.

Redelivery``Interval

time in seconds

+

Interval between repeated deliveries, if a message causes a runtime exception in the MDB.

SendBadMessagesToDMD

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.

DeadMessageDestinationJndiName

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 ProviderIntegrationMode is jndi.

DeadMessageDestinationClassName

class name of destination object.

None

Used if ProviderIntegrationMode is javabean.

DeadMessageDestinationProperties

Name Value Pairs separated by comma

None

Specifies the javabean property names and values of the destination of the JMS client. This is required only if ProviderIntegrationMode is javabean.

DeadMessageConnectionFactoryJndiName

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 ProviderIntegrationMode is jndi.

DeadMessageDestinationType

queue or topic destination

None

The destination type for dead messages.

ReconnectAttempts

integer

0

Number of times a reconnect will be attempted in case exception listener catches an error on connection.

ReconnectInterval

time in seconds

0

Interval between reconnects.

Using GenericJMSRA with WebLogic JMS

You can configure GenericJMSRA to enable applications running in Eclipse GlassFish 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 Eclipse GlassFish 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 Eclipse GlassFish

WebLogic Server provides several different clients for use by standalone applications that run outside of WebLogic Server. These client are summarized in "Overview of Stand-alone Clients" in Programming Stand-alone Clients for Oracle WebLogic Server. When connecting from Eclipse GlassFish 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 Eclipse GlassFish and make it available to GenericJMSRA:

  • To make the Thin T3 client available to all applications, copy the wlthint3client.jar to the as-install/lib directory under your Eclipse GlassFish 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 Eclipse GlassFish 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 Eclipse GlassFish, 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 "Understanding JMS Resource Configuration" in Configuring and Managing JMS for Oracle WebLogic Server. For detailed instructions on configuring WebLogic JMS resources, refer to "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 Eclipse GlassFish. 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 genericra

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

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

(replace "localhost:7001" with the host:port of WebLogic Server)

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.

When using asadmin you need to escape each = and any : characters by prepending a backward slash \. The escape sequence is not necessary if the configuration is performed through the Administration Console.

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

  1. Download the GenericJMSRA resource archive (genericra.rar).

  2. Deploy the resource adapter. You can do this using either the Administration Console or the asadmin deploy command. Here’s an example using the asadmin deploy 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 Eclipse GlassFish glassfish-ejb-jar.xml file. To configure a MDB to receive messages from WebLogic JMS, you would configure these deployment descriptor files as follows:

  1. 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>jakarta.jms.Message</method-param>
        </method-params>
      </method>
      <trans-attribute>NotSupported</trans-attribute>
    </container-transaction>
  </assembly-descriptor>
</ejb-jar>

    If container-managed transactions are configured, then the transactional attribute must be set to NotSupported. For more information, see Limitations When Using GenericJMSRA with WebLogic JMS.

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

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 asadmin to create these resources, see To Create a Connector Connection Pool and To Create a Connector Resource.

  1. Looking up the connection factory and destination

    The following code looks up a connection factory with the JNDI name jms/QCFactory and a queue with the name jms/outboundQueue from the Eclipse GlassFish 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 Eclipse GlassFish 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 Eclipse GlassFish JNDI store and configure the Eclipse GlassFish object to point to the corresponding WebLogic JMS object.

  2. Declaring the connection factory and destination

    In accordance with standard Jakarta 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>jakarta.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>jakarta.jms.Queue</resource-env-ref-type>
      </resource-env-ref>

  3. Create a Connector Connection Pool and Connector Resource by entering the following asadmin commands, 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 Eclipse GlassFish 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 jakarta.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 Eclipse GlassFish 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 jakarta.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/WLOutboundQueueFactory

      The 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 jakarta.jms.Queue --property DestinationJndiName=jms/WLOutboundQueue
    --raname genericra jms/outboundQueue

    This asadmin command creates a destination in Eclipse GlassFish.

    • The destination has the JNDI name jms/outboundQueue, uses the resource adapter genericra, and is of type jakarta.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/WLOutboundQueue

      The 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 of AUTO_ACKNOWLEDGE.

  • A transactional Required attribute 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 a TransactionRequiredException (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 if NotSupported had been used.

  • If the transactional attribute is Never, then no transaction will be started and the MDB will work as if NotSupported had 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 UserTransaction started 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 NoTransaction then a non-transacted session will be used.

  • If it is set to LocalTransaction then a (local, non-XA) transacted session will be used, which will be committed or rolled back when the UserTransaction is committed or rolled back. In this case, calling session.commit() or session.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

SupportsXA

false

Specifies whether the JMS client supports XA transactions.

Set to false for WebLogic JMS.

DeliveryType

Synchronous

Specifies whether an MDB should use a ConnectionConsumer (Asynchronous) or consumer.receive() (Synchronous) when consuming messages.

Set to Synchronous for WebLogic JMS.

ProviderIntegrationMode

jndi

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 for WebLogic JMS.

JndiProperties

 
java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory,
java.naming.provider.url=t3://localhost:7001,
java.naming.factory.url.pkgs=weblogic.corba.client.naming
(replace localhost:7001 with the host:port of WebLogic Server)

JNDI properties for connect to WebLogic JNDI, specified as comma-separated list of name=value pairs without spaces.

UserName

Name of the WebLogic JMS user

User name to connect to WebLogic JMS. The user name can be overridden in ActivationSpec and ManagedConnection. If no user name is specified anonymous connections will be used, if permitted.

Password

Password for the WebLogic JMS user

Password to connect to WebLogic JMS. The password can be overridden in ActivationSpec and ManagedConnection.

LogLevel

Desired log level of JDK logger

Used to specify the level of logging.

Connection Factory Properties

ManagedConnectionFactory objects are created in the Eclipse GlassFish 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

ClientId

A valid client ID

None

ClientID as specified by JMS 1.1 specification.

ConnectionFactoryJndiName

A valid JNDI Name

None

JNDI name of connection factory in the Eclipse GlassFish JNDI store. This connection factory should be configured to refer to the physical connection factory in the WebLogic JNDI store.

ConnectionValidationEnabled

true or false

FALSE

If set to true, the resource adapter will use an exception listener to catch any connection exception and will send a CONNECTION_ERROR_OCCURED event to Eclipse GlassFish.

Destination Properties

Destination (queue or topic) objects are created in the Eclipse GlassFish 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

DestinationJndiName

A valid JNDI name

None

JNDI name of the destination object in the Eclipse GlassFish 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 Eclipse GlassFish 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

MaxPoolSize

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.

SubscriptionDurability

Durable or Non-Durable

Non-Durable

Only used for topics. Specifies whether the subscription is durable or non-durable.

SubscriptionName

None

Only used for topics when SubscriptionDurability is Durable. Specifies the name of the durable subscription.

MessageSelector

A valid message selector

None

JMS message selector.

ClientID

A valid client ID

None

JMS ClientID.

ConnectionFactoryJndiName

A valid JNDI Name

None

JNDI name of connection factory in the Eclipse GlassFish JNDI store. This connection factory should be configured to refer to the physical connection factory in the WebLogic JNDI store.

DestinationJndiName

A valid JNDI Name

None

JNDI name of destination in the Eclipse GlassFish JNDI store. This destination should be configured to refer to the physical destination in the WebLogic JNDI store.

DestinationType

jakarta.jms.Queue or jakarta.jms.Topic

Null

Specifies whether the configured DestinationJndiName refers to a queue or topic.

ReconnectAttempts

integer

0

Number of times a reconnect will be attempted in case exception listener catches an error on connection.

ReconnectInterval

time in seconds

0

Interval between reconnection attempts.

Using GenericJMSRA with IBM WebSphere MQ

You can configure GenericJMSRA to enable applications running in Eclipse GlassFish to send messages to, and receive messages from, IBM WebSphere MQ. Eclipse GlassFishonly supports using GenericJMSRA with WebSphere MQ version 6.0 and WebSphere MQ version 7.0

These instructions assume that the WebSphere MQ broker and Eclipse GlassFish 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 Eclipse GlassFish, you must complete the following tasks:

  • The following permissions must be added to the server.policy and the client.policy file to deploy GenericJMSRA and to run the client application.

    • Use a text editor to modify the server.policy file 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.policy file 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 Eclipse GlassFishwith 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 Eclipse GlassFish. For example, in a UNIX—based system, with WebSphere MQ installed under /opt/mqm, you would enter:

    $ export LD_LIBRARY_PATH=/opt/mqm/java/lib
Configure 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 Eclipse GlassFish. 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.

image::websphere-mq.png[ "This graphic represents all of the administered objects created in this example configuration."]

  1. Switch to the mqm user:
    $ su mqm

  2. For Linux, set the following kernel version:
    $ export LD_ASSUME_KERNEL=2.2.5

  3. Create a new MQ queue manager named "QM1":
    $ crtmqm QM1

  4. Start the new MQ queue manager.
    In the image above, QM1 is associated with the IBM WebSphere MQ broker.
    $ strmqm QM1

  5. Start the MQ listener:
    $ runmqlsr -t tcp -m QM1 -p 1414 &

  6. Modify the default JMSAdmin console configuration as follows:

    1. Edit the JMSAdmin script in the /opt/mqm/java/bin directory to change the JVM to a location of a valid JVM your system.

    2. Set the relevant environment variable required for JMSAdmin by sourcing the setjmsenv script located in the /opt/mqm/java/bin directory.

      $ 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

  7. Create WebSphere MQ queues using the runmqsc console and MQJMS_PSQ.mqsc script.
    $ runmqsc QM1 < MQJMS_PSQ.mqsc

  8. 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.QUEUE is associated with QM1.

         $ runmqsc QM1
             > DEFINE QLOCAL(ORANGE.LOCAL.QUEUE)
             > end

  9. Start the WebSphere MQ Broker:
    $ strmqbrk -m QM1

  10. 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 (for QM1) and TQueue (associated with ORANGE.LOCAL.QUEUE) are defined in the FileSystem 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 Eclipse GlassFish. 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

When using asadmin you need to escape each = and any : characters by prepending a backward slash \. The escape sequence is not necessary if the configuration is performed through the Administration Console. Also , ensure that the provider URL is configured correctly depending on the platform. For example, on Windows systems it should be file:/C:/opt/tmp and on UNIX—based systems it is file://opt/tmp.

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:

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

SupportsXA

true

Set the supports distributed transactions attribute to true. The level of transactional support the adapter provides — none, local, or XA — depends on the capabilities of the Enterprise Information System (EIS) being adapted. If an adapter supports XA transactions and this attribute is XA, the application can use distributed transactions to coordinate the EIS resource with JDBC and JMS resources.

ProviderIntegrationMode

jndi

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.

JndiProperties

 
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

JNDI properties for connecting to WebSphere MQ’s JNDI, specified as comma-separated list of name=value pairs without spaces.

UserName

Name of the WebSphere MQ user

User name to connect to WebSphere MQ. The user name can be overridden in ActivationSpec and ManagedConnection. If no user name is specified anonymous connections will be used, if permitted.

Password

Password for the WebSphere MQ user

Password to connect to WebSphere MQ. The password can be overridden in ActivationSpec and ManagedConnection.

RMIPolicy

OnePerPhysicalConnection

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 OnePerPhysicalConnection, the XAResource wrapper implementation’s isSameRM in GenericJMSRA would check if both the XAResources use the same physical connection, before delegating to the wrapped objects. Therefore, ensure that this attribute is set to OnePerPhysicalConnection if the application uses XA.

LogLevel

Desired log level of JDK logger

Used to specify the level of logging.

You must use the values for SupportsXA, RMPolicy and ProviderIntegrationMode as the required values that are used in this table.
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 Eclipse GlassFish

In order to configure a JMS Connection Factory using GenericJMSRA, a Connector Connection Pool and resource needs to be created in Eclipse GlassFish, 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 Eclipse GlassFish.

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 asadmin to create these resources, see To Create a Connector Connection Pool and To Create a Connector Resource.

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

  1. Create connection pools that point to the connection pools in WebSphere MQ.

    The following asadmin command creates a Connection Pool called mypool and points to the XAQCF created in WebSphere MQ:

         asadmin create-connector-connection-pool -- raname genericra connectiondefinition
            jakarta.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 jakarta.jms.TopicConnectionFactory
            --transactionsupport  XATransaction
            --property ConnectionFactoryJndiName=XATCF mypool2

  2. Create the connector resources.

    The following asadmin command creates a connector resource named jms/MyQCF and 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

  3. Create the JMS destination resources as administered objects.

    In the image above, jms/MyQueue (pointing to GenericJMSRA and TQueue) is created in Eclipse GlassFish.

    The following asadmin command creates a jakarta.jms.Queue administered object and binds it to the Eclipse GlassFish JNDI tree at jms/MyQueue and points to the jms/TQueue created in WebSphere MQ.

         asadmin create-admin-object --raname genericra --restype jakarta.jms.Queue
            --property DestinationJndiName=TQueue jms/MyQueue

    The following asadmin command creates a jakarta.jms.Topic administered object and binds it to the Eclipse GlassFish JNDI tree at jms/MyTopic and points to the jms/TTopic created in WebSphere MQ.

         asadmin create-admin-object --raname genericra --restype jakarta.jms.Topic
            --property DestinationJndiName=TTopic jms/MyTopic
Configuring 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 Eclipse GlassFish, 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());
             }