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:

  1. Download the MQSeries Java and JMS classes, or the pub-sub package from one of the following URLs:
  2. 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
  3. Do the following to configure WebSphere Application Server and MQSeries for JMS support:
    1. Modify the JMSAdmin.bat file to include the option -java.ext.dirs=<WS AE>\lib when running the MQSeries administration tool, JMSAdmin.
    2. 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)
    3. 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/
    4. 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
    5.   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.
  4. 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.

Go to previous article: Support of Java Message Service resources Go to next article: Java Clients

 

 
Go to previous article: Support of Java Message Service resources Go to next article: Java Clients