5 Upgrading a WebLogic Domain

What Happens During a WebLogic Domain Upgrade?

During a WebLogic domain upgrade, you specify the domain that you wish to upgrade and respond to a set of prompts. The WebLogic Upgrade Wizard performs the following tasks:

1. Optionally, the wizard backs up the original domain directory.

   If a backup is requested, the wizard backs up the domain directory only, and it does not preserve file permissions. Oracle recommends that you back up the domain, any external applications, and application database resources in a separate process, as described in Step 3: Back Up the Application Environment.

   Note:

   Backup files created by the wizard need to be protected by the user as they may contain confidential information.

2. Recreates scripts, such as startup and shutdown scripts, and renames any original scripts as orig-scriptname.bak, where orig-scriptname specifies the original script name and extension.

   Note:

   The wizard does not copy any customizations in the original startup scripts to the new scripts. For example, if you specified a non-default value for the JAVA_OPTIONS environment variable in the original script, the specified value will not be preserved in the new script.

3. Restructures the original domain, creating a new directory structure and moving domain components to new locations.

   During the restructuring, if a required directory already exists, the wizard simply keeps that directory and maintains the files and subdirectories that reside in it.

   Existing server log files are copied to the servers/server_name/logs/pre-10.0-logs directory in the domain, where server_name specifies the name of the server.

   To review changes to the domain directory structure, see Appendix C, "WebLogic Domain Directory Structure Enhancements."

4. Upgrades the persisted configuration information stored in the configuration file (config.xml) to the config directory.

   If the wizard encounters duplicate resources when upgrading the configuration file (config.xml), a message is logged in the progress window. In this case, the last resource definition encountered is used during the conversion.

5. Upgrades persisted data, such as JMS file stores, JMS JDBC stores, and transaction stores.

   Note:

   If JMS JDBC stores are used in the domain, see Step 6: Set Up the Environment.

   After the JMS JDBC stores are upgraded, the original JMS JDBC stores are not deleted. You should take this fact into account when performing capacity planning. You can delete the original JMS JDBC store tables once the upgrade is successful. Original JMS JDBC store tables are named PrefixNameJMSSTORE and PrefixNameJMSSTATE, where PrefixName is the value of the Prefix Name attribute for the JMS JDBC store.

   If you do not want to upgrade persisted JMS messages, you can delete the JMS file store or JMS JDBC store tables before running the upgrade. When you do so, only JMS messages are lost; the configuration is not changed. For information about managing JDBC store tables, see "Managing JDBC Store Tables" in Configuring Server Environments for Oracle WebLogic Server.

   The wizard does not upgrade a JMS JDBC or file store if it detects that an upgrade has already been performed. If you need to perform multiple upgrades of a domain in which the same persistent stores are use (for example, in a test scenario), you must revert the data in the JMS store each time you repeat the upgrade process, as follows:

   • For a JMS JDBC store, the upgrade process creates a new table named PrefixNameWLSTORE, where PrefixName is the value of the Prefix Name attribute for the JMS JDBC store. Before re-running the upgrade process on a domain that uses the JMS JDBC store is used, to drop this table.

   • If you need to re-run the upgrade, make sure you first restore the backed up version of the JMS file store.

6. Saves the configuration.

   Note:

   When upgrading remote Managed Servers, the wizard does not persist the configuration information.

7. Reports any issues with the domain upgrade that require further consideration.

Important Notes About the Domain Upgrade Process

Please note the following important notes about the upgrade process:

• WebLogic Server applications do not need to be undeployed. In most cases, WebLogic Server applications can be run without modifications in the new WebLogic Server 10.3.4 application environment. Review the compatibility information in Appendix B, "WebLogic Server 10.3.4 Compatibility with Previous Releases," to determine whether any features changes affect the applications in your environment. Note that if APIs that have been deprecated or removed are used in the application, then you may encounter warnings or exceptions at run time.

• At a minimum, the domain directory must contain the following files:

  • config.xml

  • Security-related files, including SerializedSystemIni.dat, DefaultAuthenticatorInit.ldift, DefaultAuthorizerInit.ldift, and DefaultRoleMapperInit.ldift

    If the security-related files are not available, the server fails to start and an authentication error message is logged.

  • Any transaction log (.tlog) files that reside in the domain. For more information, see "Transaction Log Files" in Programming JTA for Oracle WebLogic Server.

• All contents of the domain directory on the target machine are updated during this process.

• You must upgrade the domain on every machine in the application environment.

• The wizard does not upgrade applications during a WebLogic domain upgrade.

• Domains that contain resources for WebLogic Liquid Data, or AquaLogic Data Services Platform cannot be upgraded to WebLogic Server 10.3.4.

• As of 9.0, the .wlnotdelete directory is no longer used in the WebLogic Server environment.

• During the upgrade process, file permissions are not preserved. All non-default file permissions need to 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 and/or modify the permissions on files created during the upgrade process.

• In WebLogic Server 10.3.4, you may need to specify a username and password when starting the server. As a result, you may notice the following behavioral change.

  When upgrading the WebLogic product samples that were installed automatically for WebLogic Server 7.0 releases (located in WL_HOME\samples\server\config), you may notice a change in behavior when starting the Administration Server in the upgraded 10.3.4 domain. With 10.3.4, you are prompted for a username and password. With 7.0, the username and password are passed as a command-line argument to the startServer command, as follows:

  -Dweblogic.management.username=weblogic -Dweblogic.management.password=weblogic
  

• When you upgrade a domain on a remote Managed Server, a message similar to the following may be displayed to indicate that the referenced application path does not reside on the system:

  <Apr 12, 2009 6:42:06 PM EDT> <INFO> <Upgrade> <BEA-800000> <An invalid
  path, 'C:\bea\wlserver_10.3\user_projects\mydomain\medrecEar.ear', was
  specified for application, 'medrecEar'.>
  

  This message can be ignored.

• If you upgraded the Avitek Medical Records application from 8.1 to 10.3.4 on a Solaris machine (only), before starting the server, you must edit the setDomainEnv.sh file to remove -Xverify:none from the start command by setting JAVA_OPTIONS="" after the following line:

  . ${WL_HOME}/common/bin/commEnv.sh
  

  Otherwise, the server start will fail with a JVM error.

Upgrading a Domain

The wizard supports the following upgrade modes:

• Graphical — For upgrading a domain interactively, the Domain Upgrade Wizard using a graphical user interface.

• Silent —Y ou can upgrade a WebLogic domain silently by specifying upgrade requirements in a file.

  Note:

  You can also use implicit mode to upgrade a WebLogic domain automatically when the Administration Server is started. For more information, see Appendix F, "Upgrading a Domain at Administration Server Startup (Implicit Mode)."

You must upgrade the domains on every machine in the domain. For information about preparing remote Managed Server domain directories, see Step 5: Prepare the Remote Managed Server Domain Directories.

The following sections provide instructions for:

• Upgrading a Domain in Graphical Mode

• Upgrading a Domain in Silent Mode

Upgrading a Domain that Uses an Evaluation Database

As of WebLogic 10.3.3, the evaluation database that is available from the installation program is changed from PointBase to Apache Derby. The evaluation database is provided for use by the sample applications and code examples and may be used as a demonstration database. If you are upgrading an examples or demonstration domain that was originally based on PointBase, you have two choices:

• Upgrade the domain so that it continues to use PointBase.

• Upgrade the domain and migrate its database to Derby.

The following sections explain how to implement each of these choices.