Upgrade Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

The Upgrade Process

This document provides information on upgrading from WebLogic Integration 8.1 to WebLogic Integration 9.2 or 9.2 MP1. Topics discussed include:



Before beginning the upgrade process, read Upgrading WebLogic Application Environments. This guide describes the procedures to upgrade your application environment to WebLogic 9.2. An application environment includes applications, the WebLogic domains in which they are deployed, any application data associated with the domain, and may include external resources, such as database servers, firewalls, load balancers, and LDAP servers.


Upgrading Your WebLogic Integration Domain to 9.2

WebLogic Integration 9.2 Upgrade Wizard allows you to upgrade domains created only in WebLogic Integration 8.1 SP4, 8.1 SP5, 8.1 SP6, 8.5, 8.5 SP5 and 8.5 SP6 (also referred to as 8.1.x and 8.5.x in this document).

At a high-level, the steps performed by the wizard during a domain upgrade are as follows:

The PointBase related environment settings are carried over to the upgraded domain scripts, setDomainEnv.cmd and setDomainEnv.sh.

You may encounter an error in Linux while running the upgrade script. The steps to fix this error are as follows:

  1. Go to /etc
  2. Rename ant.conf to ant.conf_old. This file contains the default ANT_HOME and JAVA_HOME for the system which cannot be overwritten by . ./setDomainEnv.sh
  3. Follow and complete the instructions in $WL_HOME/integration/upgrade/README.txt

For more information on the domain upgrade process and things you need to keep in mind during upgrade, see Upgrading a WebLogic Domain available at the following URL: http://download.oracle.com/docs/cd/E13179_01/common/docs92/upgrade/upgrade_dom.html


Upgrading Applications to WebLogic Integration 9.2

WebLogic Integration 9.2 provides a set of utilities that allow you to upgrade your 8.1.x or 8.5.x includes applications to 9.2. This section describes how to upgrade applications built using WebLogic Integration.

Note that during upgrade, the logic and intent of the application is not altered. WebLogic Integration simply migrates the code to make it compatible with 9.2. This would involve changes such as making the applications compatible with the Eclipse framework and converting Javadoc annotations to JSR 175 compliant annotations, among others.

Before You Begin

Complete the following tasks:

The Upgrade Process

Application upgrade is a three-step process:

You can choose to upgrade your user applications using the Import Wizard or the Command Line utility—both provided by BEA Workshop for WebLogic Platform. Alternatively, you could use an Ant task. The subsequent sections describe these methods.


Using the Import Wizard to Upgrade Your Application

You can use the Import Wizard provided by BEA Workshop for WebLogic Platform to upgrade your applications to 9.2. The wizard does not alter the logic and intent of the existing 8.1 applications, nor extract the applications from any source repository. It migrates the 8.1 source artifacts into the 9.2 source and project model. However, it retains the 8.1 Javadoc annotations as they do not require any special processing in 9.2. These annotations are also retained to facilitate any manual processing that may be required after upgrading the application.

The following are some of the tasks executed by the import wizard:

Note: When you upgrade an 8.x application with an EJB or non-web or non-utility project that uses JPD or Process Proxy to make an RMI call to the JPD, do not add a process facet to all the non-web or non-utility projects. Instead, add the Library (Process Libraries) to the project's java build path as follows:

Using the Command Line to Upgrade Applications

BEA Workshop for WebLogic Platform also provides a command line utility that converts the entire application to work with WebLogic Integration 9.2.

The utility does not check out or delete files. It also does not check in the newly upgraded files automatically. It just copies the essential files over to the WebLogic Workshop 9.2 workspace for migration.

Note: When you run the command line utility, use JRE 1.5. Ensure that the classpath includes <%ECLIPSE_HOME%>/startup.jar.

The command to upgrade your application is as follows:

java -cp %ECLIPSE_HOME%/startup.jar 
-application com.bea.wlw.upgrade.upgradeStarter
-pluginCustomization %PREFS_FILE%


Refers to the path to the directory containing the startup.jar. The default for BEA Workshop for WebLogic Platform is:
Refers to the location of WebLogic Server root folder. By default, this is:
Refers to the application that requires the upgrade. Replace WORK_FILE with the work file name corresponding to the WebLogic Workshop 8.1 that you want to upgrade.
-application com.bea.wlw.upgrade.upgradeStarter
Refers to the Eclipse plug-in extension point used to execute this command.
Refers to the name of the target workspace where you want the upgraded application to reside. This can be any directory in which you want the version 9.2 application files generated.
[-pluginCustomization PREFS_FILE]
Specifies a properties file used to set options for the upgrade. Replace the PREFS_FILE with the name of a properties file containing a number of key-value pairs. The possible properties are:
  • application refers to the plug-in extension point to execute at runtime.
  • weblogic.home refers to the location of the WebLogic Server root directory.
  • data refers to the name of the target workspace where the upgraded application resides. The name of the parameter is provided by Eclipse and it cannot be overwritten.
  • wlw.application refers to the name of the application work file.
  • pluginCustomization refers to the name of a properties file containing a number of key-value pairs.
Optional Parameters
If you do not specify this attribute, the default is false. In this case, the upgrader tries to continue after an error. When it is set to true, the upgrade process fails when it encounters any error. These errors are listed in the log file.
This attribute indicates the message level for logging. If you do not specify this attribute, the upgrader logs all messages. You can specify the following values for this attribute:
  • INFO: Displays all messages. This is the default value.
  • WARNING: Displays warning, error, and fatal messages, and suppresses informational messages.
  • ERROR: Displays only error and fatal messages.
If you do not specify this attribute, the default to false. When it is set to true, the upgrade process migrates the JSP files to their new Beehive annotation.
When you set this attribute to false, the upgrade copies the web application libraries to WEB-INF/lib. The upgrade uses J2EE shared libraries by default.
Set this attribute to true, to generate the upgrade report. The default setting is false, and with this setting both the report and upgrade are performed.
com.bea.wlw.upgrade/upgradeHarnessLogFile=<log file location>
Use this attribute to specify the location of the upgrade log file. The default value is <workspace location>/.metadata/upgrade.log
Use this attribute to specify whether an existing project is overwritten in the event of a conflict in project name. The default value is false.
This attribute is optional. Use this attribute to specify a prefix to append to all imported projects.
com.bea.wlw.upgrade/upgraderPrefMoveResourceBundle = true/false
Use this attribute to specify whether files with the .properties extension are copied or moved from the web content folder to the source file folder. The default value is false.

Using an Ant task to Upgrade Your Applications

You can use the Ant task to upgrade to WebLogic Integration 9.2.

The command line upgrade contains an Ant task. You can locate the class of the Ant task in the wlw-upgrade.jar, deployed in the ./<WORKSHOP_HOME>/eclipse/plugins/com.bea.wlw.upgrade_9.2.0 folder.

Note: When you run the Ant task, ensure that the <%ECLIPSE_HOME%>/startup.jar is on the classpath of the task, as specified by the classpathref attribute in the following sample Ant task.

A following sample shows how you can invoke an Ant task:

<target name="workshopUpgrade">

<echo message="${workshop.home}/eclipse"/> 
<path id="eclipse.classpath">
<fileset dir="${workshop.home}/eclipse/plugins" 
<taskdef name="upgradeTask" 
<upgradeTask data=%WORKSPACE%



The Eclipse workspace into which the WebLogic Integration 8.x application is imported and upgraded.
The Eclipse directory containing the startup.jar.
Location of the root folder of WebLogic Server.
Location of an optional preference file used during import or upgrade.
Location of the work file for WebLogic Workshop 8.x application to be imported or upgraded.

Understanding the Upgrade Log

WebLogic Integration 9.2 generates a log of the upgrade changes, errors, and warnings, irrespective of the upgrade process you choose. If you use the wizard, this log is displayed in a dialog that you can review before the process is complete.

The log file is generated after the upgrade is completed and it is saved as:


A log message in the file appears as follows:

!SUBENTRY 1 com.bea.wlw.upgrade severity_level date time

!MESSAGE Upgrade-related message.

The severity level contains two numbers with the same meaning. The date and time entries specify when the upgrade was attempted. The upgrade-related message describes the action, the warning logged, or the error that occurred. The following are two log entries:

!SUBENTRY 1 com.bea.wlw.upgrade 2 2 2006-02-27 17:17:53.687

!MESSAGE The 9.2 control context only supports a subset of the 8.1 control context APIs. Please see the Workshop for WebLogic upgrade documentation for more information.

!SUBENTRY 1 com.bea.wlw.upgrade 1 1 2006-02-27 17:17:53.687

!MESSAGE The import "com.bea.control.JwsContext" needs to be updated.

Outages During or After Deployment

You might encounter certain outages while trying to deploy your upgraded application. For information on outages, see the Known Limitations section, in WebLogic Integration Release Notes.

Manual Changes Required After Upgrade

Known Limitations for Domain Upgrade

When you are upgrading stateful JPD applications from WebLogic Integration or to you could encounter the following error:

java.io.InvalidClassException: javax.xml.namespace.QName; local class 
incompatible: stream classdesc serialVersionUID = 4418622981026545151, local class serialVersionUID = -9120448754896609940

This issue is due to a known bug in the JDK.

After upgrading the domain, before you restart the server, the suggested solution for systems running on:


Testing the Upgrade

After the upgrade is complete, you can optionally build and deploy the upgraded application to verify if the upgrade is successful. You can ensure that the required files have been moved or are available in the correct locations as follows:

  Back to Top       Previous  Next