Migrating WebLogic JMS Applications


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	e-docs \| Site Map \| Search \| Contact \| Glossary \| WebLogic Server Documentation

Programming WebLogic JMS: Previous topic \| Next topic \| Contents \| Index

The following sections describe how to migrate WebLogic JMS applications:

Existing Feature Functionality Changes

Changes in existing feature functionality have been made in order to comply with the JavaSoft JMS Specification version 1.0.2. and the latest JMS API - Errata.

The following table lists the changes in existing feature functionality from WebLogic Server Version 5.1, and also indicate any code changes that might be required as a result. For additional information pertaining to the Version 1.0.2 change history, see Chapter 11, "Change History," of the JavaSoft JMS Specification Version 1.0.2.

Table 6-1 Existing Feature Functionality Changes

Category
Description
Code Modification

Connection Factories

The following two default connection factories have been deprecated: javax.jms.QueueConnectionFactory and javax.jms.TopicConnectionFactory.

These connection factories are still defined and usable in this release for backwards compatibility.

WebLogic JMS 6.0 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 checkboxes when configuring the connection factory.

For more information about defining connection factories, see "JMS Connection Factories" in the Administration Console Online Help.

In order to instantiate the default connection factory on a particular WebLogic Server, you must select the Enable Default JMS Connection Factories checkbox when configuring the WebLogic Server.

None required. This is a configuration requirement. For more information, see "Server" 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 checkbox 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 Factories" 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 JMS 6.0 and pre-6.0 JMSMessageID formats.

To convert from pre-6.0 to 6.0 JMSMessageID format:

public void oldJMSMessageIDToNew(
String id,
long timeStamp
) throws JMSException

To convert from 6.0 to pre- 6.0 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 on the JMSHelper classes, 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 Templates" 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.

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.0 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.

In WebLogic Server 6.0 SP2 or higher, for the QueueConnection and TopicConnection classes, the MaxMessages argument in the createConnectionConsumer method requires a specific value for the amount of messages to be reserved on the server.

Therefore, MaxMessages will be parsed as follows:

-1 - The same as the default value, which is 10.

>0 - Positive integers require no conversion.

0 - An invalid value that will generate a JMSException.

<-1 - An invalid value that will generate a JMSException.

In the createConnectionConsumer method, ensure that the value of the MaxMessages argument is set to either -1 (the default) or a positive integer.

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.

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.

Category	Description	Code Modification
Connection Factories	The following two default connection factories have been deprecated: javax.jms.QueueConnectionFactory and javax.jms.TopicConnectionFactory. These connection factories are still defined and usable in this release for backwards compatibility. WebLogic JMS 6.0 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 checkboxes when configuring the connection factory. For more information about defining connection factories, see "JMS Connection Factories" in the Administration Console Online Help.
In order to instantiate the default connection factory on a particular WebLogic Server, you must select the Enable Default JMS Connection Factories checkbox when configuring the WebLogic Server.	None required. This is a configuration requirement. For more information, see "Server" 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 checkbox 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 Factories" 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 JMS 6.0 and pre-6.0 JMSMessageID formats. To convert from pre-6.0 to 6.0 JMSMessageID format: public void oldJMSMessageIDToNew( String id, long timeStamp ) throws JMSException To convert from 6.0 to pre- 6.0 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 on the JMSHelper classes, 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 Templates" 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.
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.0 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.
In WebLogic Server 6.0 SP2 or higher, for the QueueConnection and TopicConnection classes, the MaxMessages argument in the createConnectionConsumer method requires a specific value for the amount of messages to be reserved on the server. Therefore, MaxMessages will be parsed as follows: -1 - The same as the default value, which is 10. >0 - Positive integers require no conversion. 0 - An invalid value that will generate a JMSException. <-1 - An invalid value that will generate a JMSException.	In the createConnectionConsumer method, ensure that the value of the MaxMessages argument is set to either -1 (the default) or a positive integer.
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.
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.

Migrating Existing Applications

WebLogic Server 6.0 supports the JavaSoft JMS Specification version 1.0.2. and the latest JMS API - Errata. In order to use your existing JMS applications, you must first confirm your version of WebLogic server, and then perform the following migration procedure outlined in this section.

Before You Begin

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

Version 4.5.1 - Migration is supported only for SP14. Customers running all service packs should contact BEA Support.
Version 5.1 - Customers running with SP07 or SP08 should contact BEA Support before migrating existing JDBC stores to version 6.0.
- In order to migrate object messages, the object classes need to be in the version 6.0 server classpath.

Migration Steps

Before you can use an existing JMS application, you must migrate the configuration and message data as follows:

Properly shut down the old version of WebLogic Server before beginning the migration process.
Warning: Abruptly stopping the old version of WebLogic Server while messaging is still in process may cause problems during migration. Processing should be inactive before shutting down the old server and beginning the migration to WebLogic Server version 6.0.
Upgrade the WLS environment, as described in Installing WebLogic Server.
Migrate configuration information using the configuration conversion facility.
During the configuration migration, the following default queue and topic connection factories are enabled:
- javax.jms.QueueConnectionFactory
- javax.jms.TopicConnectionFactory
- weblogic.jms.ConnectionFactory
  The first two connection factories are deprecated, but they are still defined and usable for backwards compatibility. For information on the new default connection factory, see the table Existing Feature Functionality Changes.
  
  The JMS administrator will need to review the resulting configuration to ensure that the conversion meets the needs of the application.
  
  In this case, all of the JMS attributes will be mapped to a single node, as in Version 5.1.
  
  Note: In Version 6.0, JMS queues are defined during configuration, and no longer saved within database tables. Message data and durable subscriptions are stored either in two JDBC tables or via a directory within the file system.
Prepare for automatic migration of existing JDBC database stores.
1. Make a backup of the existing JDBC database.
2. Ensure that the migrated configuration information (see step 2) contains a JDBC database store with exactly the same attributes as the existing store, and that the new JMS servers that use the store define the same destinations and corresponding destination attributes as the existing JMS servers.
3. If the new JDBC database store already exists, ensure that it is empty.
  The new JDBC database store will be created during the automatic migration, if required.
4. Ensure that there is twice the amount of disk space required by the JDBC database store available on the system.
  Both the existing and new database information will exist on disk while the migration is performed, doubling the space requirements. Once migration is complete, you can delete the old JDBC database stores, as described in Deleting JDBC Database Stores.
Update any existing code, as required, to reflect the feature functionality changes described in Existing Feature Functionality Changes.

When you initially boot up the WebLogic Server, the existing JDBC database stores will be migrated automatically. If the automatic migration fails for any reason, the automatic migration will be re-attempted the next time the WebLogic Server boots.

Deleting JDBC Database Stores

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

During migration, 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, execute the following command:

java utils.Schema jdbc:weblogic:oracle weblogic.jdbc.oci.Driver -s server -u user1 -p foobar -verbose drop_MyJMSServer_oldtables.ddl

For more information on the utils.Schema utility, see JDBC Database Utility.

Table 6-1 Existing Feature Functionality Changes