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:
Adds resources to support advanced Web services including the file store, WseeFileStore, and the JMS server, WseeJmsServer, and its associated JMS module.
Updates and adds JMS and JDBC resources to support WebLogic Platform applications.
Removes user-defined applications that have been deployed in the domain.
Removes deprecated applications that have been deployed in the domain.
Removes the JWSQueueTransport EJB, if it is present in the domain.
Adds shared library modules to support Personalization (P13n) applications. See also WebLogic Integration 9.2.1 library modules.
Adds External Event Generators.
Adds the SQLAuthenticator security provider to the domain.
Note:
Users portaladmin and weblogic are added to the SQLAuthenticator security provider. You can remove these users from the DefaultAuthenticator security provider after the domain is upgraded.
Updates the following, if any data source is configured to use the PointBase database:
The database is automatically loaded in embedded mode and upgraded to PointBase v5.1.
The pointbase.ini file is updated to set database.home, documentation.home and pbembedded.lic for PointBase v5.1.
The database files are renamed from workshop to weblogic_eval and the associated datasource JDBC driver URLs accordingly fixed.
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:
Go to /etc
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
Follow and complete the instructions in $WL_HOME/integration/upgrade/README.txt
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:
Migrate all your applications to 8.1 (SP4, SP5, or SP6) or to 8.5 (or higher). For information on upgrading your older applications to these versions, see WebLogic Integration 8.1 Upgrade Guide.
Undeploy all version 8.1 applications before you upgrade the server.
Verify that the WebLogic domain is not running.
Check out your version 8.1.x or 8.5.x application source files that need to be upgraded.
Fix errors reported in the log to ensure your applications run in WebLogic Integration 9.2 without any problem.
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.
Notes:
The upgrader does not support upgrade of user-developed helper source files such as Helper classes and 7.x controls.
If you have specified any custom classloader hierarchies in addition to the standard classloader inversion hierarchy enforced by the 8.x process application, the application upgrader will not recognize these hierarchies. Instead, it generates a standard classloader inversion hierarchy that a WebLogic Integration 9.2 process application requires. You will then need to re-create your custom class loader hierarchy after the application upgrade is complete and then specify the classloader hierarchy in the weblogic-application.xml file.
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:
Imports upgraded source code to the WebLogic Integration 9.2 workspace which you have specified.
Upgrades 8.1.x or 8.5.x annotations to WebLogic Integration 9.2.
Migrates your WebLogic Integration 8.1.x or 8.5.x source artifacts to WebLogic Integration 9.2. This involves the following steps:
Converts WebLogic Integration 8.1.x or 8.5.x project types to WebLogic Integration 9.2.
Optionally moves libraries from the 8.1.x or 8.5.x application Libraries directory to a new EAR project in the upgraded application.
Moves JSP files into a WebContent directory.
Upgrades Beehive NetUI JSP tags to WebLogic Integration 9.2.
Moves XSD files that are in a Schema project into a Schemas directory of the Utility project.
Moves Java packages and source into a src directory.
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:
Select ProjectPropertiesJava build.
Select the Libraries tab, click Add Library, and select Process Libraries.
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:
Refers to the path to the directory containing the startup.jar. The default for BEA Workshop for WebLogic Platform is:
BEA_HOME/workshop92/eclipse
-Dweblogic.home=WL_HOME
Refers to the location of WebLogic Server root folder. By default, this is:
BEA_HOME/weblogic92
-Dwlw.application=WORK_FILE
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.
-data WORKSPACE
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.
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.
com.bea.wlw.upgrade/upgradeHarnessMessageLevel
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.
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.
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:
The Eclipse workspace into which the WebLogic Integration 8.x application is imported and upgraded.
ECLIPSE_HOME
The Eclipse directory containing the startup.jar.
WL_HOME
Location of the root folder of WebLogic Server.
PREFS_FILE
Location of an optional preference file used during import or upgrade.
WORK_FILE
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:
<UPGRADE_WORKSPACE_HOME>\.metadata\upgrade.log
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:
!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.
!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
After upgrading the 8.1 domain, ensure that you have set the security policies on the Compatibility 8.1.x Task Plan and enabled the 'Anonymous' role in the Create Policy. Use the Worklist Administration Console (the default authorization provider) to set the Create Policy for the Compatibility 8.1.x task plan. If you are using a third-party authorizer, use the related third-party client tools to set the policy.
If you are directly using MFL-derived XMLBeans types for internal use or during conversion of data from non-XML to XML as an intermediate form, you need to manually specify namespaces in the element constructors of these XQuery transformations upgraded from 8.x.
Known Limitations for Domain Upgrade
When you are upgrading stateful JPD applications from WebLogic Integration 9.2.0.0 or 9.2.1.0 to 9.2.2.0 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:
Windows is as follows:
Add the flag: -Dcom.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0 to the JAVA_OPTIONS variable in the startWeblogic.cmd file, located under the domain_home\bin directory to ensure a successful running process. Modify set JAVA_OPTIONS=%SAVE_JAVA_OPTIONS%
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:
JPD Annotation Processor:
The project and component beans that JPD requires must be available in the build/EJB directory.
The wli-process.xml, wli-subscriptions.xml, and wlw-manifest.xml should be available in the build/processoutput/WEB-INF/directory.
Channel Builder contains the wli-channels.xml file in the earProject/ear/META-INF/ directory.
