1 Introduction to Oracle WebLogic Server SmartUpgrade

This chapter introduces the Oracle WebLogic Server SmartUpgrade software. It includes the following sections:

1.1 What Is Oracle WebLogic Server SmartUpgrade?

Oracle WebLogic Server SmartUpgrade is an Oracle JDeveloper extension and command-line utility that analyzes the applications you deployed previously on OC4J. It then offers advice and performs actions that can help you successfully redeploy the applications on Oracle WebLogic Server.

You can analyze an application archive, or you can analyze an application or project you have opened in Oracle JDeveloper. In addition, SmartUpgrade can analyze the OC4J server where you deployed your applications and provide advice on how to set up a similar configuration in Oracle WebLogic Server.

In addition to providing a comprehensive report with specific findings about each application, SmartUpgrade automates some of the upgrade tasks. For example, SmartUpgrade can generate specific types of application artifacts and automatically package the artifacts as an enterprise archive. You can use this archive as a starting point for deploying your application on Oracle WebLogic Server.

1.2 Using SmartUpgrade As Part of Your Oracle Fusion Middleware Upgrade

Oracle WebLogic Server SmartUpgrade is one of several Oracle software tools that can help you upgrade your entire Oracle Application Server or Oracle WebLogic Server environment to Oracle Fusion Middleware 11g.

As a result, you can use SmartUpgrade as part of an overall approach to upgrading your environment. Oracle recommends that you use SmartUpgrade in conjunction with the other upgrade-related Oracle Fusion Middleware documentation resources.

Refer to the following for more information:

1.3 What's New in This Version of SmartUpgrade

In previous versions, SmartUpgrade provided advice on upgrading many aspects of your OC4J applications, but only generated deployable artifacts for Web services applications and some Web application deployment descriptor elements. This new release of SmartUpgrade introduces:

  • The ability to generate artifacts for EJB applications, as well as Web services applications.

  • Enhancements to the upgrade of Web Services applications and simplification of the Web services upgrade options

  • Enhanced data sources upgrade

  • Upgrade of applications using JSTL libraries.

  • Additional Web Application deployment descriptor support


This version of SmartUpgrade does not support the generation of Java Messaging Service (JMS) artifacts. If you attempt to generate artifacts for an application that contains JMS artifacts, then you will receive errors when you attempt to deploy the application on Oracle WebLogic Server.

1.4 About the SmartUpgrade Report

After SmartUpgrade analyzes a selected enterprise archive or Oracle JDeveloper application or project, SmartUpgrade generates an application upgrade report. You can then browse the report to identify potential issues to address before you can deploy it on Oracle WebLogic Server. Each issue is referred to as a "finding."

Each finding is assigned various attributes, including the level of priority and complexity. The priority and complexity attributes can help you plan the work required to modify and redeploy an application on Oracle WebLogic Server.

For more information, see Section 2.4, "Using a SmartUpgrade Report".

1.5 About SmartUpgrade Artifact Generation

In addition to the upgrade report, SmartUpgrade can optionally generate specific types of application artifacts, such as Oracle WebLogic Server deployment descriptors, data source configurations, Web services, and EJB artifacts.

Instead of reviewing the report findings and creating these artifacts yourself, you can use SmartUpgrade to generate the artifacts for you, which can save you time and effort when upgrading your applications for Oracle WebLogic Server.

For more information, see the following sections:

1.5.1 Generation of Deployment Descriptors

If you configure SmartUpgrade to generate artifacts for a typical Java EE application, then SmartUpgrade analyzes the OC4J deployment descriptors within the application and, for specific elements within the OC4J-specific deployment descriptor, generates sample files that contain the equivalent deployment descriptor elements that can be used to deploy the application on Oracle WebLogic Server.

You can then use the generated deployment descriptors as a starting point for creating the require Oracle WebLogic Server deployment descriptors for your upgraded application.

Besides reviewing the upgrade documentation and reviewing the advice available in the upgrade report findings, you can also configure SmartUpgrade to generate a specific set of Oracle WebLogic Server Web application deployment descriptor elements for you.

Specifically, if you configure SmartUpgrade to generate artifacts, and the software identifies an orion-web.xml file within the application, SmartUpgrade automatically generates the equivalent Oracle WebLogic Server deployment descriptor elements in a sample weblogic.xml file:

  • virtual-directory

  • resource-eve-ref-mapping

  • ejb-ref-mapping

  • default-char-set

  • jsp-print-nulls

  • default-mime-type

  • directory-browsing

  • persistence-path

  • session-tracking

  • expiration-setting

If your application uses the session-tracking and expiration-setting elements, then SmartUpgrade generates wrapper Java classes that are automatically included in the archive file that is generated by SmartUpgrade.

For more information, see Chapter 4, "Using SmartUpgrade Generated Artifacts" and Appendix A, "Output Directories Generated by SmartUpgrade".

1.5.2 Generation of Web Services Artifacts

SmartUpgrade makes it possible to quickly and efficiently upgrade and deploy your Web services to Oracle WebLogic Server, while preserving the existing URLs and interfaces with remote applications in your environment.

When you configure SmartUpgrade to generate artifacts for a Web services application, SmartUpgrade analyzes the OC4J Web services and performs three distinct tasks automatically:

  1. Uses Oracle Weblogic Server service generation tools to generate the service skeleton artifacts for each WSDL in the application.

    The skeleton includes:

    • A new set of value types or data transfer objects

    • A new service endpoint interface (SEI) and a skeleton Web service

    • Oracle WebLogic Server deployment descriptors

  2. Provides the implementation of the skeleton Web service. This implementation is called "glue code" and is generated with required annotations supported by Oracle WebLogic Server.

  3. The "glue code" in the generated skeleton Web service dispatches requests to the original Web service implementation class, which is part of the OC4J application being upgraded. It performs this task by converting the new value types into the original value types.

SmartUpgrade ensures that the existing clients of the original OC4J Web services are not affected by the upgrade. The original WSDL contract is preserved and existing clients can continue to interoperate with the new Web service generated for Oracle WebLogic Server.

Note that the generated Web services glue code contains the required annotations.

SmartUpgrade supports the upgrade of the following Web services features:

  • Stateless and Stateful Services

  • EJB 2.0 and 3.0 Web Services

  • RPC-Lit and Doc-LIt Web Services

  • Web Service JAX-RPC Client (a stub-based client generated by OC4J WSA utility)

  • SOAP Attachments implemented via JAX-RPC handlers

  • SOAP Message Transmission Optimization Mechanism (MTOM)

  • WS Security

For more information, see Chapter 4, "Using SmartUpgrade Generated Artifacts".

1.5.3 Generation of EJB Artifacts

If your application contains Enterprise Java Beans (EJBs), then SmartUpgrade analyzes your application and attempts to generate the equivalent artifacts that can be deployed on Oracle WebLogic Server.

Specifically, SmartUpgrade generates EJB artifacts for OC4J Native CMP applications, as well as other EJB types, with the following exceptions:

  • Auto-generated primary keys are partially supported. SmartUpgrade defaults to Oracle sequence as part of the migration, but Oracle recommends that you manually configure auto-generated keys, as required.

  • Generation of EJB artifacts for TopLink CMP applications is not supported. TopLink BMP or Weblogic CMP are recommended; however, the upgrade of these elements must be performed manually by the user.

  • There are some EJB features which are not transferable between platforms. Refer to the SmartUpgrade upgrade report for details about the features that are not upgraded for a given application.

  • Only the upgrade of OC4J Native message-driven beans (MDBs) is supported.

1.6 SmartUpgrade Oracle JDeveloper Integration and Command-Line Interface

SmartUpgrade is available as an Oracle JDeveloper extension that can be installed using the Oracle JDeveloper Check for Updates feature. It is also available as a command-line tool.

Refer to the following resources for details:

1.7 Downloading and Installing SmartUpgrade

Refer to the following sections for more information about downloading and installing SmartUpgrade:

1.7.1 Deinstalling SmartUpgrade Release 1.0

If you have previously installed SmartUpgrade Release 1.0, then you must remove the existing SmartUpgrade installation before you install SmartUpgrade Release 1.2.

To remove SmartUpgrade Release 1.0:

  1. Stop Oracle JDeveloper.

  2. Delete the oracle.smartupgrade.weblogic folder and its contents from the Middleware home where you installed Oracle JDeveloper:

  3. Delete the oracle.jdeveloper.smartupgrade.weblogic.jar file from the Middleware home:

  4. Delete the toplink_patch.jar file from the Middleware home:

  5. Start Oracle JDeveloper.

1.7.2 Obtaining the SmartUpgrade ZIP Files

You can obtain SmartUpgrade in one of two ways:

  • From the Oracle Fusion Middleware Companion CD-ROM, which is part of the Oracle Fusion Middleware CD-ROM pack

  • From the Oracle Technology Network (OTN)

For example, to download and unpack the SmartUpgrade ZIP file from OTN:

  1. Use your Web browser to navigate to the following URL on OTN:


    Note that the first time you access OTN, you will have to register. Registration is free and provides you with access to all the resources on OTN.

  2. Click the link to download Oracle WebLogic Server SmartUpgrade.

    At the time this document was published, the SmartUpgrade download link was located under the Free Downloads image on the right side of the page.

  3. Follow the instructions on the screen to download a ZIP file that contains all the required SmartUpgrade files.

  4. Unpack the ZIP file in a temporary directory on your local disk.

    Table 1-1 describes the contents of the ZIP file.

Table 1-1 Contents of the SmartUpgrade ZIP File

File Description


A text file that describes the files in the ZIP file.


A ZIP file containing the files required to use the SmartUpgrade command-line interface.


A text file that describes late-breaking information about this SmartUpgrade download.


A ZIP file containing the files required to install the SmartUpgrade Oracle JDeveloper extension.

1.7.3 Installing the Oracle JDeveloper SmartUpgrade Extension

To install the Oracle JDeveloper SmartUpgrade extension from the contents of the downloadable ZIP file:

  1. Verify that you are currently running Oracle JDeveloper 11g.

    If necessary, download and install Oracle JDeveloper 11g from the following location on OTN:


    For Oracle JDeveloper installation instructions, refer to the Oracle Fusion Middleware Installation Guide for Oracle JDeveloper.

  2. If you have previously installed SmartUpgrade Release 1.0, then deinstall Release 1.0, using the instructions in Section 1.7.1, "Deinstalling SmartUpgrade Release 1.0".

  3. Start Oracle JDeveloper.

  4. Select Check for Updates from the Help menu.

  5. Click Next on the Welcome page of the Check for Updates wizard.

  6. On the Source page, select Install From Local File.

  7. Click Browse to locate and select the jdeveloper_smartupgrade.zip file you obtained and unpacked in Section 1.7.2, "Obtaining the SmartUpgrade ZIP Files".

  8. Click Finish to install the SmartUpgrade extension.

  9. Restart Oracle JDeveloper.

    After you restart Oracle JDeveloper, refer to Chapter 2, "Using SmartUpgrade with Oracle JDeveloper".


Future updates to Oracle JDeveloper will be available by selecting one of the Search Update Centers options in the Check for Updates wizard as they are available.

1.7.4 Installing the SmartUpgrade Command-Line Interface

When you install the SmartUpgrade Oracle JDeveloper extension, the files required to run the command-line interface are installed automatically.

To verify that the command-line interface has been installed, locate the smartupgrade.jar file in the following directory after you install the SmartUpgrade extension:


If you do not install the Oracle JDeveloper extension, and you want to install only the SmartUpgrade command-line interface, you can do so from the contents of the downloadable ZIP file or the SmartUpgrade files available on the Oracle Fusion Middleware 11g Release 1 ( Companion CD-ROM.

To install and configure the SmartUpgrade command-line interface without using Oracle JDeveloper:

  1. Verify that you have installed and configured one of the following prerequisites:

    • Java 2 Standard Edition or Enterprise Edition Version 1.6 or later

      For more information, refer to the following Web site for information on downloading the Java 1.6 Software Development Kit (SDK) or Java Runtime (JRE):

    • Apache Ant Version 1.7 or later

      Apache Ant 1.7 is available is installed as part of any Oracle WebLogic Server 11g installation. You can also download it from the following URL:

  2. Unpack the smartupgrade.zip file into a permanent directory where you will run the program.

    Oracle includes the smartupgrade.zip file as part of the SmartUpgrade download from the Oracle Technology Network (OTN), as well as on the Oracle Fusion Middleware 11g Release 1 ( Companion CD-ROM.

  3. Verify that the following files are unpacked into the directory:

    • smartupgrade.jar

    • Manifest.mf

    • readme.txt

  4. For get started using the command-line interface, refer to Chapter 3, "Using the SmartUpgrade Command Line".

1.7.5 Obtaining the Latest Documentation

For the most up-to-date information about SmartUpgrade, including tutorials, data sheet, and the most recent version of this guide, refer to the Oracle Fusion Middleware Upgrade page on the Oracle Technology Network (OTN):