upgradeStarter Command

Upgrades a WebLogic Workshop application version 8.1 (SP4, SP5, or SP6) to a Workshop version 10.x workspace.

Note: This command is also available as an Ant task. For more information, see upgrade Ant Task.

Note: Your version 8.1 application must have been upgraded to SP4, SP5, or SP6 before using this command.

This command exposes from the command line essentially the same functionality exposed by the import wizard when upgrading an application, with a few exceptions.

One exception is that the command cannot specify a subset of an application to upgrade. For example, this command does not support specifying which projects to upgrade; all projects are upgraded.

Other exceptions are listed below in the section Manual Steps Required After Command Line Upgrade.

As with the import wizard, this command does not delete or change the version 8.1 application.

For larger applications, consider adding JVM memory arguments, for example: java -Xms512m -Xmx1024m.

Environment

You must use a version 1.5 implementation of the JRE. Also, the classpath must include startup.jar (see the ECLIPSE_HOME argument description below).

Syntax

For Windows... 

java 
    -Xms512m -Xmx1024m
    -cp %ECLIPSE_HOME%/eclipse/plugins/org.eclipse.equinox.launcher_1.0.1.R33x_v20080118awtswtbridge.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%]

For Linux/Unix...

java 
    -Xms512m -Xmx1024m
    -cp $ECLIPSE_HOME/eclipse/plugins/org.eclipse.equinox.launcher_1.0.1.R33x_v20080118awtswtbridge.jar
    -Dnitrox.boot.jar=file:$WORKSHOP_HOME/nitrox-boot.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%]

Arguments

ECLIPSE_HOME

Required. The path to the directory that contains the launcher. By default for Workshop, this is:

BEA_HOME/tools/eclipse_pkgs/2.0/eclipse_3.3.2

-Dweblogic.home=WL_HOME

Required. The location of WebLogic Server root folder. By default, this is:

BEA_HOME/wlserver_10.3

-Dwlw.application=WORK_FILE

Required. Specifies the application to upgrade. Replace WORK_FILE with the WORK file name corresponding to the WebLogic Workshop 8.1 you want to upgrade.

-application com.bea.workshop.upgrade81.upgradeStarter

Required. The Eclipse plugin extension point used to execute this command.

-data WORKSPACE

Required. The name of the target workspace where you want the upgraded application to go. This can be any directory to which you want the version 10.x application files generated.

[-pluginCustomization PREFS_FILE]

Optional. Specifies a properties file to set options for upgrade. Replace PREFS_FILE with the name of a properties file containing a number of key-value pairs. See the remarks below for a list of possible properties.

Remarks

The following lists the properties supported in a PREFS_FILE specified by the -pluginCustomization argument.

Manual Steps Required After Command Line Upgrade

The following upgrade tasks must be performed manually after using the upgrade command line tool. You can avoid having to perform these manual changes by using the import wizard to upgrade your applications.

Project upgrade might be triggered after command line upgrade

In some cases it may be necessary to enable AppXRay in web projects after upgrading them with the command line tool. In such cases Workshop will prompt the user to upgrade the projects when the workspace is opened for the first time. Selecting Yes in the upgrade dialog will enable AppXRay on the project.

Replacing Calls to Unsupported ControlException.getNestedException Method

The version 8.1 com.bea.control.ControlException featured a getNestedException method that is not included on its version 10.x counterpart, org.apache.beehive.controls.api.ControlException. Code that calls this method will represent a compilation error after upgrade. Because this method merely delegated to the getCause method of the Throwable class — which the ControlException class extends — working around this change is as simple as changing the getNestedException call to getCause.

Updating Code to Reflect Changes in PageFlowStack Class

Differences between the version 8.1 com.bea.wlw.netui.pageflow.PageFlowStack class and its counterpart in version 10.x, org.apache.beehive.netui.pageflow.PageFlowStack, may make it necessary for you to modify some of your code after upgrade. In particular, the version 8.1 class extended java.util.Stack, but the 10.x class extends Object directly.

One scenario in which this could create a problem is if your code casts the return value of the static method PageFlowUtils.getPageFlowStack (which is a Stack object) to PageFlowStack. This cast is of course not valid with the current PageFlowStack class. If you were casting to PageFlowStack, then using Stack methods, keep in mind that several of these methods are implemented in the current PageFlowStack class; however, you now get the PageFlowStack instance using static PageFlowStack.get methods.

If you were directly calling the Stack instance returned from PageFlowUtils.getPageFlowStack, but you aren't casting to PageFlowStack, you can still use the Stack. Keep in mind, however, that the getPageFlowStack method is deprecated.

Some PageFlowController and FlowController Methods Made Protected Instead of Public

To enhance application security, some public methods in org.apache.beehive.netui.pageflow.PageFlowController and org.apache.beehive.netui.pageflow.FlowController have been changed so that they're protected. This change means that these methods can no longer be invoked as bean properties from within JSP pages. In addition, new public versions of the methods were created for access from outside page flow code, but given names that begin "the" instead of "get" so that they're not accessible as bean properties.

In summary, this change includes the following:

In general, fixing broken code after upgrade involves searching for the method name that begins with "get" and replacing it with the corresponding method that begins with "the". For example, the following code would need to be revised:

PageFlowController pageFlowController =
     PageFlowUtils.getCurrentPageFlow(this.Request());
if(pageFlowController != null){
    if(pageFlowController.getCurrentPageInfo().getForward().getRedirect() == true) {
        return new Forward("main_page");
    }
}

The following reflects changes that would be made (note that the getCurrentPageFlow method above, from version 8.1, is deprecated; use the two-parameter version below instead):

PageFlowController pageFlowController =
         PageFlowUtils.getCurrentPageFlow(this.getRequest(), this.getServletContext());
// Note "theCurrentPageInfo" here where "getCurrentPageInfo" is used above.
if(pageFlowController != null){
    if(pageFlowController.theCurrentPageInfo().getForward().getRedirect() == true) {
        return new Forward("main_page");
    }
}

Note that code written on versions of the Beehive APIs included in WebLogic Platform prior to version 10.x might also need to be changed. Workshop upgrade tools do not upgrade code written on 9.x versions of the platform.

Upgrading from getRequest Method Calls to Retrieve a ScopedRequest Instance

In version 8.1, the return value of the FlowController.getRequest method could be cast to a ScopedRequest when running in the WebLogic Portal environment. In version 10.x, to improve performance the page flow APIs retrieve a ScopedRequest instance differently. This change is not upgraded by Workshop upgrade tools. If your portal code makes a call to this method, you will need to manually upgrade the code to avoid a ClassCastException. Your code should instead use the ScopedServletUtils.unwrapRequest method to retrieve the ScopedRequest instance.

For example, if your page flow code had the following: 

ScopedRequest s = (ScopedRequest)getRequest();

you would change it to:

ScopedRequest s = ScopedServletUtils.unwrapRequest(getRequest());

Related Topics

upgrade Ant Task

How To: Use the Import Wizard to Upgrade Version 8.1 Applications

Overview: Upgrading from WebLogic Workshop 8.1

Changes During Upgrade from WebLogic Workshop 8.1 to Version 10.x