2 Roadmap for Upgrading Your Application Environment

This section describes how to prepare for and perform an upgrade of your WebLogic application environments. Topics include:

If you are upgrading from WebLogic Server version 9.x or 10.0, see Appendix A, "Upgrading WebLogic Server 9.x or 10.x Application Environments to 10.3.6."

Note:

Oracle does not require WebLogic domains to be upgraded from WebLogic Server 10.3 to 10.3.6. WebLogic domains based upon WebLogic Server 10.3 run on WebLogic Server 10.3.6 without modification.

Plan the Upgrade

Planning how you will upgrade an application environment is an important step in the process. To ensure that your plan addresses all of 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

  • Custom security providers used in the domain

  • Custom Node Managers used in the domain

  • 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

Verify support for all the hardware and software components in the application environment. Table 2-1 lists the key components for which you must verify support.

Table 2-1 Verify Supported Configuration Information

To verify ... See ...

Operating system and hardware support

"Supported Configurations" in What's New in Oracle WebLogic Server.

Database support

"Supported Configurations" in What's New in Oracle WebLogic Server

Please note the following:

  • WebLogic Server 10.3.6 supports PointBase 5.7; however, PointBase is no longer included in the WebLogic Server installation program. (Apache Derby replaces PointBase for running WebLogic Server samples.)

    If you use the upgrade installer to upgrade your existing WebLogic Server installation, the PointBase installation directory is preserved. But to continue using PointBase, you must: a) complete the instructions described in Step 2: Re-apply Customizations to Startup Scripts, after you upgrade your domain; and b) obtain a PointBase license from http://www.pointbase.com. See also Upgrading a Domain that Uses an Evaluation Database.

    Note: The pre-5.7 version of PointBase that was distributed with earlier versions of WebLogic Server can be used for WebLogic domains only.

  • As of WebLogic Server 10.3.3, 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 changed from PointBase to Apache 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/.

    If you have a domain based on PointBase from an earlier version of WebLogic Server, and you plan to upgrade that domain to WebLogic Server 10.3.6, you can continue to use PointBase. But you must obtain a license from http://www.pointbase.com to use it. For more information, see Upgrading a Domain that Uses an Evaluation Database.

    For information about migrating the domain database from PointBase to Derby, see Migrating an Upgraded Domain Database to Derby.

  • The WebLogic jDriver for Oracle was removed in the 9.0 release. If the JDBC connection pools in your domain use the WebLogic jDriver to create database connections, you must reconfigure the upgraded data sources to use a different JDBC driver, which may include changing the driver class name, the database URL format, and properties sent to the driver when creating database connections. As a replacement, you can use any JDBC driver that implements the specification and is thread safe. The driver you select must be installed (in the CLASSPATH) on all servers on which the data source is deployed. For more information about supported JDBC drivers, see "Supported Configurations" in What's New in Oracle WebLogic Server.

    The Oracle Thin Driver is installed with WebLogic Server and is ready for use. For more information about this driver, see "Using JDBC Drivers with WebLogic Server" in Configuring and Managing JDBC for Oracle WebLogic Server.

  • 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 8.1.7 Oracle Thin driver (oracle.jdbc.driver.OracleDriver) is not supported in WebLogic Server 10.x. If your domain contains JDBCConnectionPools that are configured to use this driver, it is recommended that you reconfigure the connection pools to use another driver. Use of this driver causes the domain upgrade to fail during database upgrade.

Web servers, browsers, and firewalls

"Supported Configurations" in What's New in Oracle WebLogic Server


Step 3: Review the Compatibility Information

Most existing WebLogic Server applications can be run without modification in the new WebLogic Server 10.3.6 application environment. However, you should review Appendix B, "WebLogic Server 10.3.6 Compatibility with Previous Releases," to determine whether any feature changes affect the applications in your 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. Please note the following:

  • 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 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 use transactional message-driven beans (MDBs) driven by non-WebLogic XA-enabled JMS providers, you must quiesce gracefully all pending transactions before shutting down and upgrading a server. Pending transactions cannot be recovered after an upgrade. For more information about message-driven beans, see "Message-Driven EJBs" in Programming WebLogic Enterprise JavaBeans for Oracle WebLogic Server.

  • 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, then migrate your security realm to it. Oracle does not recommend "retrofitting" the RDBMS security store to an existing domain. For more information, see "Managing the RDBMS Security Store" in Securing Oracle WebLogic Server.

Prepare to Upgrade

Before you upgrade the application environment, you must perform the following steps:

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 10.3.6 application environment. Review the compatibility information in Appendix B, "WebLogic Server 10.3.6 Compatibility with Previous Releases," to determine whether any features changes affect the applications in your environment. Note that if you use deprecated or removed APIs in the application, you might encounter warnings or exceptions at run time (see "Deprecated Functionality (WebLogic Server 11g Release 1)" in What's New in Oracle WebLogic Server).

Step 2: Shut Down Servers in the Application Environment

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

Note:

If you are upgrading a cluster from WebLogic Server 10.3 to 10.3.6, it is unnecessary to shut down all Managed Server instances simultaneously. Instead, you can perform a rolling upgrade, as described in Appendix G, "WebLogic Server Rolling Upgrade."

Step 3: Back Up the Application Environment

You have the option of backing up the domain during the upgrade process, as described in "Backup Domain" in Procedure for Upgrading a WebLogic Domain. However, the wizard archives the domain directory only; it does not preserve file permissions.

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

Table 2-2 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.

By default, the Configuration Wizard creates a domain directory in the MW_HOME\user_projects directory, where MW_HOME represents the Middleware Home directory in which you installed WebLogic Server.

Applications and application-persisted data

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

By default, applications are created in the MW_HOME\user_projects\applications directory, where MW_HOME represents the Middleware Home directory in which you installed WebLogic Server. In releases before 10.3.1, this location was called the BEA Home directory.

Custom security providers

Back up any custom security providers that you are using in your application environment.

By default, security providers are located in WL_HOME\server\bin\mbeantypes, where WL_HOME specifies the root directory of the WebLogic Server installation.

Node Manager directory and scripts

Back up any Node Manager directories and scripts that you are using to manage your servers in a clustered environment.

The names of the directory and script depend on your operating system:

  • Windows:

    WL_HOME\common\nodemanager
    WL_HOME\server\bin\startNodeManager.cmd
    
  • UNIX:

    WL_HOME/common/nodemanager
    WL_HOME/server/bin/startNodeManager.sh
    

In the preceding path names, WL_HOME represents the root directory of the WebLogic Server installation, for example, c:\bea\wlserver_10.0.

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 maintain them.


Step 4: Install Required Oracle Products

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

Notes:

Before you proceed with installation, note the following:
  • If you are using Node Manager in your pre-10.0 installation, when installing the 10.3.6 product, you should set the Node Manager listen port to match the port number used in the pre-10.0 installation, if possible. The default value for the listen port for Node Manager is 5556.

  • If you have an existing domain that uses PointBase and you plan to continue using PointBase in that domain after upgrading it to WebLogic Server 10.3.6, use the WebLogic Server upgrade installer, not the full installer. The upgrade installer preserves the PointBase installation. For more information, see Upgrading a Domain that Uses an Evaluation Database.

Step 5: Prepare the Remote Managed Server Domain Directories

Some configurations include Managed Servers running on one or more machines that are remote from the Administration Server for the domain. If you have this type of configuration, you must upgrade the domain directories on each of the machines that host the remote Managed Servers.

To prepare the remote domain directories, you must copy the following files from the root directory of the pre-upgraded domain directory on the host computer for the Administration Server to the root directory of the host domain(s) of the remote Managed Servers:

  • config.xml (configuration file)

  • SerializedSystemIni.dat

    Note:

    If the database in your configuration is not compatible with WebLogic Server 10.3.6, the data must be upgraded to a database that is supported before it can be used in the new application environment. For more information, see Step 4: Create an Upgrade Plan.

Step 6: 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 10.3.6.

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

  3. If you use JMS JDBC stores:

    1. Make sure the JDBC driver classes are added to the CLASSPATH environment variable.

    2. Start the corresponding database.

Upgrade Your Application Environment

Figure 2-1 identifies the steps required to upgrade your application environment.

Figure 2-1 Roadmap for Upgrading Your Application Environment

Description of Figure 2-1 follows
Description of "Figure 2-1 Roadmap for Upgrading Your Application Environment"

Table 2-3 summarizes the steps for updating an application environment. Some steps are mandatory, others are optional. Each step that is performed must be done on every computer in the domain and in the sequence shown in this table.

Table 2-3 Procedure for Upgrading an Application Environment

Step Task Description

1

Upgrade custom security providers

If are upgrading from WebLogic Server Version 8.1, and you have custom security providers in your current application environment that you want to continue using in the new environment, upgrade them:

  • On all machines in the environment.

  • Before you upgrade the WebLogic domain.

Note: If you are installing WebLogic Server 10.3.6 into an existing directory that contains a pre-9.0 installation of WebLogic Server, all custom security providers that reside in the default location (WL_HOME\server\lib\mbeantypes) are upgraded automatically. If all of your custom security providers reside in the default location, then the security provider upgrade step is complete, and you do not have to perform the steps described in this section.

2

Upgrade Node Managers

If you are currently using a customized version of Node Manager to provide high availability to Managed Servers and you want to continue doing so in the new application environment, upgrade Node Manager:

  • On all machines in the environment

  • Before you start the servers in an upgraded WebLogic domain

3

Upgrade WebLogic domain (Administration Server)

Upgrade the WebLogic domain on the computer that hosts the Administration Server.

Note: Oracle recommends that you upgrade the Administration Server for a domain before the Managed Servers.

4

Upgrade WebLogic domain (remote Managed Servers)

Upgrade the WebLogic domain on every computer that hosts any Managed Servers. Be sure to copy the appropriate files to the Managed Servers before performing the upgrade, as described in Step 5: Prepare the Remote Managed Server Domain Directories.

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


Complete Post-Upgrade Procedure

After you use the WebLogic Upgrade Wizard to upgrade the application environment, it might be necessary to perform the following steps:

Not all of these steps are required for all situations. Review the sections to determine which, if any, of these steps are appropriate for your environment.

Step 1: Upgrade Your Application Infrastructure

Due to recent changes in the MBean hierarchy, Oracle does not guarantee that all existing configuration and administration scripts (such as WLST, wlconfig, weblogic.Admin, Ant, and so on) can be run from all pre-9.2 environments. Oracle recommends that you update your scripts to take advantage of the new features introduced in WebLogic Server 9.2, 10.0, 10.3, and 10.3.6. For more information about new WebLogic Server features and changes in the MBean hierarchy introduced in each release since 9.2, see WebLogic Administration and Configuration Scripts.

More information is provided in the following sections about scripting tools, custom domain templates, and SNMP:

Using the WebLogic Scripting Tool

The WebLogic Scripting Tool (WLST) is a command-line scripting interface (built with Jython) that you can use to configure WebLogic domains. Using WLST, WebLogic Server administrators can perform administrative tasks and initiate WebLogic Server configuration changes interactively or by running an executable script.

Online and offline versions of WLST are delivered as a single tool. WLST fully supports the administrative and configuration features offered by 10.3.6. For more information about WLST, see Oracle WebLogic Scripting Tool.

As with the other pre-9.2 tools, Oracle does not guarantee that existing pre-9.2 WLST scripts can be run in 9.2 or 10.x due to recent changes in the MBean hierarchy. Oracle recommends that you update your scripts to take advantage of the new features provided with WebLogic Server 9.2, 10.0, 10.3, and 10.3.6.

For more information about new WebLogic Server features and changes in the MBean hierarchy introduced in each release since 9.2, see WebLogic Administration and Configuration Scripts.

Upgrading Your Custom Domain Configuration Templates

Table 2-4 summarizes the steps required to upgrade custom domain or extension templates created with the Template Builder.

Table 2-4 Upgrade Procedure for Custom Domain Templates

Step Task More Information

1

Using the Upgrade Wizard, upgrade the domain that was created using the custom domain or extension template.

Follow the steps described in Upgrade Your Application Environment.

2

Modify the domain to leverage new features, as appropriate.

See What's New in Oracle WebLogic Server. For features introduced in each release of WebLogic Server since 9.2, see Table B-3.

3

Use the Template Builder or pack command to create a 10.3.6 domain or extension template.

See:


Using SNMP to Monitor WebLogic Server

If you use an SNMP manager to monitor WebLogic Server:

  1. Load the WebLogic Server 10.3.6 MIB into your SNMP manager.

    The MIB is located at WL_HOME/server/lib/BEA-WEBLOGIC-MIB.asn1. WebLogic Server does not change object identifiers (OIDs) for existing managed objects; it only adds new OIDs for new managed objects.

  2. If you are generating traps for any deprecated managed objects, create new traps for the replacement objects.

    For a list of deprecated managed objects, see "Deprecated MBeans" in Oracle WebLogic Server MBean Reference. The description of each deprecated MBean includes a pointer to the replacement MBean. (Each SNMP managed object corresponds to an MBean attribute.)

    Note:

    A number of run-time MBeans that are internal to Oracle have been removed from the MIB. These MBeans are not included in the deprecated MBeans list. For more information, see the following documents:

Step 2: Re-apply Customizations to Startup Scripts

To complete the upgrade of your application environment to 10.3.6, it might be necessary to re-apply any customizations to startup scripts. The following sections describe how to customize the default startup scripts as well as any custom startup scripts.

Default Startup Scripts

The Upgrade Wizard does not carry forward any customizations that have been made to the default startup scripts, such as the setting of the JAVA_OPTIONS environment variable. After the upgrade process is complete, you must customize the default scripts again.

If you are upgrading your domain to 10.3.6 and you want to continue using PointBase, you must add the PointBase JAR files to the beginning of the CLASSPATH environment variable definition. To do so, update the set CLASSPATH statement in your setDomainEnv files.

Note:

WebLogic Server 10.3.6 supports PointBase 5.7; however, the use of any version of PointBase with WebLogic Server 10.3.3 or later requires a PointBase license, available at http://www.pointbase.com.

Custom Startup Scripts

If you have created custom startup scripts, you must update them manually, as follows:

  • Set the JDK version to JDK 6.0.

  • Update the CLASSPATH variable, as follows:

    • Add WebLogic Server 10.3.6 classes to the beginning of the variable.

    • Remove all unused pre-10.3 WebLogic classes.

    • To continue using PointBase, include the PointBase database JARs at the beginning of the CLASSPATH environment variable definition.

      For more information about upgrading a domain that uses an evaluation database, see Upgrading a Domain that Uses an Evaluation Database.

Step 3: Verify File Permissions

Verify the file permissions, as follows:

  • If you backed up the domain directory as part of the upgrade, you now must make your backup files secure because they might contain confidential information.

  • During the upgrade process, file permissions are not preserved. If nondefault file permissions are set on files, they must be verified and reset.

  • On a UNIX system, ownership and permissions for any new files created during the upgrade process are assigned to the user performing the upgrade. For example, if the upgrade is performed by root, then root is assigned ownership of any new files. As a result, any user who subsequently wants to update these files in the domain must have root privileges. You may want to review or modify the permissions on files created during the upgrade process.

Step 4: Enroll the Computer with Node Manager

If you upgrade Node Manager during the upgrade process, enroll the computer that is hosting the WebLogic domain with Node Manager. This can be accomplished using the nmEnroll command.

Note:

If the nodemanager.domains file resides on the computer where the Administration Server and Managed Server are configured to run and they share the same domain directory, you can manually edit the file to include an entry for the domain, in the following form: <domain-name>=<domain-directory>.

This file is located in WL_HOME/common/nodemanager, by default (where WL_HOME refers to the top-level installation directory for WebLogic Server).

For more information, see "Configuring nodemanager.domains File" in "General Node Manager Configuration" in Node Manager Administrator's Guide for Oracle WebLogic Server.

The nmEnroll command updates the nodemanager.domains file under the WL_HOME/common/nodemanager directory with information about the domain, where WL_HOME refers to the top-level installation directory for WebLogic Server. The nodemanager.domains file specifies the domains that a Node Manager instance controls. This file is necessary so that standalone clients are not required to specify the domain directory explicitly.

This command also downloads the following files from the Administration Server:

  • nm_password.properties, the Node Manager secret file, which contains the encrypted username and password that is used for server authentication

  • SerializedSystemIni.dat file

To enroll the computer with Node Manager using the nmEnroll command:

  1. Set up your environment, as described in "Setting Up Your Environment" in Oracle WebLogic Scripting Tool.

  2. Invoke WLST, as described in "Invoking WLST" in Oracle WebLogic Scripting Tool.

    As described in step 2, start a WebLogic Server instance and connect WLST to the server using the connect command.

  3. The moment WLST is connected to the Administration Server, enter the "nmEnroll" command to enroll the computer on which WLST is running with Node Manager.

    You have the option of specifying:

    • Path of the domain directory in which you want to save the Node Manager secret file (nm_password.properties) and SerializedSystemIni.dat file. By default, these files are saved in the directory in which WLST was started.

    • Path of the Node Manager home directory. The nodemanager.domains file, containing the information about the domain, is written to this directory. By default, the directory used for this purpose is WL_HOME/common/nodemanager, where WL_HOME refers to the top-level installation directory for WebLogic Server.

      For example, if the domain directory is specified as c:/bea/mydomain/common/nodemanager, and the default home directory for Node Manager, WL_HOME/common/nodemanager, is used, then you enroll the computer on which WLST is running with Node Manager by entering the following command, shown in bold:

      wls:/mydomain/serverConfig> nmEnroll('c:/bea/mydomain/common/nodemanager') 
      Enrolling this machine with the domain directory at c:\bea\mydomain\common\nodemanager....
      Successfully enrolled this machine with the domain directory at C:\bea\mydomain\common\nodemanager
      wls:/mydomain/serverConfig>
      

For more information, see "nmEnroll" in WebLogic Scripting Tool Command Reference.

Step 5: Verify Remote Server Startup Options

When you start the Administration Server, verify the remote server start options, such as JAVA_HOME, MW_HOME, BEA_HOME, and CLASSPATH, reference the WebLogic Server 10.3.6 installation on the target Managed Server. This can be accomplished using the Administration Console, as described in "Configure startup arguments for Managed Servers" in Oracle WebLogic Server Administration Console Help.

Note:

If the remote server startup options are not set correctly, when attempting to start a Managed Server using Node Manager, messages similar to the following may be written to the log file. Because these messages may be sent recursively, they may eventually consume all space available on the drive.
No config.xml was found.

Would you like the server to create a default configuration and boot? (y/n): 
java.io.IOException: The handle is invalid 
at COM.jrockit.io.FileNativeIO.read(III)I(Native Method) 
at COM.jrockit.io.NativeIO.read(Ljava.io.FileDescriptor;II)I(Unknown Source) 
at COM.jrockit.io.NativeIOInputStream.read(II)I(Unknown Source) 
at COM.jrockit.io.NativeIOInputStream.read(I[BI)I(Unknown Source)
at COM.jrockit.io.NativeIOInputStream.read([BII)I(Unknown Source)
at java.io.FileInputStream.read([BII)I(Unknown Source)

Step 6: Promote the Application Environment to Production

Execute standard procedures for quality assurance and performance tuning before promoting an application environment to production. You should test the execution of your applications (including external client applications) in your test application environment. If your applications use APIs that have been deprecated or removed, then you may encounter warnings or exceptions at run time (see "Deprecated Functionality (WebLogic Server 11g Release 1)" in What's New in Oracle WebLogic Server). If you do, you can make any required modifications before promoting your applications to production.

When all test criteria have been met, you can promote the application environment to production, as outlined in your upgrade plan (defined previously in Step 4: Create an Upgrade Plan).

When the new 10.3.6 application environment is deployed into production, you can start redirecting requests to the new environment from the existing environment. Gradually, you can quiesce the existing environment. This might be accomplished using a load balancer, for example.

What to Do If the Upgrade Process Fails

If any step in the upgrade process fails, the WebLogic Upgrade Wizard displays a message indicating the reason for the failure and terminates. To proceed, perform the following steps:

  1. Restore the application environment to its original state using the backup files created in Step 3: Back Up the Application Environment.

  2. Correct the failure reported by the WebLogic Upgrade Wizard.

  3. Continue with the upgrade process from the step at which the failure occurred, as described in Upgrade Your Application Environment.