1. Overview of GlassFish Server Administration
Default Settings and Locations
Instructions for Administering GlassFish Server
4. Administering the Virtual Machine for the Java Platform
6. Administering Web Applications
7. Administering the Logging Service
8. Administering the Monitoring Service
9. Writing and Running JavaScript Clients to Monitor GlassFish Server
10. Administering Life Cycle Modules
11. Extending and Updating GlassFish Server
Part II Resources and Services Administration
12. Administering Database Connectivity
13. Administering EIS Connectivity
14. Administering Internet Connectivity
15. Administering the Object Request Broker (ORB)
16. Administering the JavaMail Service
17. Administering the Java Message Service (JMS)
Updating the JMS Service Configuration
Setting Message Queue Broker Properties in the JMS Service Configuration
Configuring Embedded and Local JMS Hosts
Administering JMS Connection Factories and Destinations
To Create a Connection Factory or Destination Resource
To Delete a Connection Factory or Destination Resource
Administering JMS Physical Destinations
To Create a JMS Physical Destination
To List JMS Physical Destinations
To Purge Messages From a Physical Destination
To Delete a JMS Physical Destination
Special Situations When Using the JMS Service
Troubleshooting the JMS Service
Using the Generic Resource Adapter for JMS to Integrate Supported External JMS Providers
Configuring GenericJMSRA for Supported External JMS Providers
To Deploy and Configure GenericJMSRA
GenericJMSRA Configuration Properties
Using GenericJMSRA with WebLogic JMS
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
Using GenericJMSRA with IBM WebSphere MQ
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
18. Administering the Java Naming and Directory Interface (JNDI) Service
19. Administering Transactions
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:
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.
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.
See Deploying a Connector Module in Oracle GlassFish Server 3.1 Application Deployment Guide
The following table describes the properties that can be set to when configuring the resource adapter.
|
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.
|
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.
|
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.
|
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:
Create a Resource Adapter Configuration for GenericJMSRA to Work With WebLogic JMS
Configuration Reference of GenericJMSRA Properties for WebLogic JMS
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 3.1 Application Development Guide.
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.
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:
|
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.
The supported version of the GenericJMSRA resource archive is available as an Add-On in the Administration Console's Update Tool.
$ 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.
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:
<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.
<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 the WebLogic Server Administration Console Online Help and the WebLogic Server WLST Online and Offline Command Reference.
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.
The following code looks up a connection factory with the JNDI name jms/QCFactory and a queue with the namejms/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.
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>
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.
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.
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.
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.
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.
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.
|
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.
|
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.
|
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.
|
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:
Create a Resource Adapter Configuration for GenericJMSRA to Work With WebSphere MQ
Create the Connection Factories and Administered Objects in GlassFish Server
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
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.
$ su mqm
$ export LD_ASSUME_KERNEL=2.2.5
$ crtmqm QM1
In the image above, QM1 is associated with the IBM WebSphere MQ broker.
$ strmqm QM1
$ runmqlsr -t tcp -m QM1 -p 1414 &
$ cd /opt/mqm/java/bin $ source setjmsenv
where /opt/mqm is the location of the WebSphere MQ installation.
INITIAL_CONTEXT_FACTORY=com.sun.jndi.fscontext.RefFSContextFactory PROVIDER_URL=file:/opt/tmp
$ runmqsc QM1 < MQJMS_PSQ.mqsc
In the image above, ORANGE.LOCAL.QUEUE is associated with QM1.
$ runmqsc QM1 > DEFINE QLOCAL(ORANGE.LOCAL.QUEUE) > end
$ strmqbrk -m QM1
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)
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.
|
Note - You must use the values for SupportsXA, RMPolicy and ProviderIntegrationMode as the required values that are used in this table.
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.
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.
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.
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
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
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
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()); }