Workshop provides tools to help ease the process of upgrading applications built with version 8.1. These tools are designed to read your version 8.1 code and generate a new corresponding version 10.x (or 9.2) workspace. The newly generated code is a migrated, upgraded version of the 8.1 code in which all of the clearly predictable changes have been made (note that your application logic is not altered by upgrade tools). The new code supports a new annotation model, a different project model, and other component-oriented changes.
Note: The Workshop upgrade documentation assumes that your application was developed using WebLogic Workshop version 8.1. If it wasn't, you must migrate your code so that it builds and runs in the WebLogic Workshop IDE version 8.1 SP4, SP5, or SP6 before using the tools described here to upgrade to Workshop version 10.x.
Note: If you want to upgrade a version 8.1 SP6 application to version 9.2, you must first upgrade to 9.2 MP1 or higher.
This topic provides an overview of the changes from version 8.1 to version 10.x, as well as suggested high-level steps for approaching upgrade.
Differences Between the Version 8.1 and 10.x IDEs, and the Applications Built with Them
Upgrade Process: High Level Steps
Preparing a Version 8.1 Application for Upgrade
Actions Performed By Upgrade Tools
Differences Between the Version 8.1 and 10.x IDEs and the Applications Built with Them
If you've been developing on WebLogic Workshop version 8.1, the most significant differences you'll notice in version 10.x (and applications built with it) are likely to be:
- A different IDE codebase (it is now built on the Eclipse Platform).
- Changes in the project model (differences in the locations for project artifacts, file extensions, and so on).
- A different annotation model that uses the Java 5 standard (as opposed to the Javadoc-style annotations in previous releases).
- Component-specific changes, such as updated, altered or omitted support for certain areas of functionality.
You might also be interested in reading Key Differences for WebLogic Workshop 8.1 Users.
Key IDE Differences
Unlike version 8.1, in version 10.x the IDE is built on the Eclipse Platform. This is a change that offers many benefits, including: the transparency of an open-source architecture; commonly used features that are familiar because they're available with other widely used Eclipse-based IDEs; and a widely used extensibility model via the Eclipse plug-in framework. To this open framework, Workshop adds many features to support iterative development of the kinds of components you built with version 8.1.
Needless to say, moving from the version 8.1 IDE to the Eclipse-based version 10.x means that there are significant user interface changes. The following list describes how familiar version 8.1 features are (or are not) rendered in version 10.x.
- Some source types aren't rendered in a Design View. The version 8.1 IDE featured graphical Design View alternatives for most source artifacts, including web services, EJBs, controls, and JSPs. In version 10.x, the version 8.1 Flow View and web service sources have a corresponding graphical feature.
- Extensions to the version 10.x IDE are based on the Eclipse plug-in framework. In other words, extensions to the version 8.1 IDE must be rewritten to work with version 10.x. Note that version 10.x does not provide tooling for upgrading version 8.1 extensions.
- Some similar features are labeled differently.
Project Model Differences
Many of the changes from the version 8.1 to the version 10.x project model are intended to align the model with broadly used Eclipse and Java conventions. If you've used other Eclipse-based IDEs, version 10.x of Workshop should feel familiar. For a list of significant changes, see Changes During Upgrade from WebLogic Workshop 8.1 to Version 10.x.
Annotation Differences
Workshop version 10.x supports the Java 5 annotation model. Whereas in version 8.1 the annotations in your source code were embedded in Javadoc-style comments, their version 10.x counterparts are outside the comment block. In the abstract, however, there are more similarities than differences between the annotation model in versions 8.1 and 10.x. In other words, for most version 8.1 annotations there are version 10.x counterparts that use the new syntax. Note that as with version 8.1, the version 10.x IDE provides an editor (the Annotations view) through which you can view and edit annotation attribute values. For more information on the changes, see Upgrading Annotations. Note that in version 10.x, the Annotations view is replaced by the Properties view.
Component-Specific Changes
These are changes that are specific to component types, such as web services, EJBs, controls, and so on. They primarily affect source code. You can read Changes During Upgrade from WebLogic Workshop 8.1 to Version 10.x for a summary list, or see the individual technology-oriented topics listed at the bottom of this topic under Related Topics.
Upgrade Process: High Level Steps
These steps assume that your application was developed with WebLogic Workshop. If you wrote your code without using that IDE and you want to upgrade it using Workshop upgrade tools, you must first migrate your code so that it builds and runs in the WebLogic Workshop IDE.
- Ensure that your WebLogic Workshop version 8.1 applications have been upgraded to SP4, SP5, or SP6. The upgrade tools included in this release are designed to upgrade from those versions only.
- Undeploy WebLogic Workshop version 8.1 applications from your version 8.1 domain before you upgrade the server.
Upgrading domains and upgrading WebLogic Workshop applications are separate processes, but they're interrelated. For information about upgrading version 8.1 WebLogic Workshop domains, see WebLogic Workshop Version 8.1 Domains Can Be Upgraded from Within Version 10.x.
- Use the topics in this documentation to determine whether it would be useful for you to do preparatory work on your version 8.1 application before using the upgrade tools to upgrade.
For a list of suggested pre-upgraded changes, see Preparing a Version 8.1 Application for Upgrade.
Also, see Changes During Upgrade from WebLogic Workshop 8.1 to Version 10.x and Notes About General Issues. Those sections list upgrade-related issues, providing links to more information.
- Build your version 8.1 projects before upgrading them with upgrade tools. Certain version 8.1 build artifacts must be present in order for some upgrade changes to be successful.
- Use upgrade tools to upgrade the version 8.1 application.
How To: Use the Import Wizard to Upgrade Version 8.1 Applications describes how to use the tool.
You can also perform the wizard's work through the upgradeStarter Command or upgrade Ant Task.
- Use the upgrade log and these topics to determine how to start fixing any post-upgrade problems that might keep your upgraded application from running.
Preparing a Version 8.1 Application for Upgrade
If your applications are complex, upgrading them from version 8.1 to version 10.x is likely to be a multi-step process. A key part of that process will be the upgrade support the IDE provides via upgrade tools. But you'll also find that some preparatory work on your version 8.1 application makes the wizard's end result much easier to work with and get running.
Take a look through the upgrade documentation provided here. Many of the notes recommend ways to edit your version 8.1 application to make your upgraded code easier to get running.
Note that
Actions Performed By Upgrade Tools
Workshop includes three tools that automate most parts of the upgrade process. Each tool does essentially the same thing, allowing you to specify applications and parameters for upgrade: the import wizard is available as user interface in the IDE; upgradeStarter Command exposes options from the command line; and the upgrade Ant task exposes options for use from Ant.
Note: You can also upgrade individual files once they're in the version 10.x IDE. To do this, right-click the file, then click Upgrade Source Files. For information about the error logging and message verbosity options, see To Import and Upgrade a Version 8.1 Application.
Note: The upgradeStarter Command may require you to make some manual changes to your applcation after upgrading. You can avoid these manual changes by using the import wizard.
The following briefly describes actions performed (and not performed) by the upgrader.
- The upgrader does not change version 8.1 code. Instead it writes upgraded versions of the code into a new version 10.x workspace that you define.
- No source control actions are performed. In other words, your version 8.1 code is not checked out, nor is your upgraded code checked in to a source control repository. Before upgrade, you should check out your version 8.1 application sources. You should also choose a location for the new workspace that is a convenient place from which to check in the upgraded app.
- Wherever possible, version 8.1 annotations will be upgraded to their version 10.x counterparts. For a list of version 8.1 annotations and corresponding version 10.x annotations, see Upgrading Annotations.
- Version 8.1 annotations will be preserved in upgraded code. Version 10.x of the IDE (including the runtime and compiler) does not see the version 8.1 annotation block as anything more than a Javadoc comment. In fact, you might find it helpful to have the older annotations present as you finish upgrading your application. You can delete the version 8.1 annotations at any time.
- The upgrader will migrate your version 8.1 source artifacts into a version 10.x project model. This includes the following:
- Converting version 8.1 project types to version 10.x project types.
- Optionally moving libraries from the version 8.1 application's Libraries folder to a new EAR project in the upgraded application. An EAR project is the preferred location for libraries used by multiple projects in version 10.x.
- Moving JSP files into a WebContent directory.
- Upgrading NetUI JSP tags to versions that are compatible with version 10.x of the runtime.
- Optionally migrating NetUI JSP tags to current JSP tags. See Changes When Upgrading from Version 8.1 NetUI JSP Tags to Version 10.x JSP Tags for more information.
- Moving XSD files that are in a schema project into a version 10.x utility project.
- Moving Java packages and sources into a src directory if they are not in one already.
Viewing the Upgrade Log
Whether you use the import wizard, command-line, or Ant task to upgrade, Workshop will generate a log of the upgrade changes, errors, and warnings. If you use the import wizard, this log will also be displayed in a dialog you can review before completing the process.
Upgrade Preview Dialog
You can expand the node for each file to view the upgrade messages associated with that file. The following key describes the symbols displayed next to file names:
Informational message.
Warning message.
Error message.
Text Log File
Upgrade tools generate a log file containing upgrade messages. This file is available at the following location after upgrade has completed:
UPGRADE_WORKSPACE_HOME\.metadata\upgrade.log
A log message in the file will take the following form:
!SUBENTRY 1 com.bea.workshop.upgrade81 severity_level date time
!MESSAGE Upgrade-related message.
The severity_level will be two numbers, but they have 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 that shows two log entry examples:
!SUBENTRY 1 com.bea.workshop.upgrade81 2 2 2006-02-27 17:17:53.687 !MESSAGE The 10.x control context only supports a subset of the 8.1 control context APIs. Please see the Workshop 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.