2 Roadmap for Upgrading Your Application Environment

Use the upgrade roadmap to identify the procedure required to upgrade your Oracle WebLogic Server application environment. An upgrade of WebLogic application environment is complete when you upgrade, configure, and deploy your WebLogic application environments.

Plan for an Upgrade

Before upgrading your WebLogic application environment, plan the upgrade path. Planning the upgrade path includes generating an inventory of the application environment, verifying the supported system configurations, reviewing the compatibility information of application environment, and creating an upgrade plan.

To ensure that your plan addresses all the aspects of upgrading that are necessary for your environment, complete the following steps:

Step 1: Inventory the Application Environment

Generate an inventory of the application environment by identifying the following components:

  • Administration Server and the computer on which it resides

  • Managed Servers and the computer(s) on which they reside

  • Location of the applications (including all external client applications)

  • External resources, for example:

    • Databases used to store persisted and application data

    • Firewalls

    • Load balancers

  • Tools, scripts, templates, and source code used for automating the tasks required to create the application environment

You can view a sample application environment in Overview of the Upgrade Process.

Step 2: Verify Supported Configuration Information

Supported configurations (for example, JDK versions, Operating System versions, Web server versions, and database versions) have changed for WebLogic Server 14.1.2.0.0. You may be required to upgrade your environments to the supported versions of these and other products.

For information about supported configurations, see Oracle Fusion Middleware Supported System Configurations on Oracle Technology Network (OTN).

For databases, note that:

  • The evaluation database available from the installation program that is provided for use by the sample applications and code examples, and as a demonstration database, is Derby. Derby is an open source relational database management system based on Java, JDBC, and SQL standards. For more information about Derby, see http://db.apache.org/derby/.

  • The Oracle Thin Drivers are included as part of the WebLogic Server installation.

  • If you are using an Oracle OCI database driver and want to change to use a Thin database driver, you must remove the server property (as illustrated below) from the generated JDBC module. For example:

    <property> 
      <name>server</name> 
      <value>servername</value> 
    </property> 
    
  • The Oracle Thin Drivers are installed with WebLogic Server and are ready for use. For more information about using these drivers, see JDBC Drivers Installed with WebLogic Server in Administering JDBC Data Sources for Oracle WebLogic Server.

Step 3: Review the Compatibility Information

Most existing WebLogic Server applications can be run without modification in the new WebLogic Server 14.1.2.0.0 application environment.

Step 4: Create an Upgrade Plan

Using the information gathered in the preceding steps, create a plan for upgrading your application environment.

Identify the scope and timing of the upgrade process, based on your business needs. Note the following points:

  • Oracle does not recommend upgrading an application environment that is currently deployed in production. Instead, you should upgrade your application environment while it is under development or test and execute standard procedures for quality assurance and performance tuning before promoting the upgraded environment to production.

  • If you start a WebLogic Server after performing a significant upgrade, then the WebLogic Server, the products layered on top of the WebLogic Server, and/or your applications can make irreversible changes to existing data files and database tables. For example, the default file stores may change such that the older versions will no longer be able to load them. Significant upgrade includes upgrade from the major versions, minor versions, and patch sets, or any specific patch/application that changes the files or database formats.

  • If your application is complex, for example, if it includes multiple clustered domains and a large number of deployed applications, you may choose to upgrade the components of the application environment in stages.

  • You may consider limiting the number of WebLogic Server versions used in any single application environment to minimize the diversity and cost of systems being administered.

  • If you plan to use the RDBMS security store in a WebLogic domain, Oracle recommends that you create a new domain in which the RDBMS security store is configured. If you have an existing domain in which you want to use the RDBMS security store, you should create the new domain, and then migrate your security realm to it. Oracle does not recommend "retrofitting" the RDBMS security store to an existing domain. See Managing the RDBMS Security Store in Administering Security for Oracle WebLogic Server.

Prepare for the Upgrade

Before you start the upgrade process, you should verify whether there are any upgrade compatibility issues that apply to your applications. You then shut down all running server instances and back up the application components in your domain.

Review the following steps to prepare your system for an upgrade.

Step 1: Check Your Applications (Undeploy If Necessary)

It is not necessary for WebLogic Server applications to be undeployed before upgrading the domain. In most cases, WebLogic Server applications can be run without modifications in the new WebLogic Server 14.1.2.0.0 application environment. Note that if you use deprecated or removed APIs in the application, you might encounter warnings or exceptions at run time.

WebLogic provides tools that can help simplify the application migration process by identifying unused APIs or activating recipes that perform migration tasks for you automatically.
  • The WebLogic Migration Analysis Tool is a command line utility that identifies APIs in a WebLogic application that have been removed or are no longer used in WebLogic Server. For more information about using the WebLogic Migration Analysis Tool, see Identifying Unused APIs.
  • The WebLogic OpenRewrite Recipes project uses a standard OpenRewrite module that is designed to be used by WebLogic Server application users who need to migrate to a new WebLogic version or an updated JDK. For more information, see Using OpenRewrite Recipes to Migrate WebLogic Applications.

Using OpenRewrite Recipes to Migrate WebLogic Applications

Use the OpenRewrite recipes to simplify migrating your WebLogic applications to a new version of WebLogic and Java.

The Oracle WebLogic OpenRewrite recipes implement a Rewrite module that performs common tasks when migrating your WebLogic applications to a new version of WebLogic and Java.

For more information about activating these recipes for your own WebLogic applications, see the Getting Started Readme located in the public WebLogic Rewrite GitHub repository at WebLogic OpenRewrite Project .

Identifying Unused APIs

It is important to know which classes and APIs are no longer in the new version and to address any changes required for the application to successfully deploy. Use the WebLogic Migration Analysis Tool to identify these classes and APIs.

The WebLogic Migration Analysis Tool is a command line utility that identifies APIs in a WebLogic application that have been removed or are no longer used in WebLogic Server 14.1.2.0.0 and generates a report. The report is meant to show only those deletions that are on the classpath of a running WebLogic Server (such as weblogic.jar). The reports are not intended to report on all jar files that are missing in a class - just those associated with the WebLogic applications.

Note:

This report will not catch all potential problems associated with missing or deprecated APIs or classes. For example, if you are using reflection, this report will not detect it. Similarly, this report may state that a library has been removed and could cause and issue, but you may have your own copy of that library somewhere else.

To run the Migration Analysis Tool, execute the following:
java -jar $WL_HOME/server/lib/weblogic.migration-analysis-tool.jar <archive-file-name> <archive-2> <archive-3>
Where <archive-file-name> parameters are the files you want to analyze. For example:
java -jar $WL_HOME/server/lib/weblogic.migration-analysis-tool.jar /tmp/em_example.war

Step 2: Shut Down Servers in the Application Environment

Before you upgrade, you must shut down all servers in the application environment.

Step 3: Back Up the Application Environment

Oracle recommends that before upgrading your application environment, you manually back up the components defined in Table 2-1. You should back up the relevant information on all machines in the domain.

Table 2-1 Recommendations for Backing Up the Application Environment

Component Recommendations

Domain directory

Back up the Administration Server and any remote Managed Server domain directories that are defined in the application environment.

Note: The Domain Upgrade Wizard, which automatically backed up the domain being upgraded, is no longer provided with WebLogic Server. You must manually back up your domain directory prior to upgrading the domain.

Applications and application-persisted data

Back up any applications and data that reside outside of the domain directory.

Log files

If it is important for you to maintain a record of all messages that are logged, back up the log files. As log files can be large, you may want to delete them to conserve disk space if it is not important to retain them.

Step 4: Install Required Oracle Products

Before upgrading your application environment, you must install the Oracle WebLogic Server 14.1.2.0.0 products that you require on each computer in the domain. For more information about installing Oracle WebLogic products, see Installing and Configuring Oracle WebLogic Server and Coherence.

Step 5: Set Up the Environment

To set up the environment for an upgrade:

  1. Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX).
  2. Add the 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 WebLogic Server.

    You can perform this step by running the WL_HOME\server\bin\setWLSEnv script.

    Note:

    On UNIX operating systems, the setWLSEnv.sh command does not set the environment variables in all command shells. Oracle recommends that you execute this command using the Korn shell or bash shell.

Upgrade an Application Environment

To upgrade your application environment to the latest version of WebLogic Server, back up the domain, upgrade the Administration Server host machine, configure the Node Manager, and upgrade each Managed Server instance.

The table below summarizes the steps for updating an application environment. Each step that is performed must be done on every machine in the domain and in the given sequence shown in this table.

Table 2-2 Procedure for Upgrading an Application Environment

Task Description

Back up the domain

Before upgrading the domain on the Administration Server, ensure to backup the domain. See Backing Up the Domain.

Upgrade WebLogic domain (Administration Server)

Run the Reconfiguration Wizard to upgrade the WebLogic domain on the computer that hosts the Administration Server.

Notes: Oracle recommends that you completely upgrade the domain on the Administration Server before upgrading the domain on the Managed Servers.

Depending on the Node Manager configuration of the original domain and the desired Node Manager configuration of the upgraded domain, you may be able to upgrade Node Manager by using the Reconfiguration Wizard. See Determining Node Manager Upgrade Procedure.

Complete Node Manager configuration

This is needed only if your existing domain is using a per host Node Manager configuration and you want to continue using a per domain Node Manager in the upgraded domain. See Completing the Node Manager Configuration.

Back up the domain on each Managed Server.

Prior to upgrading the domain on a Managed Server, make a backup copy of the domain.

Upgrade WebLogic domain (remote Managed Servers)

Use the pack and unpack commands or the WLST writeTemplate() command in online mode to upgrade the WebLogic domain on every computer that hosts any Managed Servers.

Note:
  • The unpack command works only with the same version used to pack the WebLogic domain.

  • Managed Servers that reside on the same computer as the Administration Server do not require additional upgrade steps.

Troubleshooting an Upgrade

If the upgrade process fails at any step, the Reconfiguration Wizard displays a message indicating the reason for the failure, and then terminates the upgrade process.

To proceed with the upgrade process, perform the following steps:

  1. Restore the application environment to its original state using the backup files you created in Step 3: Back Up the Application Environment.
  2. Correct the failure reported by the Reconfiguration Wizard.
  3. Run the Reconfiguration Wizard again to upgrade the domain.

If you encounter any issues during the upgrade or post upgrade, refer to the Known Issues and Workarounds in Release Notes for Oracle WebLogic Server to troubleshoot the issue.