InfoCenter Home >
4: Developing applications >
4.6: Java Technologies >
4.6.3: Java Message Service (JMS) overview >
4.6.3.4: Support for the use of MQSeries Java Message Service resources
4.6.3.4: Support for the use of MQSeries Java Message Service resources
WebSphere Application Server Enterprise JavaBeans support the transactional use of MQSeries Java Message Service (JMS) resources.
To use this feature, install MQSeries Version 5.2 and the MQSeries classes for Java and JMS.
Only MQSeries Version 5.2 provides this support; earlier versions will not work. Note the following items when using MQSeries: You should apply Correctness Services Diskette 3 (CSD3) to MQSeries Version 5.2. If the MQSeries queue manager stops while the WebSphere Application Server administrative server is running, you can restart the MQSeries manager without rebooting the system. However, it could require that the administrative server is recycled.
To configure JMS resources for use with WebSphere Application Server:
- Download the MQSeries Java and JMS classes, or the pub-sub package
from one of the following URLs:
- Review the MQSeries Using Java book
for a description of the parameters required for WebSphere Application Server.
The instructions in this book refer to a WebSphere Application Server Version 3.5.3 environment, and are
not valid for WebSphere Application Server Version 4.0. For example, the following content in the book is invalid
for Version 4.0:
- Names of jar files
- Dependent classpath
- Adminserver classpath
- Do the following to configure WebSphere Application Server and MQSeries for JMS support:
- Modify the JMSAdmin.bat file to include the option -java.ext.dirs=<WS AE>\lib
when running the MQSeries administration tool, JMSAdmin.
- Modify the JMSAdmin.config file by uncommenting the following lines:
INITIAL_CONTEXT_FACTORY=com.ibm.ejs.ns.jndi.CNInitialContextFactory
PROVIDER_URL=iiop://localhost/ (or iiop://host-name)
- Comment out the following lines in the JMSAdmin.config file:
INITIAL_CONTEXT_FACTORY=com.ibm.sun.jndi.fscontext.RefFSContextFactory
PROVIDER_URL=file:/C:/JNDI-Directory/
- Add the following to the application server classpath:
You can add these classes in the console's
default JVM settings, or by editing WebSphere Application Server's admin.config file.
- <MQ JMS>\lib directory
- com.ibm.mq.jar file
- com.ibm.mqjms.jar file
An alternative way to set up the configuration is
to use the administrative console. In the Resources, JMS Providers folder, specify
the ContextFactory, the provider URL, and the path to the MQSeries JMS .jar files.
See the article about administering JMS support resources for more information.
- Bind the classes provided by the new function into the JNDI namespace using
the MQSeries administration tool, JMSAdmin.
The JMSAdmin tool provides for two, new WebSphere Application Server JMS connection factories:
- WSQCF - a new type of queue connection factory
- WSCTF - a new type of topic connection factory
WebSphere Application Server connection factory objects
The following calls can be used either in a global transaction
or in an unspecified transaction context:
- QueueSender.send
- MessageConsumer.receive
- MessageConsumer.receiveNoWait
- TopicPublisher.publish
If another resource manager, as for example JDBC, is involved in a global
transaction, the MQSeries JMS resources are involved in a 2-phase commit.
The 1-phase commit occurs if only the JMS resources are involved in a global transaction.
This is a feature of the Transaction Manager optimization.
In a global transaction, messages sent with QueueSender.send or
published with TopicPublisher.publish do not become visible until the
transaction is committed. Messages received by MessageConsumer.receive
or MessageConsumer.receiveNoWait are requeued if the transaction is
rolled back. Both bean-managed transaction demarcation and container-managed
transaction demarcation are supported.
If no global transaction is active, then an "unspecified transaction context"
situation occurs. The following circumstances cause an "unspecified transaction context:"
- EJB methods when a global transaction cannot occur (for example, ejbCreate)
- Bean Managed Transaction methods where the bean writer chose not to begin a transaction
- Container Managed Transaction NOT_SUPPORTED or NEVER methods
- Container Managed Transaction SUPPORTS methods when no transaction exists
In an unspecified transaction context, the transactional behavior is specified in the
transacted flag that is passed when the session is created. If the transacted flag is set
to false, the messaging operations occur immediately. This is also known as the 0-phase commit.
If the flag is set to true, the send, receive, and publish operations occur on the commit of the session,
or also known as the 1-phase commit.
A summary of the transactional behavior for objects created on WSQCF or WSTCF is
described in the following table:
| Global transaction context |
Unspecified transaction context |
transacted=false |
2-phase commit |
0-phase commit |
transacted=true |
2-phase commit |
1-phase commit |
To commit or to roll back the messaging work done on a transacted session, call method session.commit()
or session rollback().
First check whether session.getTransacted() returns true before committing the session.
Session.getTransacted() returns true if:
- The user passed in true as the transacted parameter when the session was created, and
- No global transaction is active at the moment of the call.
If both tests are met, you can commit the session. Trying to commit a session
when a global transaction is active will result in the JMS exception, IllegalStateException, being thrown.
JMS XA support in WebSphere Application Server is integrated with local transactions.
For container managed transactions, an "unspecified transaction context" causes WebSphere
Application Server to start a local transaction.
In Version 4.0, the scope of the local transaction is the EJB method.
The action taken at the end of the EJB method (commit or rollback of the local transaction)
depends on the information contained in the deployment descriptor. This information is a
WebSphere Application Server extension. The transaction manager will commit or rollback any
outstanding, uncommitted work done within the local transaction without any user
intervention. The default is to roll back.
Any work performed on a JMS session in an unspecified transaction context, will be
rolled back or committed if the corresponding local transaction is rolled back or committed.
Requestors are only used with non-transacted sessions. Therefore, QueueRequestor
and TopicRequestor cannot be used with sessions created by WebSphere Application
Server JMS connection factories.
Unsupported interfaces and methods
The following JMS interfaces are not designed for application use and, therefore,
cannot be invoked:
Unsupported interfaces |
javax.jms.ServerSession |
javax.jms.ServerSessionPool |
javax.jms.ConnectionConsumer |
all the javax.jms.XA interfaces |
The following JMS methods are inappropriate
in this environment and interfere with connection
management by the container. Therefore, these methods cannot be used:
Unsupported methods |
javax.jms.Connection.setExceptionListener |
javax.jms.Connection.stop |
javax.jms.Connection.setClientID |
javax.jms.Connection.setMessageListener |
javax.jms.Session.getMesssageListener |
javax.jms.QueueConnection.createConnectionConsumer |
javax.jms.TopicConnection.createConnectionConsumer |
javax.jms.TopicConnection.createDurableConnectionConsumer |
javax.jms.MessageConsumer.setMessageListener |
All the above methods throw the JMS exception, IllegalStateException, when invoked.
You cannot register a MessageListener
with a QueueReceiver or TopicSubscriber.
The following methods throw the JMS exception, IllegalStateException, if used
within a global transaction:
javax.jms.Session.commit |
javax.jms.Session.rollback |
javax.jms.Session.recover |
With the Enterprise JavaBeans programming model, you must ensure all JMS resources are closed correctly.
Since JMS resources never time-out, JMS resources that are not closed correctly will continue to consume MQSeries resources.
The MQSeries resources also persist until the application server or MQSeries Queue manager is restarted.
Restrictions
The following restrictions exist regarding the use of JMS XA support in WebSphere Application Server:
- A subscriber can only be used in the same type of transactional context (for example, a global transaction or an
unspecified transaction context) as the one that existed when the subscriber was created.
If this restriction is not respected, the JMS exception, subscriber restriction, is thrown.
If a global transaction is active at the creation of the subscriber, that subscriber can be used to
receive messages in different global transactions, but not in an unspecified transaction context.
If an unspecified transaction context is active when the subscriber is created, that subscriber cannot
be used with a global transaction.
- The use of JMS sessions across methods with different transactional attributes is restricted.
If a session was used within a global transaction, it cannot be reused in a different
global transaction or in an unspecified context until the first transaction commits.
Similarly, if there is work outstanding in a local transaction then the session
cannot be used in a global transaction until the local transaction has finished.
Session use, in this case, refers to the send, receive, and publish operations using
the message producers or consumers that were created on the session.
|
|