Porting WebLogic JMS Applications

The following sections describe how to port your WebLogic JMS applications to a newer version of WebLogic Server:

Changes in existing feature functionality have been made in order to comply with Sun Microsystem's JMS Specification. Therefore, you should check feature functionality changes in the following tables before beginning any porting procedures:

The following table lists the changes in existing feature functionality from WebLogic Server version 5.1, and also indicates any code changes that might be required as a result. For additional information pertaining to the JMS Specification's version change history, refer to Chapter 11, "Change History" in the specification.

Category	Description	Code Modification
Connection Factories	Two default connection factories have been deprecated. The JNDI names for these factories are: javax.jms.QueueConnectionFactory javax.jms.TopicConnectionFactory For backwards compatibility, the JNDI names for these two connection factories are still defined and supported. WebLogic JMS 6.x or later defines one connection factory, by default: weblogic.jms.ConnectionFactory You can also specify user-defined connection factories using the Administration Console. Note: Using the default connection factory, you have no control over the WebLogic server on which the connection factory may be deployed. If you would like to target a particular WebLogic Server, create a new connection factory and specify the appropriate WebLogic Server target(s).	It is recommended that existing code that use the deprecated classes be modified to use a new default or user-defined connection factory class. For example, if your code specified the following constant using the default queue connection factory: public final static String JMS_FACTORY="javax.jms.QueueConnectionFactory" You should modify the constant to use a new user-defined connection factory, for example: public final static String JMS_FACTORY="weblogic.jms.QueueConnectionFactory" For true backwards compatibility with previous releases, you should ensure that you select the Allow Close In onMessage and User Transactions Enabled check boxes when configuring the connection factory. For more information about defining connection factories, see "JMS Connection Factory Tasks" in the Administration Console Online Help.
Connection Factories	In order to instantiate the default connection factory on a particular WebLogic Server, you must select the Enable Default JMS Connection Factories check box when configuring the WebLogic Server.	None required. This is a configuration requirement. For more information, see "Server --> Services --> JMS" in the Administration Console Online Help.
Connections	When closing a connection, the call blocks until outstanding synchronous calls and asynchronous listeners have completed.	None required.
Sessions	When closing a session, the call blocks until outstanding synchronous calls and asynchronous listeners have completed.	None required.
Message Consumers	If multiple topic subscribers are defined in the same session for the same topic, each consumer will receive its own copy of a message.	None required.
	When closing a message consumer, the call blocks until the method call completes and any outstanding synchronous applications are cancelled.	None required.
	In order to comply with the JMS specification, if the close() method is called from within an onMessage() method, the application will hang unless the Allow Close In OnMessage check box is selected when configuring the connection factory. If the acknowledge mode is AUTO_ACKNOWLEDGE, the current message will still be automatically acknowledged.	None required. This is a configuration requirement. For more information, see "JMS Connection Factory Tasks" in the Administration Console Online Help.
Message Header Field	The JMSMessageID header field format has changed.	If you wish to access existing messages using the JMSMessageID, you may need to run one of the following weblogic.jms.extensions.JMSHelper methods to convert between WebLogic pre-JMS 5.1 and JMS 6.x JMSMessageID formats. To convert from pre-5.1 to 6.x JMSMessageID format: public void oldJMSMessageIDToNew( String id, long timeStamp ) throws JMSException To convert from 6.1 to pre- 6.1 JMSMessageID format: public void newJMSMessageIDToOld( String id, long timeStamp ) throws JMSException
Destinations	The createQueue() and createTopic() methods do not create destinations dynamically, only references to destinations that already exist given the vendor-specific destination name.	Update any portion of code that uses createQueue() or createTopic() to dynamically create destinations using the following JMSHelper class methods, respectively: createPermanentQueueAsync() and createPermanentTopicAsync(). For example, if your code used the following method to dynamically create a queue: queue=qsession.createQueue(queueName); You should modify the code to dynamically create a queue, as described in the sample findQueue() method in Using the JMSHelper Class Methods. For more information, see Creating Destinations Dynamically.
	When creating temporary destinations, you must specify a temporary template.	None required. This is a configuration requirement. For more information, see "JMS Template Tasks" in the Administration Console Online Help.
	You must be the owner of the connection in order to create a message consumer for that temporary destination.	When creating a message consumer on a temporary destination, ensure that you are the owner of the connection.
Durable Subscribers	You no longer need to manually create JDBC tables for durable subscribers. They are created automatically.	None required.
	There is no limit on the number of durable subscribers that can be created.	None required.
	When defining a client ID programatically, it must be defined immediately after creating a connection. Otherwise, an exception will be thrown and you will be unable to make any other JMS calls on that connection.	Ensure that the setClientID() method is issued immediately after creating the connection. For more information, refer to Defining the Client ID.
Session Pools	Session pool factories, session pools, referenced connection factories, referenced destinations, and associated connection consumers must all be targeted on the same JMS server.	Ensure that all objects are targeted on the same JMS server.
Session Pools	The SessionPoolManager and ConnectionConsumerManager interfaces that were published as part of the WebLogic JMS version 5.1 Javadoc have been removed from the version 6.x and later Javadoc, as they are system interfaces and should not be used within client applications.	If used, remove any references to these objects from the client application.
Transactions	To combine JMS and EJB database calls within the same transaction, a two-phase commit (2PC) license is required. In previous releases of WebLogic Server, it was possible to combine them by using the same database connection pool.	None required.
Transactions	Recovering or rolling back received queue messages makes them available to all consumers on the queue. In previous releases of WebLogic Server, rolled back messages were only available to the session that rolled back the message, until that session was closed.	None required.

The following table lists the changes in existing feature functionality from WebLogic Server 6.0, and also indicates any code changes that might be required as a result. For additional information pertaining to the JMS Specification's change history, see Chapter 11, "Change History," of Sun Microsystem's JMS Specification

Category	Description	Code Modification
Connection Factories	For the Acknowledge Policy attribute in the Administration Console, the new default value of All is a work-around to accommodate a change in the JMS Specification. This new default setting represents a change from prior versions of JMS, which internally defaulted to Previous, and which did not appear as an option in the Administration Console. As the message acknowledge policy for the connection factory, the Acknowledge Policy attribute only applies to implementations that use the CLIENT_ACKNOWLEDGE mode for a non-transacted session. All — acknowledge all messages ever received by a given session, regardless of which message calls the acknowledge method. Previous — acknowledge all messages received by a given session, but only up to and including the message that calls the acknowledge method. For more information on message acknowledge modes, refer to Non-transacted Session. Note: For connection factories used by MDBs (message-driven beans), always set the Acknowledge Policy field to Previous. Although the default MDB connection factory already does this, foreign connection factories may not.	If you want to acknowledge only previously received messages, up to and including the message that calls the acknowledge method, change the default Acknowledge Policy setting from All to Previous via the JMS --> Connection Factory --> General tab in the Administration Console.
Destinations	In WLS 6.0, the JMS documentation correctly specifies values of default, true, and false for the StoreEnabled attribute of the JMSDestinationMBean, even though the software allowed for mixed case characters. version 6.1 or later, however, requires all lowercase characters for the StoreEnabled settings.	None required. This is a configuration requirement. For more information, see "JMS Template Tasks" in the Administration Console Online Help.

Category

Description

Code Modification

Connection Factories

For the Acknowledge Policy attribute in the Administration Console, the new default value of All is a work-around to accommodate a change in the JMS Specification. This new default setting represents a change from prior versions of JMS, which internally defaulted to Previous, and which did not appear as an option in the Administration Console.

As the message acknowledge policy for the connection factory, the Acknowledge Policy attribute only applies to implementations that use the CLIENT_ACKNOWLEDGE mode for a non-transacted session.

All — acknowledge all messages ever received by a given session, regardless of which message calls the acknowledge method.

Previous — acknowledge all messages received by a given session, but only up to and including the message that calls the acknowledge method.

For more information on message acknowledge modes, refer to Non-transacted Session.

Note: For connection factories used by MDBs (message-driven beans), always set the Acknowledge Policy field to Previous. Although the default MDB connection factory already does this, foreign connection factories may not.

If you want to acknowledge only previously received messages, up to and including the message that calls the acknowledge method, change the default Acknowledge Policy setting from All to Previous via the JMS --> Connection Factory --> General tab in the Administration Console.

Destinations

In WLS 6.0, the JMS documentation correctly specifies values of default, true, and false for the StoreEnabled attribute of the JMSDestinationMBean, even though the software allowed for mixed case characters. version 6.1 or later, however, requires all lowercase characters for the StoreEnabled settings.

None required. This is a configuration requirement. For more information, see "JMS Template Tasks" in the Administration Console Online Help.

This release of WebLogic Server supports Sun Microsystem's JMS Specification. In order to use your existing JMS applications, you must first confirm your version of WebLogic server, and then perform the appropriate porting procedures provided in this section.

Before beginning the porting procedure, you should check the following list to confirm whether porting is support for your version of WebLogic Server JMS, and to find out whether special porting rules apply to that release:

Before you can use an existing WebLogic JMS 6.x application, you must port the WebLogic Server versions 4.5 and 5.1 configuration and message data as follows:

Before you can use an existing WebLogic JMS 6.x application, you must port the WebLogic Server 6.0 configuration and message data as follows

All WebLogic JMS 6.x applications are supported in version 7.0. However, if you want your applications to take advantage of the new highly available JMS features, you will need to configure your existing physical destinations (queues and topics) to be part of a single distributed destination set.

For more information on using JMS distributed destinations, see "Using Distributed Destinations" in Programming WebLogic JMS.

Once the porting is complete, the old JDBC database tables should be removed using the utils.Schema utility, described in detail in JDBC Database Utility.

During porting, a DDL file is generated and stored in the local working directory. The DDL file is named drop_<jmsServerName>_oldtables.ddl, where <jmsServerName> specifies the name of the JMS server. To delete the JDBC database stores, you pass the resulting DDL file as an argument to the utils.Schema utility.

For example, to delete the old JDBC database store from a JMS server named MyJMSServer, run the following command: