Upgrade Guide

The Upgrade Process

This document provides information on upgrading from WebLogic Integration 8.1.x, 8.5.x, 9.x, or 10.x to Oracle WebLogic Integration 10g Release 3 (10.3.1). Topics discussed include:

Prerequisites

Before beginning the upgrade process, go through the Upgrading Oracle WebLogic Application Environments Guide. This guide describes the procedures to upgrade your application environment to Oracle WebLogic 10g Release 3 (10.3.1). 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 from Oracle WebLogic Integration 10g Release 3 (10.3) to Oracle WebLogic Integration 10g Release 3 (10.3.1)

Notes:

Before you upgrade from Oracle WebLogic Integration 10g Release 3 (10.3) to Oracle WebLogic Integration 10g Release 3 (10.3.1) using the Upgrade Installer, you need to use Smart Update to remove the SWX2 patch. The SWX2 patch has been replaced with the AWX4 patch, which is automatically applied when you run the upgrade installer.
Take a back up of your WLI environment before you upgrade. Uninstall of WLI 10g Release 3 (10.3.1) is not supported. If after upgrading to Maintenance Pack 1 you want to revert to your previously installed version of Oracle WebLogic Integration, you must restore your WLI environment from backup.
Take a back up of the WLI 10.3 sample domain before upgrading from WLI 10g Release 3 (10.3) to WLI 10g Release 3 (10.3.1) using the Upgrade Installer. This is because the Upgrade Installer overwrites the existing sample domain during the upgrade process.
After you upgrade from WLI 10g Release 3 (10.3) to WLI 10g Release 3 (10.3.1) using the Upgrade Installer, you need to manually upgrade any user-defined domains before starting the server.
Deployment error occurs when you start the server after you upgraded from WLI 10g Release 3 (10.3) to WLI 10g Release 3 (10.3.1) using the Upgrade Installer, but did not upgrade the domain. Make sure that you upgrade the WLI 10g Release 3 (10.3) domain before you start the server.
Errors occurs when you deploy the adapter resource files after you upgraded from WLI 10g Release 3 (10.3) domain to WLI 10g Release 3 (10.3.1) domain because the WLI_HOME parameter is removed from the setDomainEnv file.

Note: For Windows systems, include the following in the setDomainEnv.cmd file:

Note: set WLI_HOME=<WLI installation directory>

Note: for %%i in ("%WLI_HOME%") do set WLI_HOME=%%~fsi

Note: For Linux and Solaris systems, include the following in the setDomainEnv.sh file:

Note: WLI_HOME="<WLI installation directory>"

Note: export WLI_HOME

After you remove the patch, run the Upgrade installer to upgrade from Oracle WebLogic Integration 10g Release 3 (10.3) to Oracle WebLogic Integration 10g Release 3 (10.3.1). In the Upgrade Installer wizard, specify the BEA_HOME (WLI install location) of the WLI instance that you want to upgrade, confirm the various install locations and click Finish.

You can now upgrade the domains, applications, and any other artifacts.

Upgrading Your WebLogic Integration Domain to Oracle WebLogic Integration 10g Release 3 (10.3.1)

The Oracle WebLogic Upgrade Wizard allows you to upgrade domains created only in WebLogic Integration 8.1.x and higher. The WLI domain upgrade plug-in supports cluster enabled domains.

Domain Upgrade from 8.1.x to 10g Release 3 (10.3.1)

At a high-level, the steps performed by Oracle WebLogic Integration 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.
Adds Beehive shared library modules to support Oracle Workshop for WebLogic product applications.
Adds shared library modules to support Personalization (P13n) applications.
Adds shared library modules to support WebLogic applications.
Updates and adds JMS and JDBC resources to support WebLogic applications.
Removes user-defined applications that have been deployed in the domain for applications updated from WLI 8.1.x or 8.5.x to Oracle WebLogic Integration 10g Release 3 (10.3.1) . You will have to upgrade the source files and compile and redeploy the applications.
Removes deprecated applications that have been deployed in the domain.
Removes the JWSQueueTransport EJB, if it is present in the domain.
Adds WebLogic Personalization (P13n) JDBC data sources and connection pools.
Adds external Event Generators.
Updates JMS destinations.
Does not support binary compatibility for WLI 8.1.x or 8.5.x.
Adds the SQLAuthenticator security provider to the domain.

Note: The 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 data source JDBC driver URLs accordingly fixed.
The PointBase related environment settings are carried over to the upgraded domain scripts, setDomainEnv.cmd and setDomainEnv.sh.

Domain Upgrade from 9.x or 10.x to 10g Release 3 (10.3.1)

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

Upgrades Beehive shared library modules to support Oracle Workshop for WebLogic product applications.
Upgrades shared library modules to support Personalization (P13n) applications.
Upgrades shared library modules to support WebLogic applications.
Applications are retained as part of the domain and are deployed automatically when you start the Oracle WebLogic Integration 10g Release 3 (10.3.1) domain.
Supports binary compatibility for WLI 9.x and WLI 10.x. The applications created in WLI 9.x or WLI 10.x can be deployed and need not be re-built in Oracle WebLogic Integration 10g Release 3 (10.3.1). For more information, see Compatibility Statement for Oracle WebLogic Server.
Supports in-flight process upgrade from WLI 9.x or 10.x to Oracle WebLogic Integration 10g Release 3 (10.3.1). After the domain upgrade, you must run all the long running processes started in the 9.x or 10.x domain, to completion in Oracle WebLogic Integration 10g Release 3 (10.3.1) domain.

For more information on the domain upgrade process and things you need to keep in mind during upgrade, see Upgrading a Oracle WebLogic Domain.

A domain created in production mode, opens in development mode when upgraded from WLI 9.x or 10.x to Oracle WebLogic Integration 10g Release 3 (10.3.1). The work around to update the development domain to a production domain is as follows:

After the domain upgrade, edit the setDomainEnv.cmd file and set PRODUCTION_MODE=true
Before starting the server, set JAVA_VENDOR=Sun (or edit setDomainEnv.cmd to add this after the set WL_HOME=.... line).

The logic of selecting jrockit/Sun JDK in production mode is defined in the BEA_HOME\wlserver_10.3\common\bin\commEnv.cmd file.

Upgrade Modes

The domain upgrade wizard supports the following upgrade modes:

Graphical—For upgrading a domain interactively, the Domain Upgrade Wizard using a graphical user interface.
Silent—You can upgrade a domain silently by specifying upgrade requirements in a file.

The following sections provide instructions for:

Upgrading a Domain in Graphical Mode

The following sections describe how to upgrade a WebLogic domain using the Oracle WebLogic Upgrade Wizard in graphical mode:

Note:

The console from which you are running the Upgrade Wizard in graphical mode must support a Java-based GUI. If you attempt to start the Upgrade Wizard in graphical mode on a system that cannot support a graphical display, the invocation fails and an error message is displayed.

Starting the Oracle WebLogic Upgrade Wizard in Graphical Mode to Upgrade a Domain

To start the Oracle WebLogic Upgrade Wizard in graphical mode and upgrade a WebLogic domain on a Windows platform, choose the Domain Upgrade Wizard option from the Windows Start Menu:

Start > All Programs > Oracle WebLogic > WebLogic Server 10gR3 > Tools > Domain Upgrade Wizard

Note:

You can only use this option if you do not have to customize the environment to specify JDBC driver classes.

To start the Oracle WebLogic Upgrade Wizard in graphical mode and upgrade a WebLogic domain from a Windows command prompt or on a UNIX platform:

Verify that the WebLogic domain is not running.
Review the Important Notes About the Domain Upgrade Process.
Backup the JMS Store, if applicable.
Open a command prompt window (on Windows) or a command shell (on UNIX) and set up the environment as follows:

Add the Oracle WebLogic Server classes to the CLASSPATH environment variable and WL_HOME\server\bin to the PATH environment variable, where WL_HOME refers to the top-level installation directory for Oracle WebLogic Server.
You can use the WL_HOME\server\bin\setWLSenv script to set both variables.
If you use JMS JDBC stores:

Make sure the JDBC driver classes are added to the CLASSPATH environment variable.
Start the corresponding database.

Execute the following script to upgrade your domains.

On Windows: WL_HOME\common\bin\upgrade.cmd
On UNIX: WL_HOME/common/bin/upgrade.sh

The log file will be available in the BEA_HOME/user_projects/upgrade_logs directory.

The following command can also be used to upgrade a domain.

java weblogic.Upgrade [-type domain] [-out file]

Two arguments are optional: -type and -out. Include these arguments if you want to override the default values for the following:

The type of upgrade to be performed. If you do not specify a type with the -type option, a domain upgrade is performed.
The output file in which all standard output (stdout) and error messages are written. If you do not specify a file with the -out option, such messages are written to the command window, and a summary of messages is displayed at the end of the upgrade process.

After you run the command, the Oracle WebLogic Upgrade Wizard opens, as shown in the following figure.

If JMS JDBC stores are used, ensure the corresponding database is running. Note that PointBase databases are automatically started and shut down by the Oracle Domain Upgrade Wizard.
Click Next to proceed to the next window.

Procedure for Upgrading a WebLogic Domain

The following table summarizes the steps in the procedure to upgrade a domain using the Oracle WebLogic Upgrade Wizard.

In this step...

You...

Select WebLogic Version

Select the WebLogic version of the domain that you are upgrading.

Click Next to proceed to the next window.

Select a Domain to Upgrade

Select the directory that contains the WebLogic domain to be upgraded by navigating the local directory hierarchy.

Click Next to proceed to the next window.

Inspect Domain

Review progress of the wizard as it inspects the domain. Progress messages are displayed in the window.

If you attempt to upgrade a domain in which custom security providers are used, without first upgrading those security providers, an error message is displayed and the wizard exits.

If you receive this error message, upgrade the customer security providers, and start the domain upgrade procedure again.

Once the inspection is complete (and if no error is encountered), the wizard advances to the next window automatically.

Select Administration Server

Select a server to function as the Administration Server in the new domain.

Note:

If there is only one server defined in the domain, this window is skipped. This window is displayed only if the domain you are upgrading has multiple servers.

Click Next to proceed to the next window.

Enter Node Manager Credentials

Enter the username and password (and password confirmation) for Node Manager authorization.

For Oracle WebLogic Integration 10g Release 3 (10.3.1), Node Manager requires user and password credentials to be specified for each domain. By default, the username and password are set to weblogic. If you do not use Node Manager, leave the default values unchanged.

Click Next to proceed to the next window.

Select Upgrade Options

Back up current domain (recommended)—If selected, the wizard backs up the original domain directory and stores it in a zip file. This option is selected by default.

Note:

The wizard backs up the domain directory only and does not preserve file permissions. We recommend that you back up the domain and any external application and application database resources in a separate process.

Add log files to backup zip—If selected, log files will be included in the backup zip file. The number and size of log files can be large and you may want to disable this option to exclude them from the backup file. By default, log files are included in the backup file.
Do not set backwards compatibility flags—As of WebLogic Server 9.0, some previously supported behavior has changed to comply with J2EE 1.4. By default, the wizard sets flags to enable the previous behavior in the new domain. If you select this option, these flags are not set for backward compatibility.

Directory Selection Analysis and Optional Tasks

Review progress as the wizard processes the domain information and options provided. Progress messages are displayed in the window.

Once processing is complete, the wizard advances automatically to the next window.

Domain Backup

Review progress of the wizard as it prepares to back up the domain. Progress messages are displayed in the window.

Once processing is complete, the wizard advances automatically to the next window.

Select Directory for Domain Backup

In this window, set values for the following:

Backup directory — Navigate the local hierarchy and select the directory in which you want to save the backup zip file. By default, the original domain directory is used.
Backup filename—Enter the name of the backup file in the text box. The default filename is weblogic-domain-backup-domain.zip, where domain specifies the name of the domain.

Click Next to proceed to the next window.

Backup Domain

Review progress as the wizard backs-up the domain. A progress bar displays the percentage of the backup process that is complete, and progress messages are displayed in the window.

Note:

Backup files created by the wizard need to be protected by the user as they may contain confidential information.

Once the backup process is complete, the wizard advances automatically to the next window.

Restructure Domain Directory

Review progress as the wizard restructures the domain directory. Progress messages are displayed in the window.

Once the process is complete, the wizard automatically advances to the next window.

Upgrade Configuration Settings

Review progress as the wizard upgrades the configuration settings. Progress messages are displayed in the window.

The configuration information is not persisted until a later step.

Once the configuration upgrade is complete, the wizard advances automatically to the next window.

Upgrade Persisted Messages and Transaction Log Formats

Review progress as the wizard upgrades the persisted messages (JMS file and JDBC stores) and transaction (JTA) logs that exist in the domain. A progress bar displays the percentage complete and progress messages are displayed in the window.

Once the persisted message and transaction log upgrade process is complete, the wizard advances to the next window automatically.

Execute Upgrade of Required WebLogic Personalization Components

Review progress as the Wizard updates Personalization components.

Click Next to proceed to the next window.

Upgrade RDBMS Authenticator Security Provider

Specify whether or not the deprecated RDBMSAuthenticator should be replaced by the SQLAuthenticator.

Note:

This window appears only when an RDBMSAuthenticator Security Provider exists in the domain you are upgrading.

Click Next to proceed to the next window.

Prepare WLI Domain Upgrade Plugins

The Wizard will now upgrade Oracle WebLogic Integration-specific resources in the domain.

Click Next to begin the process.

Execute WLI Domain Upgrade Plugins

Review progress as the Wizard upgrades Oracle WebLogic Integration resources in the domain.

Click Next to proceed.

Finalize Domain Upgrade

Review progress of the wizard as it saves the upgraded configuration and deletes any temporary files that were created during the upgrade process. Progress messages are displayed in the window.

Note:

When upgrading remote Managed Servers, the wizard does not persist the configuration information.

Once this process is complete, click Next to proceed to the next window.

Database Upgrade Choice

Specify whether or not you would like to upgrade the domain database before proceeding.

The Wizard does not back up the domain database. You will need to back up your domain database before beginning a domain upgrade.

Select an option and click Next to proceed.

Associate DB Categories with Datasources

The table displays the database categories and their associated data sources. The categories are used with their associated data source to initialize the domain database. If a data source appears as undefined, you can update the category with the correct data source. If the data source remains undefined, it will be skipped and not upgraded. In most of the cases, the association is correct and no further changes are required.

Note:

To upgrade the DB category, ensure a data source is associated with it and not left undefined. If the data source remains undefined, it will be skipped and not upgraded.

Click Next to proceed.

Initialize Category/Datasource Table

Note:

This window appears only if you have opted to upgrade the domain database.

Review progress of the Wizard as it prepares to upgrade the domain database schema objects.

The wizard automatically advances to the next window when the process is complete.

Upgrade Database

Note:

This window appears only if you have opted to upgrade the domain database.

Review progress of the Wizard as it upgrades the domain databases.

The wizard automatically advances to the next window when the process is complete.

Upgrade Complete

Review the results of the upgrade, including any important messages that require further consideration.

Click Done to close the Oracle WebLogic Upgrade Wizard.

Upgrading a WLI 10.2 Domain

You can upgrade a WLI domain from WLI 10.2 to WLI 10.2 with WebLogic Portal 10.2.

WLI 10.2 Domain Without WLP 10.2

Install WLI 10.2 without WLP 10.2.
Create a WLI domain using the Configuration Wizard. This domain uses WLS 10.0 MP1 Light Weight Portal Framework libraries.
Add the WLP 10.2 installation on top of the WLI 10.2 installation. The WLI 10.2 domain you had created earlier will not work with this new installation as it contains new Light Weight Portal Framework libraries. However, if you create a new domain now, it works with this installation without a problem.
Run the domain upgrade on the WLI domain that you created earlier. Confirm that the config.xml file has been updated with 10.2 Light Weight Portal Framework references.

WLI 10.2 Domain With WLP 10.2

If you install both WLI 10.2 and WLP 10.2 and then create a new domain, you do not encounter any problem with the domain.

Note:

By default, Oracle Oracle WebLogic Integration 10g Release 3 (10.3.1) is installed with Oracle WebLogic Portal.

Upgrading a Domain in Silent Mode

Note:

Only Oracle WebLogic Server domains can be upgraded in the Silent mode.

In some circumstances, for example, when the domain resides on a remote machine, it is not practical to use the Oracle WebLogic Upgrade Wizard in graphical mode. In such situations, you can use the wizard in silent mode to upgrade the WebLogic domain.

To start the Oracle WebLogic Upgrade Wizard in silent mode and upgrade a WebLogic domain:

Verify that the WebLogic domain is not running.
Review the Important Notes About the Domain Upgrade Process.
Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX) and set up the environment as follows:

Add the Oracle WebLogic Server classes to the CLASSPATH environment variable and WL_HOME\server\bin to the PATH environment variable, where WL_HOME refers to the top-level installation directory for Oracle WebLogic Server.
You can use the WL_HOME\server\bin\setWLSenv script to set both variables.
If you use JMS JDBC stores:

Make sure the JDBC driver classes are added to the CLASSPATH environment variable.
Start the corresponding database.

(Optional) Create an XML script to define the upgrade requirements. For more information see Silent Upgrade XML Script Reference.
Navigate to the directory that contains WebLogic domain that you want to upgrade. For example:

cd c:\bea\user_projects\domains\domain

where domain specifies the name of the domain.

At a command prompt, enter the following command:

java weblogic.Upgrade -mode silent -type domain [-responses xmlfile] [-out file]

The following arguments are optional: -responses and -out. Include these arguments if you want to override the default values for the following:

The location of an XML file that defines the upgrade requirements. If you do not specify a file with the -responses option, the wizard uses the default values during the upgrade process. For more information about the format of the XML file and the default values, see Silent Upgrade XML Script Reference.
The output file in which all standard output (stdout) and error messages are written. If you do not specify a file with the -out argument, these messages are written to the command window.

Known Limitations for Domain Upgrade

When you are upgrading stateful JPD applications from WebLogic Integration 9.x 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 for the upgraded domain, 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%

set JAVA_OPTIONS=%SAVE_JAVA_OPTIONS%

"-Dcom.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0"

UNIX and Linux is as follows:

Modify the SAVE_JAVA_OPTIONS="${JAVA_OPTIONS}"

SAVE_JAVA_OPTIONS="${JAVA_OPTIONS}

-Dcom.sun.xml.namespace.QName.useCompatibleSerialVersionUID=1.0"

Testing Your Domain Upgrade

After upgrading the 8.x, 9.x, or 10.x domain to 10g Release 3 (10.3.1), you can verify that:

variables like WLPORTAL_HOME, WL_HOME, JAVA_HOME in the DOMAIN_HOME\bin\setDomainEnv file point to the 10g Release 3 (10.3.1) values.
the domain version and the configuration version in the DOMAIN_HOME\config\config.xml file is 10.3.1.0.
the JCA libraries file, wli-jca-lib-10.0.ear, is deployed and available in the WLI_HOME\wli_10.3\lib directory.
the JCA event generator, jcaEG.ear, is deployed and available in the WLI_HOME\wli_103\egs directory.
any sample JCA-based application is successfully deployed in Oracle WebLogic Integration.

Upgrading Applications to Oracle WebLogic Integration 10g Release 3 (10.3.1)

Oracle WebLogic Integration 10g Release 3 (10.3.1) provides a set of utilities that allow you to upgrade your 8.1.x, 8.5.x, 9.x, and 10.x applications to Oracle WebLogic Integration 10g Release 3 (10.3.1). This section describes how to upgrade applications built using Oracle WebLogic Integration.

Notes:

During upgrade, the logic and intent of the application is not altered. Oracle WebLogic Integration simply migrates the code to make it compatible with Oracle WebLogic Integration 10g Release 3 (10.3.1). This would involve changes like making the applications compatible with the Eclipse Framework and converting Javadoc annotations to JSR-175 compliant annotations, among others.
Code migration happens only when you upgrade from 8.1.x, 8.5.x applications to 10g Release 3 (10.3.1) not when you migrate from 9.x or 10.x.
Because JCA-based applications need the JCA libraries for application deployment and these libraries are not available in the 8.x, 9.x, or 10.x releases, JCA-based applications cannot be created in any of these releases.

Before You Begin

Verify that you have completed the following tasks:

Migrated all your applications to 8.1 (SP4, SP5, or SP6) or to 8.5 (or higher).
Un-deployed all version 8.1 applications before you upgrade the server.
Verified that the WebLogic domain is not running.
Checked out your version 8.1.x, 8.5.x, 9.x, or 10.x application sources that need to be upgraded to WebLogic Integration 10g Release 3 (10.3.1).
Upgraded the Oracle WebLogic Integration domain using the Oracle Domain Upgrade Wizard. For more information on upgrading your domain, see Upgrading a WebLogic Domain.
Used deployment plans to customize the generation of the EAR files and specify the following tuning parameters:

<transaction-isolation-level>
<transaction-timeout>
<message-transaction-timeout>
<ejb-concurrency-strategy>
<web-tier-controls>
<async-dispatch-policy>

For more information, see Configuring Applications for Production Deployment in Deploying Applications to WebLogic Server.

The Upgrade Process

Application upgrade is a three-step process: going through a list of items that will be upgraded, performing the application upgrade, and fixing errors reported in the log to ensure your applications run in WebLogic Integration 10g Release 3 (10.3.1) without any problems.

You can choose to upgrade your user applications using the Import Wizard or the Command Line utility - both provided by Oracle Workshop for WebLogic. 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.1.x or 8.5.x process application, the application upgrader will not recognize these hierarchies. Instead, it generates a standard classloader inversion hierarchy that a Oracle WebLogic Integration 10g Release 3 (10.3.1) 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.
To use Oracle Service Bus control with Oracle WebLogic Integration 10g Release 3 (10.3.1), you must add a library reference for the control in the weblogic-application.xml file as follows:

<wls:library-ref>

<wls:library-name>sb-transport-control-10.0</wls:library-name>

<wls:specification-version>10.0</wls:specification-version>

<wls:implementation-version>10.0</wls:implementation-version>

</wls:library-ref>

The Application Upgrade allows you to add this entry to the weblogic-application.xml file during upgrade from any WLI version to Oracle WebLogic Integration 10g Release 3 (10.3.1).

Handler methods can only throw throwables that are declared by Interface methods. This indicates that if the eventset methods declaration throws a exception then its implementation should also throw a proper exception. On the other hand, if the eventset methods declaration does not throw an exception, then its implementation clause also should not throw an exception. Please note that this was not handled by the WLI 8.x compiler, so if an WLI 8.x application is upgraded with improper throwables, it would lead to a compilation error in WLI 10.x. The workaround for this problem is to add or remove the throwable in accordance with the interface definition.

In this example, the eventset declaration for Callback method onTaskCompleted and also its implementation in AdvanceTaskCtrlImpl.java throws an exception which is as expected.

BasicTaskCtrl.java

-------------------------------------------

@ControlExtension()

@com.bea.control.TaskAnnotations.TaskCreate(taskPlanId =

@com.bea.control.TaskAnnotations.TaskPlanID(path = '/Worklist/Compatibility 8.1.x', version = 9.0f,

worklistHostApplicationId = 'worklist-ejbs-81x'),
isControlLevelAnno = true)

public interface BasicTaskCtrl extends TaskControl

...................

    @EventSet()

    public interface Callback extends TaskControl.Callback {

/**

* @jc:task-event event-type='complete' response='{response}'

*/

@com.bea.control.TaskAnnotations.TaskEventAnno(eventType = 
com.bea.wli.worklist.api.events.data.TaskEvent.Type.COMPLETE, 
responseParamName = '{response}')

void onTaskCompleted(WliBaseWFTODocument response)throws Exception;

AdvanceTaskCtrlImpl.java

--------------------------------------------

public class AdvanceTaskCtrlImpl implements AdvanceTaskCtrl, ControlSource

   ...................

/**

     * @common:control

*/

    @org.apache.beehive.controls.api.bean.Control()

    private cn.ccb.clpm.wli.control.BasicTaskCtrl basicTaskCtrl;

    @EventHandler(field = 'basicTaskCtrl',

                  eventSet = BasicTaskCtrl.Callback.class,

                  eventName = 'onTaskCompleted')

    public void basicTaskCtrl_onTaskCompleted(WliBaseWFTODocument response)

throws Exception

       ...................

Upgrading the 8.1.x or 8.5.x Application Using the Import Wizard

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

The Import Wizard executes the following tasks:

Imports upgraded source code to the Oracle WebLogic Integration 10g Release 3 (10.3.1) workspace that you have defined.
Upgrades 8.1.x or 8.5.x annotations to Oracle WebLogic Integration 10g Release 3 (10.3.1).
Migrates your WebLogic Integration 8.1.x or 8.5.x source artifacts to Oracle WebLogic Integration 10g Release 3 (10.3.1). This involves the following steps:

Converts WebLogic Integration 8.1.x or 8.5.x project types to Oracle WebLogic Integration 10g Release 3 (10.3.1).
Optionally moves libraries from the 8.1.x or 8.5.x application Libraries folder to a new EAR project in the upgraded application.
Moves JSP files into a WebContent directory.
Upgrades Beehive NetUI JSP tags to Oracle WebLogic Integration 10g Release 3 (10.3.1).
Optionally migrates Beehive NetUI JSP tags to Apache Beehive JSP tags.
Moves XSD files that are in a Schema project into a Schemas folder of the Utility project.
Moves Java packages and source into a src directory.

Note: When you upgrade an 8.1.x or 8.5.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 business process, 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 Project > Properties > Java build.
Select the Libraries tab, click Add Library, and select Process Libraries.

Note:

When you build the application after upgrade, the Eclipse log contains an InvocationTargetException for an application upgraded from WLI 8.1.x or 8.5.x to Oracle WebLogic Integration 10g Release 3 (10.3.1). The steps to re-create this exception are as follows:

Import a WLI 8.1.x or 8.5.x application.
After the upgrade is successful, check the eclipse log. In some machines, you will find a InvocationTargetException in the Eclipse log.

Note:

The steps to remove this exception are as follows:

Select a new workspace.
In Oracle Workshop for WebLogic, select Windows > Preferences > Validation and clear the XML validator check box.
Repeat the upgrade process on the same application. The exception does not appear in the Eclipse log.

For a step by step guide to upgrade an 8.1.x or 8.5.x application to Oracle WebLogic Integration 10g Release 3 (10.3.1), see Upgrading the 8.1 Application Source.

Upgrading the 9.x Application

During the upgrade from 9.x to Oracle WebLogic Integration 10g Release 3 (10.3.1), the IDE updates project metadata, moves your facets to version Oracle WebLogic Integration 10g Release 3 (10.3.1), and requires a version 10.0 server. The project files are updated to Oracle WebLogic Integration 10g Release 3 (10.3.1) and not the source.

The key changes during the upgrade are as follows:

The runtime is upgraded to 10.x.
All the facets versions are upgraded to 10.x.
Factory paths and classpaths are reconfigured to fit in to 10.x
Libraries/classpath containers are upgraded to 10.x

For a step by step guide to upgrade an 9.x application to Oracle WebLogic Integration 10g Release 3 (10.3.1), see Upgrading the 9.2 Application Source.

Note:

Once the upgrade to Oracle WebLogic Integration 10g Release 3 (10.3.1) is complete, you must redo any manual changes you made to the 9.x project before the upgrade.

Using the Command Line to Upgrade 8.1.x or 8.5.x Applications

Oracle Workshop for WebLogic also provides a command line utility that converts the entire 8.1.x or 8.5.x application to work with Oracle WebLogic Integration 10g Release 3 (10.3.1).

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 Oracle WebLogic Integration 10g Release 3 (10.3.1) workspace for migration.

Note: When you run the command line utility, use a 1.5 implementation of the JRE. Ensure that the classpath includes <%ECLIPSE_HOME%>/eclipse/plugins/org.eclipse.equinox.launcher_1.0.1.R33x_v20080118.jar.

The command to upgrade your application is as follows:

java – cp <%ECLIPSE_HOME%>/eclipse/plugins/org.eclipse.equinox.launcher_1.0.1.R33x_v20080118.jar 
-Dwlw.application=%WORK_FILE%
-Dweblogic.home=%WL_HOME%
org.eclipse.core.launcher.Main
-application com.bea.workshop.upgrade81.upgradeStarter
-data %WORKSPACE%
-pluginCustomization %PREFS_FILE%

where,

`ECLIPSE_HOME`	Refers to the Eclipse directory `<%BEA_HOME%>\tools\eclipse_pkgs\2.0\eclipse_3.2.2`
`-Dweblogic.home=WL_HOME`	Refers to the location of Oracle WebLogic Server root folder. By default, this is: `BEA_HOME/wlserver_10.3`
`-Dwlw.application=WORK_FILE`	Refers to the application that requires the upgrade. Replace `WORK_FILE` with the work file name corresponding to the Oracle Workshop for WebLogic 8.1 that you want to upgrade.
`-application com.bea.workshop.upgrade81.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 go. This can be any directory in which you want the version 10g Release 3 (10.3.1) 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 run time. `weblogic.home` refers to the location of the Oracle WebLogic Server root folder. `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
`com.bea.wlw.workshop.upgrade81/upgradeHarnessAbortOnError=true/false`	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.workshop.upgrade81/upgradeHarnessMessageLevel`	This attribute indicates a message level. 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. `WARNING`: Displays warning, error, and fatal messages,and suppresses informational messages. `ERROR`: Displays only error and fatal messages.
`com.bea.wlw.workshop.upgrade81/migrateJSPPreference=true/false`	If you do not specify this attribute, the default is `false`. When it is set to `true`, the upgrade process migrates the JSP files to their new Beehive annotation.
`com.bea.wlw.workshop.upgrade81/useJ2EESharedLibraries=true/false`	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.
`com.bea.wlw.workshop.upgrade81/upgradeHarnessReportOnly=true/false`	When you set this attribute to `true`, the upgrade report is generated. The default setting is `false`, and with this setting both the report and upgrade are performed.
`com.bea.wlw.workshop.upgrade81/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`
`com.bea.wlw.workshop.upgrade81/upgradeProjectImportOverwrite=true/false`	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`.
`com.bea.wlw.workshop.upgrade81/upgradeProjectImportPrefix`	Use this attribute to specify an optional prefix to append to all imported projects.
`com.bea.wlw.workshop.upgrade81/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`.

Note:

To upgrade 9.x applications to Oracle WebLogic Integration 10g Release 3 (10.3.1), you have to use Oracle Workshop for WebLogic, as there is no command line utility available to upgrade 9.x applications to Oracle WebLogic Integration 10g Release 3 (10.3.1). The metadata is upgraded when you open the project in the IDE.

Using an Ant task to Upgrade 8.1.x or 8.5.x Applications

You can use the Ant task to upgrade from WLI 8.1.x or 8.5.x to Oracle WebLogic Integration 10g Release 3 (10.3.1).

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 %BEA_HOME%/tools/eclipse_pkgs/2.0/pkgs/eclipse/plugins/com.bea.workshop.upgrade81_1.0.100.CR376510 folder.

Note: When you run the Ant task, ensure that the <%ECLIPSE_HOME%>/eclipse/plugins/org.eclipse.equinox.launcher_1.0.1.R33x_v20080118.jar is on the classpath of the task, as specified by the classpathref attribute in the following sample Ant task.

A following sample shows the content of the Ant task (upgrade.xml):

<!-- Upgrade.xml : Target to upgrade the 8.1.x or 8.5.x app to Darjeeling -->.

<target name="workshopUpgrade">

<echo message="Upgrading 8.1.x or 8.5.x located at ${WORK_FILE} to ${WORKSPACE}" />

<path id="eclipse.classpath">

<pathelement path="${env.CLASSPATH}" />

<fileset dir="${PKGS.HOME}/eclipse/plugins/" includes="com.bea.workshop.**/wlw-upgrade.jar" />

</path>

<taskdef name="upgradeTask"

classname="com.bea.workshop.upgrade81.cmdline.UpgradeTask"

classpathref="eclipse.classpath" />

<upgradeTask data=%WORKSPACE%

eclipseHome=%ECLIPSE_HOME%

weblogicHome=%WL_HOME%

pluginCustomization=%PREFS_FILE%

wlwApplication=%WORK_FILE%/>

</target>

The following example shows how you can invoke the Ant task to perform an application upgrade from the command line:

ant -f Upgrade.xml workshopUpgrade -DWORK_FILE=C:\xyz\allWorkflows3.work -DWORKSPACE=C:\tempcmdupgrade

where,

`WORKSPACE`	Refers to the Eclipse workspace that the WebLogic Integration 8.1.x or 8.5.x application is imported and upgraded to.
`ECLIPSE_HOME`	Refers to the Eclipse directory `<%BEA_HOME%>\tools\eclipse_pkgs\2.0\eclipse_3.2.2`
`PKGS.HOME`	Refers to the location of the Eclipse packages. `<%BEA_HOME%>\tools\eclipse_pkgs\1.1\pkgs`
`WL_HOME`	Refers to the location of the root folder of Oracle WebLogic Server. `<%BEA_HOME%>\wlserver_10.3`
`PREFS_FILE`	Refers to the location of an optional preference file used during import or upgrade.
`WORK_FILE`	Refers to the location of the work file for the Workshop for WebLogic 8.1.x or 8.5.x application to be imported or upgraded.

Note:

There is no Ant task available to upgrade applications from WLI 9.x to Oracle WebLogic Integration 10g Release 3 (10.3.1).

Understanding the Upgrade Log

Oracle WebLogic Integration 10g Release 3 (10.3.1) 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.workshop.upgrade81 severity_level date time

!MESSAGE Upgrade-related message.

The severity level contains two numbers with the same meaning. The date and time entries refer to when the upgrade was attempted. The upgrade-related message describes what was done, warned about, or the error that occurred. The following is a snippet containing two log entry examples:

!SUBENTRY 1 com.bea.workshop.upgrade81 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 Oracle Workshop for WebLogic upgrade documentation for more information.

!SUBENTRY 1 com.bea.workshop.upgrade81 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 Oracle WebLogic Integration Release Notes.

Manual Changes You Need to Do After Upgrade

After upgrading the 8.1.x or 8.5.x domain, ensure that you have set the security policies on the Compatibility 8.1.x or 8.5.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 or 8.5.x task plan. If you are using a third-party authorizer, use the related third-party client tools to set the policy.
Some worklist 8.x applications are backward compatible. However, a few of the APIs used in the 8.x application may be deprecated. The upgrade log will contain errors and warnings listing the deprecated APIs in the application. You need to redesign the Task Plans in the upgraded worklist application to experience the benefits of the new worklist features.
You must regenerate task controls if there is any change to the Task Plan.
Several worklist 8.x control methods have been removed from the worklist 9.2 task controls. Although the upgrade completes successfully, these methods will be listed as deprecated in the process log file. You must manually redesign the deprecated control methods using the new task control methods.
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.1.x or 8.5.x.
When you upgrade any XQuery 2002 file to 10g Release 3 (10.3.1) release (XQuery 2004 is used in this release), you need to include a namespace declaration in the generated XQuery file. An Xquery 2002 file generated after MFL Transformation (XML to MFL or MFL to XML) does not have a namespace declared in it. You need to manually update the XQuery with the namespace, which should be same as the namespace in the schema. This namespace should be used to qualify all the elements in the generated XQuery file.

Here are a few examples for manually changing the XQuery file:

Example 1: XQuery 2002 file generated after MFL to XML Transformation:

let $CYCC_TO_IMPACTDataLine1 := $_CYCC_TO_IMPACTDataLineDoc

return

<CYCC_TO_IMPACTDataLine>

<cycc_line>

<line_action>{

data($CYCC_TO_IMPACTDataLine1/cycc_line/line_action) }</line_action>

</cycc_line>

</CYCC_TO_IMPACTDataLine>

The above XQuery should be changed using the value of namespace in the schema generated from corresponding MFL as follows:

declare namespace ns0 = 'mfl/cycctoimpactdataline'

let $CYCC_TO_IMPACTDataLine1 := $_CYCC_TO_IMPACTDataLineDoc

return

<ns0:CYCC_TO_IMPACTDataLine>

<ns0:cycc_line>

<ns0:line_action>{

data($CYCC_TO_IMPACTDataLine1/cycc_line/line_action) }</ns0:line_action>

</ns0:cycc_line>

</ns0:CYCC_TO_IMPACTDataLine>

Example 2: Xquery 2002 MFL to XML transformation which does root element mapping from MFL Object to XML Document

$_tcp_TagLen_PackedDoc

Above Xquery should now be changed to include namespace using XML Tags (tcp_TagLen_Packed )

declare namespace ns0='mfl/tcptaglenpacked'

<ns0:tcp_TagLen_Packed>

    <ns0:TagLen_Packed>{ data($_tcp_TagLen_PackedDoc/TagLen_Packed)

}</ns0:TagLen_Packed>

</ns0:tcp_TagLen_Packed>

Example 3: XML to MFL transformation

Before you use any XML file in the business process involving XML to MFL transformation, update this input XML file by declaring the namespace value in the XML Schema (using the namespace value in the corresponding XML schema) and qualifying every element of the input XML with this namespace

<tcp_TagLen_Packed><TagLen_Packed>385</TagLen_Packed></tcp_TagLen_Packed>

The above XML should be changed to by declaring the namespace value in the XML Schema and qualifying every element of the input XML with this namespace:

<ns0:tcp_TagLen_Packed

xmlns:ns0=\'mfl/tcptaglenpacked\'><ns0:TagLen_Packed>385</ns0:TagLen_Packed></ns0:tcp_TagLen_Packed>

Testing the Upgrade

After the upgrade is complete, you can optionally build and deploy the upgraded application (upgraded from 8.1.x or 8.5.x to 10g Release 3 (10.3.1)) 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.

Note: The wlw-manifest.xml file provides information about the server resources referenced in an EAR file. Server administrators should examine the wlw-manifest.xml file to determine the resources necessary for successful deployment.
In 8.x, the wlw-manifest.xml file was generated in META-INF/wlw-manifest.xml of the enterprise application. In 10.x, this file is generated in the WEB-INF directory of each web application.

Channel Builder contains the wli-channels.xml file in the UtilProject\build\classes\channeloutput directory.