Programming WebLogic JMS
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 Microsystems' 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.
Two default connection factories have been deprecated. The JNDI names for these factories are: 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: You can also specify user-defined connection factories using the Administration Console. Note: Using the default connection factories, you have no control over the WebLogic server on which the connection factory may be deployed. However, you can can enable and/or disable the default connection factories on a per WebLogic Server basis. To deploy a connection factory on a particular WebLogic Server or cluster, create a new connection factory and specify the appropriate WebLogic Server target. |
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:
You should modify the constant to use a new user-defined connection factory, for example:
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 using connection factories, see ConnectionFactory Object. For more information about defining connection factories, see "JMS Connection Factory Tasks" in the Administration Console Online Help. |
|
In order to instantiate the default connection factories on a particular WebLogic Server, you must select the Enable Default JMS Connection Factories check box on the Server --> Services --> JMS node tab 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. |
|
When closing a connection, the call blocks until outstanding synchronous calls and asynchronous listeners have completed. |
||
When closing a session, the call blocks until outstanding synchronous calls and asynchronous listeners have completed. |
||
If multiple topic subscribers are defined in the same session for the same topic, each consumer will receive its own copy of a message. |
||
When closing a message consumer, if the consumer is asynchronous then the call blocks until outstanding calls to the |
||
In order to comply with the JMS specification, if the |
None required. This is a configuration requirement. For more information, see "JMS Connection Factories" in the Administration Console Online Help. |
|
If you wish to access existing messages using the To convert from pre-5.1 to 6.x
To convert from 6.1 to pre- 6.1
|
||
The |
Update any portion of code that uses For example, if your code used the following method to dynamically create a queue:
You should modify the code to dynamically create a queue, as described in the sample 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 Server --> Configuration --> General" in the Administration Console. |
|
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. |
|
You no longer need to manually create JDBC tables for durable subscribers. They are created automatically. |
||
There is no limit on the number of durable subscribers that can be created. |
||
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 |
|
Session pool factories, session pools, referenced connection factories, referenced destinations, and associated connection consumers must all be targeted on the same JMS server. |
None required. This is a configuration requirement. Ensure that all objects are targeted on the same JMS server. For more information, see "JMS Server Tasks" in the Administration Console. |
|
The |
If used, remove any references to these objects from the client application. |
|
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. |
||
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. |
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 Microsystems' JMS Specification.
For the Acknowledge Policy attribute in the Administration Console, the new default value of As the message acknowledge policy for the connection factory, the Acknowledge Policy attribute only applies to applications that use the
For more information on message acknowledge modes, refer to Non-Transacted Session. Note: For connection factories used by MDBs, always set the Acknowledge Policy field to |
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 |
|
In WLS 6.0, the JMS documentation correctly specifies values of |
None required. This is a configuration requirement. For more information, see "JMS Templates" in the Administration Console Online Help. |
This release of WebLogic Server supports Sun Microsystems' 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:
CLASSPATH
. Before you can use an existing WebLogic JMS 5.1 application, you must port the WebLogic Server 5.1 configuration and message data to version 8.1 as follows:
Warning: Abruptly stopping the old version of WebLogic Server while messaging is still in process may cause problems during porting. Processing should be inactive before shutting down the old server and beginning the porting to WebLogic Server 8.1.
During the configuration porting, the following default queue and topic connection factories are enabled:
javax.jms.QueueConnectionFactory
javax.jms.TopicConnectionFactory
weblogic.jms.ConnectionFactory
weblogic.jms.XAConnection Factory
The first two connection factories are deprecated, but they are still defined and usable for backwards compatibility. For information on the new default connection factories, see ConnectionFactory Object.
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 versions 6.0 or later, 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.
Both the existing and new database information will exist on disk while the porting is performed, doubling the space requirements. Once porting is complete, you can delete the old JDBC database stores, as described in Deleting JDBC Database Stores.
Note: If the automatic porting fails for any reason, the automatic upgrade will be re-attempted the next time the WebLogic Server boots.
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:
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.
Before you can use an existing WebLogic JMS 6.0 application, you must port the WebLogic Server 6.0 configuration and message data to version 8.1 as follows
Warning: Abruptly stopping the old version of WebLogic Server while messaging is still in process may cause problems during porting. Processing should be inactive before shutting down the old server and beginning the porting to WebLogic Server 8.1.
All WebLogic JMS 6.1 and 7.0 applications are supported in version 8.1. However, if you want your applications to take advantage of the highly available Distributed Destination feature, you 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.