25/29

# 17 Administering the Java Message Service (JMS)

The Java Message Service (JMS) API is a messaging standard that allows Java EE applications and components, including message-driven beans (MDBs), to create, send, receive, and read messages. It enables distributed communication that is loosely coupled, reliable, and asynchronous.

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

GlassFish Server also supports the Generic Resource Adapter for JMS (GenericJMSRA), available as an Add-On in the Administration Console's Update Tool, for use as a resource adapter to connect to other JMS providers. The last section in this chapter, Using the Generic Resource Adapter for JMS to Integrate Supported External JMS Providers, describes the GenericJMSRA and provides instructions for using it to make other supported JMS providers available to GlassFish Server.

The following topics are addressed here:

- About the JMS Service

- Updating the JMS Service Configuration

- Administering JMS Hosts

- Administering JMS Connection Factories and Destinations

- Administering JMS Physical Destinations

- Special Situations When Using the JMS Service

- Troubleshooting the JMS Service

- Using the Generic Resource Adapter for JMS to Integrate Supported External JMS Providers

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

## About the JMS Service

To support JMS messaging, the JMS Service provides the following administrative objects:

JMS Service Configuration

  The JMS service configuration is part of the overall configuration for a GlassFish standalone instance or cluster. It specifies how the JMS Service is to create and maintain connections with JMS Hosts.

JMS Hosts

  JMS hosts are the message servers that host destinations, store messages, and interact with applications to send and receive messages across connections. In Message Queue, JMS hosts are called brokers.

  The JMS service supports these types of JMS hosts:

  - Embedded type, in which the JMS host runs in the same JVM as the GlassFish instance; its configuration and lifecycle are managed by the JMS service

  - Local type, in which the JMS host runs separately on the same host as the GlassFish instance; its configuration and lifecycle are managed by the JMS service

  - Remote type, in which the JMS host represents a Message Queue broker or broker cluster that is external to the JMS service; its operation is managed using Message Queue administrative tools

  For more information about JMS host types, see About JMS Host Types.

JMS Connection Factory Resources

  JMS connection factory resources house the information that applications use to connect to a JMS provider. For each JMS connection factory, the JMS service automatically maintains a GlassFish connector resource and a GlassFish connector connection pool in order to support connection pooling and failover.

JMS Destination Resources

  JMS destination resources house the information that applications use to specify the target destination of messages they produce and the source destination of messages they consume. For each JMS destination resource, the JMS service automatically maintains a GlassFish administered object.

JMS Physical Destinations

  JMS physical destinations provide a means to create and manage JMS destinations administratively instead of having them created dynamically when needed by an application. While dynamic creation of destinations is often sufficient during application development, administratively created physical destinations are more suitable for production environments.

### JMS Service High Availability

Just as GlassFish Server supports clusters of instances to provide high availability, Message Queue supports clusters of brokers to provide service availability or service and data availability, depending on the type of broker cluster, as described in "Broker Clusters" in Oracle GlassFish Server 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 Oracle GlassFish Server 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 GlassFish Server waits for the JMS service to start before aborting the startup.

`start-args`

  A list of arguments the JMS service passes to Embedded and Local type JMS hosts on startup. Permissible arguments are the options supported by the Message Queue `imqbrokerd` command, as described in "Broker Utility" in Oracle GlassFish Server 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 Oracle GlassFish Server Message Queue Administration Guide for syntax information.

Note:

After making changes to the JMS service configuration, GlassFish Server instances that use the configuration must be restarted in order for the changes to be propagated.

### Setting Message Queue Broker Properties in the JMS Service Configuration

You can specify any Message Queue broker property in the JMS service configuration by adding it by name to the Additional Properties table on the Java Message Service page for the configuration in the Administration Console, or by using a `set` subcommand of the following form:

    set configs.config.config-name.jms-service.property.broker-property-name=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.

Note:

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

## Administering JMS Hosts

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

The following topics are addressed here:

- About JMS Host Types

- Configuring Embedded and Local JMS Hosts

- To Create a JMS Host

- To List JMS Hosts

- To Update a JMS Host

- To Delete a JMS Host

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

### About JMS Host Types

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

Embedded Type

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

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

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

Local Type

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

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

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

Remote Type

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

Note:

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 jms-host-name

   `--mqhost`

     The host name of the Message Queue broker.

   `--mqport`

     The port number of the Message Queue broker.

   `--mquser`

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

   `--mqpassword`

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

   `--target`

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

   `--property`

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

         prop1Name=prop1Value:prop2Name=prop2Value:...

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

     Note:

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

   jms-host-name

     The unique name of the JMS host.

Example 17-1 Creating a JMS Host

This example creates a JMS host named `MyNewHost`.

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

See Also

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

### To List JMS Hosts

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

1. Ensure that the server is running.

   Remote `asadmin` subcommands require a running server.

2. List the JMS hosts by using the `list-jms-hosts` 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.

     Note:

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

Example 17-3 Updating a JMS Host

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

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

### To Delete a JMS Host

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

1. Ensure that the server is running.

   Remote `asadmin` subcommands require a running server.

2. List the JMS hosts by using the `list-jms-hosts` 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 GlassFish Server, JMS is implemented by performing the following tasks:

- Creating a connection factory

- Creating a destination, which requires creating a physical destination and a destination resource that refers to the physical destination

JMS applications use the Java Naming and Directory Interface (JNDI) API to access the connection factory and destination resources. A JMS application normally uses at least one connection factory and at least one destination. By studying the application or consulting with the application developer, you can determine what resources must be created. The order in which the resources are created does not matter.

GlassFish Server provides the following types of connection factory objects:

- `QueueConnectionFactory` objects, used for point-to-point communication

- `TopicConnectionFactory` objects, used for publish-subscribe communication

- `ConnectionFactory` objects, which can be used for both point-to-point and publish-subscribe communications (recommended for new applications)

GlassFish Server provides the following types of destination objects:

- `Queue` objects, used for point-to-point communication

- `Topic` objects, used for publish-subscribe communication

The following topics are addressed here:

- To Create a Connection Factory or Destination Resource

- To List JMS Resources

- To Delete a Connection Factory or Destination Resource

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 Oracle GlassFish Server High Availability Administration Guide. For instructions on administering physical destinations, see Administering JMS Physical Destinations.

### To Create a Connection Factory or Destination Resource

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

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

Tip:

To specify the `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 `javax.jms.ConnectionFactory` whose JNDI name is `jms/DurableConnectionFactory`. The `ClientId` property sets a client ID on the connection factory so that it can be used for durable subscriptions. The JNDI name for a JMS resource customarily includes the `jms/` naming subcontext.

    asadmin> create-jms-resource --restype javax.jms.ConnectionFactory
    --description "connection factory for durable subscriptions"
    --property ClientId=MyID jms/DurableConnectionFactory
    Command create-jms-resource executed successfully.

Example 17-6 Creating a JMS Destination

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

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

See Also

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

### To List JMS Resources

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

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 javax.jms.TopicConnectionFactory
    jms/DurableTopicConnectionFactory
    jms/TopicConnectionFactory
    Command list-jms-resources executed successfully.

See Also

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

### To Delete a Connection Factory or Destination Resource

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

Before You Begin

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

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, GlassFish Server automatically creates the physical destination and sets the value of the `maxNumActiveConsumers` property to `-1`. However, it is good practice to create the physical destination beforehand. The first time that an application accesses a destination resource, Message Queue automatically creates the physical destination specified by the Name property of the destination resource. This automatically created physical destination is temporary and expires after a period specified by a Message Queue configuration property, provided that there are no messages in it and no message producers or consumers connected to it.

The following topics are addressed here:

- To Create a JMS Physical Destination

- To List JMS Physical Destinations

- To Purge Messages From a Physical Destination

- To Delete a JMS Physical Destination

### 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 Oracle GlassFish Server 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 GlassFish Server to provide JMS messaging managed through a rich set of `asadmin` subcommands and Administration Console pages to simplify JMS messaging administration tasks. In most instances, this tight integration is transparent and automatic, requiring no special effort on the part of an administrator. In certain special situations, though, an administrator must perform a task such a setting a Message Queue broker property or a GlassFish object attribute to enable or disable a capability of the integration. The topics in this section describe these situations.

Restarting an Embedded or Local Broker That Has Failed

  Because the JMS service, not Message Queue, manages the lifecycle of brokers acting as Embedded and Local JMS hosts, do not use the `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 GlassFish Server log file. For `server`, the Domain Administrations Server (DAS), the log is available at domain-dir`/logs/server.log`; for other GlassFish instances, the log is available at as-install`/nodes/`node-name`/`instance-name`/logs/server.log`.

  If the log file indicates that a Message Queue broker acting as a Remote JMS host did not respond to a message, stop the broker and then restart it.

- View the broker log. For a broker associated with the Domain Administration Server (DAS), the log is available at domain-dir`/imq/instances/imqbroker/log/log.txt`; for brokers associated with other GlassFish instances, the log is available at as-install`/nodes/`node-name`/`instance-name`/imq/instances/`mq-instance-name`/log/log.txt`.

- For Remote type JMS hosts, be sure to start Message Queue brokers first, then GlassFish Server instances.

- If all Message Queue brokers are down, it can take up to 30 minutes for GlassFish Server to go down or up when you are using the default values in JMS. You can change the default values for this timeout. For example:

      asadmin set domain1.jms-service.reconnect-interval-in-seconds=5

## Using the Generic Resource Adapter for JMS to Integrate Supported External JMS Providers

GlassFish Server supports the integration and use of Oracle WebLogic JMS and IBM WebSphere MQ JMS providers through the use of the Generic Resource Adapter for JMS (GenericJMSRA), which is available as an Add-On in the Administration Console's Update Tool. This Java EE connector 1.5 resource adapter can wrap the JMS client library of Oracle WebLogic JMS and IBM WebSphere MQ and make it available for use by GlassFish. The adapter is a `.rar` archive that can be deployed and configured using GlassFish Server administration tools.

The following topics are addressed here:

- Configuring GenericJMSRA for Supported External JMS Providers

- Using GenericJMSRA with WebLogic JMS

- Using GenericJMSRA with IBM WebSphere MQ

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

1. Download the `genericra.rar` archive as an Add-On in the Administration Console's Update Tool.

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

   See "Deploying a Connector Module" in Oracle GlassFish Server 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 `javax.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 `javax.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 `javax.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 `javax.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 `javax.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 `javax.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 `javax.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 GlassFish Server `glassfish-ejb-jar.xml` deployment descriptor of an MDB as `activation-config-properties`. All the resource adapter properties can be overridden in an Activation Spec. Additional properties available only in ActivationSpec are given below.

Property Name | Valid Value | Default Value | Description
--- | --- | --- | ---
`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` | `javax.jms.Queue` or `javax.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 GlassFish Server to send messages to, and receive messages from, Oracle WebLogic JMS.

GenericJMSRA should be used in conjunction with the WebLogic Server Thin T3 Client. Due to the nature of this client, messages exchanged between GlassFish Server and WebLogic Server cannot be sent or received in XA transactions. There is also only limited support for asynchronous receipt of messages in an MDB, as described in detail in Limitations When Using GenericJMSRA with WebLogic JMS.

The following topics are addressed here:

- Deploy the WebLogic Thin T3 Client JAR in GlassFish Server

- Configure WebLogic JMS Resources for Integration

- Create a Resource Adapter Configuration for GenericJMSRA to Work With WebLogic JMS

- Deploy the GenericJMSRA Resource Archive

- Configuring an MDB to Receive Messages from WebLogic JMS

- Accessing Connections and Destinations Directly

- Limitations When Using GenericJMSRA with WebLogic JMS

- Configuration Reference of GenericJMSRA Properties for WebLogic JMS

#### Deploy the WebLogic Thin T3 Client JAR in GlassFish Server

WebLogic Server provides several different clients for use by standalone applications that run outside of WebLogic Server. These client are summarized in "Overview of Stand-alone Clients" in Programming Stand-alone Clients for Oracle WebLogic Server. When connecting from GlassFish Server to WebLogic JMS resources you must use the WebLogic Thin T3 client, `wlthint3client.jar`.

There are a couple of methods to deploy the WebLogic Thin T3 client in GlassFish Server and make it available to GenericJMSRA:

- To make the Thin T3 client available to all applications, copy the `wlthint3client.jar` to the as-install`/lib` directory under your GlassFish Server installation. The Thin T3 client can be found in a WebLogic Server installation in a directory similar to MW_HOME`/server/lib`.

- It is also possible to deploy the Thin T3 client in a less global manner, so that it is specific to an individual application. For information on how to do this, see "Application-Specific Class Loading" in Oracle GlassFish Server Application Development Guide.

#### Configure WebLogic JMS Resources for Integration

If you need to configure the necessary WebLogic JMS resources on the WebLogic Server from which you want to access messages using GlassFish Server, then follow the instructions in the WebLogic Server documentation for configuring the necessary resources, such as destinations, and connection factories.

- JMS System Module Configuration

- Queue and Topic Destination Configuration

- Connection Factory Configuration

The example code snippets in this section refer to a WebLogic JMS connection factory named `WLoutboundQueueFactory` and queue destination named `WLoutboundQueue`. For conceptual overviews on configuring WebLogic JMS resources, refer to "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 GlassFish Server. You can do this using either the Administration Console or the `asadmin` command. If you use theAdministration Console then you need deploy the GenericJMSRA resource archive first. Here's an example using `asadmin`:

    asadmin create-resource-adapter-config --host localhost --port 4848 --property
    SupportsXA=false:DeliveryType=Synchronous:ProviderIntegrationMode
                              =jndi:JndiProperties=java.naming.factory.initial\
                              =weblogic.jndi.WLInitialContextFactory,java.naming.provider.url\
                              =t3\://localhost\:7001,java.naming.factory.url.pkgs\
                              =weblogic.corba.client.naming 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.

Note:

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

The supported version of the GenericJMSRA resource archive is available as an Add-On in the Administration Console's Update Tool.

1. Download the GenericJMSRA resource archive (genericra.rar) using the Administration Console's Update Tool.

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 GlassFish Server `glassfish-ejb-jar.xml` file. To configure a MDB to receive messages from WebLogic JMS, you would configure these deployment descriptor files as follows:

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

   Note:

   If container-managed transactions are configured, then the transactional attribute must be set to `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.

Note:

If you want configure connections and destination resources using the Administration Console, this is explained in the Administration Console online help. When using Administration Console, follow the instructions for creating a new Connector Connection Pool and Admin Object Resources, and not the instructions for creating a JMS Connection Pool and Destination Resources. For more information about using `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 GlassFish Server JNDI store:

            Context initialContect  = new InitialContext();
            QueueConnectionFactory queueConnectionFactory = (QueueConnectionFactory)
                 jndiContext.lookup("java:comp/env/jms/MyQCFactory");
            Queue queue = (Queue) jndiContext.lookup("java:comp/env/jms/outboundQueue");

   Note that the resources used are GlassFish Server resources, not WebLogic JMS resources. For every connection factory or destination that you want to use in the WebLogic JMS JNDI store, you need to create a corresponding connection factory or destination in the GlassFish Server JNDI store and configure the GlassFish Server object to point to the corresponding WebLogic JMS object.

2. Declaring the connection factory and destination

   In accordance with standard Java EE requirements, these resources need to be declared in the deployment descriptor for the MDB, EJB or other component. For example, for a session bean, configure the `ejb-jar.xml` with `<resource-env-ref>` elements, as follows:

       <ejb-jar>
         <enterprise-beans>
           <session>
             . . .
             <resource-env-ref>
               <resource-env-ref-name>jms/QCFactory</resource-env-ref-name>
               <resource-env-ref-type>javax.jms.QueueConnectionFactory</resource-env-ref-type>
             </resource-env-ref>
             <resource-env-ref>
               <resource-env-ref-name>jms/outboundQueue</resource-env-ref-name>
               <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
             </resource-env-ref>

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 GlassFish Server using names that map to the corresponding connection factory in the WebLogic JNDI store.

       asadmin create-connector-connection-pool --host localhost --port 4848
          --raname genericra --connectiondefinition javax.jms.QueueConnectionFactory
          --target server --transactionsupport LocalTransaction
          --property ConnectionFactoryJndiName=jms/WLOutboundQueueFactory
            qcpool

       asadmin create-connector-resource --host localhost --port 4848
           --poolname qcpool --target server jms/QCFactory

   These `asadmin` commands together creates a connection factory in GlassFish Server and its corresponding connection pool.

   - The connection pool has the JNDI name `jms/WLoutboundQueueFactory` and obtains connections from a connection pool named `qcpool`.

   - The connection pool `qcpool` uses the resource adapter `genericra` and contains objects of type `javax.jms.QueueConnectionFactory`.

   - The `transactionsupport` argument is set to `LocalTransaction`, which specifies that the connection will be used in local transactions only. You can also specify `NoTransaction`. However, the default setting of `XATransaction` cannot be used. For more information, see Limitations When Using GenericJMSRA with WebLogic JMS.

   - The connection pool is configured with the properties specified using the `properties` argument; multiple properties are configured as a colon-separated list of name-value pairs. Only one property is configured in this example, as follows:

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

   This `asadmin` command creates a destination in GlassFish Server.

   - The destination has the JNDI name `jms/outboundQueue`, uses the resource adapter `genericra`, and is of type `javax.jms.Queue`.

   - The destination is configured with the properties specified using the `properties` argument; multiple properties are configured as a colon-separated list of name-value pairs. Only one property is configured in this example, as follows:

         DestinationJndiName=jms/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 GlassFish Server JNDI store using the Administration Console or the `asadmin connector-connection-pool` command. All the properties that can be set on a resource adapter configuration can be overridden by setting them on a destination object. The properties specific to `ManagedConnectionFactory` objects are listed in the following table.

Property Name | Valid Value | Default Value | Description
--- | --- | --- | ---
`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 GlassFish Server 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 GlassFish Server.

Destination Properties

Destination (queue or topic) objects are created in the GlassFish Server JNDI store using the Administration Console or the `asadmin connector-admin-object` command. All the properties that can be set on a resource adapter configuration can be overridden by setting them on a destination object. The properties specific to destination objects are listed in the following table.

Property Name | Valid Value | Default Value | Description
--- | --- | --- | ---
`DestinationJndiName` | A valid JNDI name | None | JNDI name of the destination object in the GlassFish Server JNDI store. This destination object should be configured to refer to the corresponding physical destination in the WebLogic JNDI store.

ActivationSpec Properties

An ActivationSpec is a set of properties that configures a MDB. It is defined either in the MDB's GlassFish Server deployment descriptor `glassfish-ejb-jar.xml` using `activation-config-property` elements or in the MDB itself using annotation. All the resource adapter properties listed in the table above can be overridden in an ActivationSpec. Additional properties available only to a ActivationSpec are given below.

Property Name | Valid Value | Default Value | Description
--- | --- | --- | ---
`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 GlassFish Server 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 GlassFish Server JNDI store. This destination should be configured to refer to the physical destination in the WebLogic JNDI store.
`DestinationType` | `javax.jms.Queue` or `javax.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 GlassFish Server to send messages to, and receive messages from, IBM WebSphere MQ. GlassFish Serveronly supports using GenericJMSRA with WebSphere MQ version 6.0 and WebSphere MQ version 7.0

These instructions assume that the WebSphere MQ broker and GlassFish Server are deployed and running on the same physical host/machine. If you have the WebSphere MQ broker running on a different machine and need to access it remotely, refer to the WebSphere MQ documentation for configuration details. The resource adapter configuration and other application server related configuration remains unchanged.

The following topics are addressed here:

- Preliminary Setup Procedures for WebSphere MQ Integration

- Configure the WebSphere MQ Administered Objects

- Create a Resource Adapter Configuration for GenericJMSRA to Work With WebSphere MQ

- Deploy the GenericJMSRA Archive

- Create the Connection Factories and Administered Objects in GlassFish Server

- Configuring an MDB to Receive Messages from WebSphere MQ

#### Preliminary Setup Procedures for WebSphere MQ Integration

Before you can configure WebSphere MQ to exchange messages with GlassFish Server, you must complete the following tasks:

- The following permissions must be added to the `server.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 GlassFish Serverwith WebSphere MQ 6.0 or 7.0, copy the necessary JAR files to the as-install`/lib` directory:

  - For WebSphere MQ 6.0, copy these JAR files to the as-install`/lib` directory:

        /opt/mqm/java/lib/com.ibm.mq.jar
        /opt/mqm/java/lib/com.ibm.mq.jms.Nojndi.jar
        /opt/mqm/java/lib/com.ibm.mq.soap.jar
        /opt/mqm/java/lib/com.ibm.mqjms.jar
        /opt/mqm/java/lib/com.ibm.mqetclient.jar
        /opt/mqm/java/lib/commonservices.jar
        /opt/mqm/java/lib/dhbcore.jar
        /opt/mqm/java/lib/rmm.jar
        /opt/mqm/java/lib/providerutil.jar
        /opt/mqm/java/lib/CL3Export.jar
        /opt/mqm/java/lib/CL3Nonexport.jar

    where `/opt/mqm` is the location of the WebSphere MQ 6.0 installation.

  - For WebSphere MQ 7.0, copy these JAR files to the as-install`/lib` directory:

        /opt/mqm/java/lib/com.ibm.mq.jar,
        /opt/mqm/java/lib/com.ibm.mq.jms.Nojndi.jar,
        /opt/mqm/java/lib/com.ibm.mq.soap.jar,
        /opt/mqm/java/lib/com.ibm.mqjms.jar,
        /opt/mqm/java/lib/com.ibm.mq.jmqi.jar,
        /opt/mqm/java/lib/com.ibm.mq.commonservices.jar,
        /opt/mqm/java/lib/dhbcore.jar,
        /opt/mqm/java/lib/rmm.jar,
        /opt/mqm/java/lib/providerutil.jar,
        /opt/mqm/java/lib/CL3Export.jar,
        /opt/mqm/java/lib/CL3Nonexport.jar

    where `/opt/mqm` is the location of the WebSphere MQ 7.0 installation.

- Set the `LD_LIBRARY_PATH` environment variable to the `java/lib` directory, and then restart GlassFish Server. For example, in a UNIX—based system, with WebSphere MQ installed under `/opt/mqm`, you would enter:

      $ export LD_LIBRARY_PATH=/opt/mqm/java/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 GlassFish Server. Therefore, you will need to change the administered object names to suit your installation.

Before You Begin

If WebSphere MQ created a user and a group named `mqm` during the installation, then you must specify a password for the `mqm` user using the `$ passwd mqm` command.

Description of the illustration websphere-mq.png

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 GlassFish Server. You can do this using either the Administration Console or the `asadmin` command. Use the following `asadmin` command to create a resource adapter configuration for `genericra` to configure it to work with WebSphere MQ.

                         asadmin> create-resource-adapter-config
                           --user <adminname> --password <admin password>
                           --property SupportsXA=true:ProviderIntegrationMode
                           =jndi:UserName=mqm:Password=###:RMPolicy
                           =OnePerPhysicalConnection:JndiProperties
                           =java.naming.factory.url.pkgs\\
                           =com.ibm.mq.jms.naming,java.naming.factory.initial\\
                           =com.sun.jndi.fscontext.RefFSContextFactory,java.naming.provider.url\\
                           =file\\:\\/\\/opt\\/tmp:LogLevel=finest genericra

Note:

When using `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:

Note:

The tables in this section describe the GenericJMSRA properties that are relevant only when integrating with WebSphere MQ. For a complete list of properties, see the comprehensive table in GenericJMSRA Configuration Properties.

Property Name | Required Value | Description
--- | --- | ---
`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.

Note:

You must use the values for `SupportsXA`, `RMPolicy` and `ProviderIntegrationMode` as the required values that are used in this table.

#### Deploy the GenericJMSRA Archive

The GenericJMSRA archive is available as an Add-On in the Administration Console's Update Tool.

For instructions on downloading and deploying GenericJMSRA, see Deploy the GenericJMSRA Resource Archive.

#### Create the Connection Factories and Administered Objects in GlassFish Server

In order to configure a JMS Connection Factory using GenericJMSRA, a Connector Connection Pool and resource needs to be created in GlassFish Server, as described in this section.

Using the example WebSphere MQ configuration in Configure the WebSphere MQ Administered Objects, you will see `mypool` (pointing to `GenericJMSRA` and `QCF`) and `jms/MyQCF` (for `mypool`) created in GlassFish Server.

Note:

If you want configure connections and destination resources using the Administration Console, this is explained in the Administration Console online help. When using Administration Console, following the, instructions for creating a new Connector Connection Pool and Admin Object Resources, and not the instructions for creating a JMS Connection Pool and Destination Resources. For more information about using `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 GlassFish Server using names that map to the corresponding connection and destination resources in WebSphere MQ. The connections and destination name in these steps map to the example WebSphere MQ configuration in Configure the WebSphere MQ Administered Objects.

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
                   javax.jms.QueueConnectionFactory --transactionsupport  XATransaction
                   --property ConnectionFactoryJndiName=QCF mypool

   The following `asadmin` command creates a Connection Pool called `mypool2` and points to the `XATCF` created in WebSphere MQ:

            asadmin create-connector-connection-pool
                   -- raname genericra connectiondefinition javax.jms.TopicConnectionFactory
                   --transactionsupport  XATransaction
                   --property ConnectionFactoryJndiName=XATCF mypool2

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

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

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

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

            asadmin create-admin-object --raname genericra --restype javax.jms.Topic
                   --property DestinationJndiName=TTopic jms/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 GlassFish Server, as shown below.

           <sun-ejb-jar>
             <enterprise-beans>
             <unique-id.1</unique-id>
             <ejb>
                <ejb-name>SimpleMessageEJB</ejb-name>
                <jndi-name>jms/SampleQueue</jndi-name>
                 <!-- QCF used to publish reply messages -->
                <resource-ref>
                   <res-ref-name>jms/MyQueueConnectionFactory</res-ref-name>
                   <jndi-name>jms/MyQCF</jndi-name>
                   <default-resource-principal>
                      <name>mqm</name>
                      <password>mqm</password>
                   </default-resource-principal>
                </resource-ref>
                <!-- reply destination resource> Creating of this replyQueue destination resource is not
                     shown above, but the steps are similar to creating the  "jms/MyQueue" resource -->
                <resource-env-ref>
                   <resource-env-ref-name>jms/replyQueue</resource-env-ref-name>
                   <jndi-name>jms/replyQueue</jndi-name>
                </resource-env-ref>

                <!-- Activation related RA specific configuration for this MDB -->
                <mdb-resource-adapter>
                <!-- resource-adapter-mid points to the Generic Resource Adapter for JMS -->
                <resource-adapter-mid>genericra</resource-adapter-mid>
                <activation-config>
                   <activation-config-property>
                      <activation-config-property-name>DestinationType</activation-config-property-name>
                      <activation-config-property-value>javax>jms>Queue</activation-config-property-value>
                   </activation-config-property>
                   <activation-config-property>
                      <activation-config-property-name>ConnectionFactoryJndiName</activation-config-property-name>
                      <activation-config-property-value>QCF</activation-config-property-value>
                   </activation-config-property>
                   <activation-config-property>
                      <activation-config-property-name>DestinationJndiName</activation-config-property-name>
                      <activation-config-property-value>TQueue</activation-config-property-value>
                   </activation-config-property>
                   <activation-config-property>
                      <activation-config-property-name>MaxPoolSize</activation-config-property-name>
                      <activation-config-property-value>32</activation-config-property-value>
                   </activation-config-property>
                   <activation-config-property>
                      <activation-config-property-name>RedeliveryAttempts</activation-config-property-name>
                      <activation-config-property-value>0</activation-config-property-value>
                   </activation-config-property>
                   <activation-config-property>
                      <activation-config-property-name>ReconnectAttempts</activation-config-property-name>
                      <activation-config-property-value>4</activation-config-property-value>
                   </activation-config-property>
                   <activation-config-property>
                      <activation-config-property-name>ReconnectInterval</activation-config-property-name>
                      <activation-config-property-value>10</activation-config-property-value>
                   </activation-config-property>
                   <activation-config-property>
                      <activation-config-property-name>RedeliveryInterval</activation-config-property-name>
                      <activation-config-property-value>1</activation-config-property-value>
                   </activation-config-property>
                   <activation-config-property>
                      <activation-config-property-name>SendBadMessagesToDMD</activation-config-property-name>
                      <activation-config-property-value>false</activation-config-property-value>
                   </activation-config-property>
                </activation-config>
              </mdb-resource-adapter>
              </ejb>
              </enterprise-beans>
           </sun-ejb-jar>

The business logic encoded in Message Driven Bean could then lookup the configured `QueueConnectionFactory/Destination` resource to create a connection as shown below.

                 Context context = null;
                 ConnectionFactory connectionFactory = null;
                 logger>info("In PublisherBean>ejbCreate()");
                 try {
                     context = new InitialContext();
                     queue = (javax>jms>Queue) context>lookup ("java:comp/env/jms/replyQueue");
                     connectionFactory = (ConnectionFactory) context>lookup("java:comp/env/jms/MyQueueConnectionFactory");
                     connection = connectionFactory>createConnection();
                 } catch (Throwable t) {
                     logger>severe("PublisherBean>ejbCreate:" + "Exception: " +
                     t>toString());
                 }