Contents

Title and Copyright Information

Preface

Documentation Accessibility

Conventions

1 Introduction

Important Terminology

Overview of the Upgrade Process

How the Upgrade Wizard Simplifies the Upgrade Process

Interoperability and Compatibility with Previous Releases

2 Roadmap for Upgrading Your Application Environment

Plan the Upgrade

Step 1: Inventory the Application Environment

Step 2: Verify Supported Configuration Information

Step 3: Review the Compatibility Information

Step 4: Create an Upgrade Plan

Prepare to Upgrade

Step 1: Check Your Applications (Undeploy If Necessary)

Step 2: Shut Down Servers in the Application Environment

Step 3: Back Up the Application Environment

Step 4: Install Required Oracle Products

Step 5: Prepare the Remote Managed Server Domain Directories

Step 6: Set Up the Environment

Upgrade Your Application Environment

Complete Post-Upgrade Procedure

Step 1: Upgrade Your Application Infrastructure

Using the WebLogic Scripting Tool

Upgrading Your Custom Domain Configuration Templates

Using SNMP to Monitor WebLogic Server

Step 2: Re-apply Customizations to Startup Scripts

Default Startup Scripts

Custom Startup Scripts

Step 3: Verify File Permissions

Step 4: Enroll the Computer with Node Manager

Step 5: Verify Remote Server Startup Options

Step 6: Promote the Application Environment to Production

What to Do If the Upgrade Process Fails

3 Upgrading a Security Provider

What Happens During a Security Provider Upgrade

Upgrading a Security Provider

Upgrading a Security Provider in Graphical Mode

Starting the WebLogic Upgrade Wizard in Graphical Mode to Upgrade a Security Provider

Procedure for Upgrading a Security Provider

Upgrading a Security Provider in Silent Mode

4 Upgrading Node Manager

What Happens During a Node Manager Upgrade

Upgrading Node Manager

Upgrading Node Manager in Graphical Mode

Starting the WebLogic Upgrade Wizard in Graphical Mode to Upgrade Node Manager

Procedure for Upgrading Node Manager

Upgrading Node Manager in Silent Mode

5 Upgrading a WebLogic Domain

What Happens During a WebLogic Domain Upgrade?

Important Notes About the Domain Upgrade Process

Upgrading a Domain

Upgrading a Domain in Graphical Mode

Starting the WebLogic Upgrade Wizard in Graphical Mode to Upgrade a Domain

Procedure for Upgrading a WebLogic Domain

Upgrading a Domain in Silent Mode

Upgrading a Domain that Uses an Evaluation Database

Using PointBase in an Upgraded Domain

Migrating an Upgraded Domain Database to Derby

A Upgrading WebLogic Server 9.x or 10.x Application Environments to 10.3.6

Creating a New Domain

Updating an Existing Domain

Upgrading Beehive Applications

B WebLogic Server 10.3.6 Compatibility with Previous Releases

Core Server

WebLogic Persistent Store

Evaluation Database

Server Examples

Continued Use of PointBase Requires License

JMX 1.2 Implementation

Deprecated Features

Runtime MBean Registration

Diagnostics

Oracle JRockit Flight Recorder Integration

Change to DisplayArgumentsAction Behavior

Monitoring Dashboard and Request Performance Pages

Dynamic Configuration Management

Changes to Schema Namespaces and Locations

Modular Configuration and Deployment of JDBC Resources

JDBC Data Sources and Connection Pools

MultiPools

Data Source Factories

JDBC Feature Changes

JDBC 4.0 Support

Deprecated JDBC Drivers

WebLogic-Branded Data Direct Drivers

Oracle RAC Support

Reorganization of JDBC Resources and Data Source Factories in the Administration Console

Socket Direct Protocol

Connection-based System Properties

Keep Connection After Local Transaction

getVendorConnectionSafe

JDBC Debugging Enhancements

Miscellaneous New Features

JMS

Modular Configuration and Deployment of JMS Resources

JMS Message ID Format

Improved Message Paging

Messaging

Changes to weblogic.jms.extension API

Persistent Store Updates

Plug-Ins

Thread Management

JTA

Resource Registration Name

JTA Transaction Log Migration

Enterprise Java Beans (EJBs)

Middleware Home Directory

Security

SSL Support Changes

Performance Enhancements for Security Policy Deployment

Deprecated Authentication Providers

XACML Security Providers

SAML V2 Providers

SAML 2.0 Providers

Oracle Internet Directory and Oracle Virtual Directory Authentication Providers

RDBMS Security Store

Password Validation Provider

Security MBeans

Password Encryption

Security for HTTP Requests

Secure Access to MBeanHome

Message-Level Security in Web Services

RSA Cryptographic Services Upgrade

Validation of Security Certificates

SAML Single Sign-On Attribute Support

WebLogic Service Component Architecture (WebLogic SCA)

Web Services

New Web Services Features

Web Applications, JSPs, and Servlets

ActiveCache

Class Caching

Deprecated and Obsolete Web Application Features

BASIC Authentication with Unsecured Resources

Backward Compatibility Flags

JSP 2.1 Support and Compatibility With JSP 2.0 Web Applications

Support for JSP 2.0

Servlet Path Mapping

XML Implementation

XMLBeans and XQuery Implementation

WebLogic Administration and Configuration Scripts

Deployment Descriptor Validation and Conversion

Deprecated Startup and Shutdown Classes

Administration Console

Console Configuration Features

Administration Console Extension Architecture

Important Console-Extension Information for Version 9.2

WebLogic Portal Skeleton URI References Should be Fully Qualified

Resource Adapters

WLEC

SNMP MIB Refresh Interval and Server Status Check Interval No Longer Used

Backward Compatibility Flags

Deprecated and Removed APIs

C WebLogic Domain Directory Structure Enhancements

WebLogic Server 8.1 Domain Directory Structure

D Upgrade Wizard Command-Line Reference

Examples

E Silent Upgrade XML Script Reference

About Modifying the Sample XML Scripts

Security Provider Upgrade Script

Node Manager Upgrade Script

Domain Upgrade Script

F Upgrading a Domain at Administration Server Startup (Implicit Mode)

G WebLogic Server Rolling Upgrade

Scope of the Rolling Upgrade Process

Before you Begin

Rolling Upgrade Process

Quiescing and Stopping Servers

Shutdown Servers in a Cluster

Installing a Patch, Maintenance Pack, or Minor Release

Installing Patches Using Smart Update

Using the Command Line Interface

Silent Installation

Additional Information

Restarting Servers

Steps in Rolling Upgrade Process for a Patch and Minor Release

Steps in Rolling Upgrade Process for Minor WebLogic Server Releases

Rolling Uninstall

Uninstalling a Patch or Maintenance Pack

Uninstalling a Minor Release

Limitations

Oracle® Fusion Middleware

Upgrade Guide for Oracle WebLogic Server

11g Release 1 (10.3.6)

E13754-06

November 2011

This document describes the procedures to upgrade an application environment to Oracle WebLogic Server 11g Release 1 (10.3.6).

Oracle Fusion Middleware Upgrade Guide for Oracle WebLogic Server, 11g Release 1 (10.3.6)

E13754-06

Copyright © 2007, 2011, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Preface

This preface describes the document accessibility features and conventions used in this guide—Upgrade Guide for Oracle WebLogic Server.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Conventions

The following text conventions are used in this document:

Convention | Meaning
boldface | Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.
italic | Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.
monospace | Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

1 Introduction

This document describes the procedures to upgrade your WebLogic Server application environment to WebLogic Server 11g Release 1 (10.3.6). An application environment includes applications, the WebLogic domains in which they are deployed, and any application data associated with the domain, and may include external resources, such as database servers, firewalls, load balancers, and LDAP servers.

Note:

For information about upgrading your Java EE environment and your deployed applications from Oracle Application Server 10g and Oracle Containers for Java EE (OC4J) to WebLogic Server 11g Release 1 (10.3.6), see Oracle Fusion Middleware Upgrade Guide for Java EE.

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.

WebLogic Server 10.3.6 includes powerful tools to assist you with upgrading your application environments including the WebLogic Upgrade Wizard for upgrading domains, custom security providers, and custom node managers.

Most WebLogic Server applications can be run without modifications in the new WebLogic Server 10.3.6 application environment.

The following sections provide an overview of the topics discussed in this chapter:

Overview of the Upgrade Process

How the Upgrade Wizard Simplifies the Upgrade Process

Interoperability and Compatibility with Previous Releases

Important Terminology

We recommend that, before proceeding, you familiarize yourself with the following terminology:

Upgrade—To update WebLogic products from a previous release or service pack to a more recent one. This process may include updating an existing application or domain configuration to run in a more recent version of WebLogic Server.

Migrate—To move an application or domain configuration from a third-party product to an Oracle product.

Interoperability—(1) The ability of an application deployed in one release or service pack to communicate with another application that is deployed in a different release or service pack. (2) The ability of Oracle product components to communicate with third-party software using standard protocols.

Compatibility—The capability of an application built using one release or service pack to run in another release or service pack, regardless of whether the application was rebuilt.

Overview of the Upgrade Process

The process required to upgrade an application environment depends on the scope of the application. An application environment includes a WebLogic domain and any applications and application data associated with the domain. It may also include external resources, such as firewalls, load balancers, and LDAP servers. Figure 1-1 shows an example of a WebLogic application environment.

Figure 1-1 Example WebLogic Application Environment

Table 1-1 lists the components of the WebLogic application environment shown in Figure 1-1 and the upgrade requirements for each.

Table 1-1 Upgrade Requirements for Components in Example WebLogic Application Environment

Component
Description
Upgrade Requirements

WebLogic domain

Includes the Administration Server (AS) and optionally one or more Managed Servers (for example, MS1, MS2, MS3, and MS4). The servers in a domain may span multiple machines. Furthermore, you can group Managed Servers into clusters to support load balancing and failover protection for critical applications. For more information about WebLogic domains, see "Understanding Oracle WebLogic domains" in Understanding Domain Configuration for Oracle WebLogic Server.

Upgrade the domain directory on each computer in the domain.

Custom security provider

Supports custom security requirements. For information about developing custom security providers, see Developing Security Providers for Oracle WebLogic Server.

Upgrade the custom security providers on each computer in the domain.

Node Manager

Provides high availability to Managed Servers. For more information about Node Manager, see "Node Manager Overview" in Node Manager Administrator's Guide for Oracle WebLogic Server.

Upgrade custom Node Manager on each computer in the domain.

Applications

Any Java EE applications, including Web applications, EJBs, and so on. Typically, applications are deployed to one or more Managed Servers in a domain. Depending on the deployment strategy, applications may reside locally on a computer or be accessible using a shared directory. In addition, external client applications may access the application environment from outside a firewall.

Most WebLogic Server applications can be run without modifications in the new WebLogic Server 10.3.6 application environment. For more information, see Interoperability and Compatibility with Previous Releases.

External resources

Software components, such as databases for storing domain and application data, load balancers, and firewalls.

Verify that all external resources are compatible with WebLogic Server 10.3.6. For more information, see "Supported Configurations" in What's New in Oracle WebLogic Server.

How the Upgrade Wizard Simplifies the Upgrade Process

The WebLogic Upgrade Wizard guides you through the steps required to upgrade a WebLogic domain that is compatible with WebLogic Server 8.1 or later such that it runs in a WebLogic Server 10.3.6 application environment. As part of the upgrade process, you must upgrade any custom security providers and Node Managers used in the domain.

You can also use the WebLogic Upgrade Wizard to upgrade to 10.3.6 a WebLogic domain that is compatible with WebLogic Server 9.x or 10.0, but this is optional. This type of domain runs under WebLogic Server 10.3.6 without modification.

You can step through the upgrade process interactively, using the graphical user interface (GUI), or "silently", by creating an upgrade script and running it. Silent Mode is supported for upgrading a WebLogic domain, security providers, and Node Manager.

Interoperability and Compatibility with Previous Releases

Application environments that run with WebLogic Server 10.3.6 can interact with application environments built on WebLogic Server Version 8.1, 9.x, 10.0, or 10.3.

Most existing WebLogic Server applications can be run without modification in the new WebLogic Server 10.3.6 application environment. You should review the compatibility information described in Appendix B, "WebLogic Server 10.3.6 Compatibility with Previous Releases," to determine whether any feature changes affect the applications in your environment. If your application uses 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).

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:

Plan the Upgrade

Prepare to Upgrade

Upgrade Your Application Environment

Complete Post-Upgrade Procedure

What to Do If the Upgrade Process Fails

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

Step 2: Verify Supported Configuration Information

Step 3: Review the Compatibility Information

Step 4: Create an Upgrade Plan

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)

Step 2: Shut Down Servers in the Application Environment

Step 3: Back Up the Application Environment

Step 4: Install Required Oracle Products

Step 5: Prepare the Remote Managed Server Domain Directories

Step 6: Set Up the Environment

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:

Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX).

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.

If you use JMS JDBC stores:

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

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

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:

Step 1: Upgrade Your Application Infrastructure

Step 2: Re-apply Customizations to Startup Scripts

Step 3: Verify File Permissions

Step 4: Enroll the Computer with Node Manager

Step 5: Verify Remote Server Startup Options

Step 6: Promote the Application Environment to Production

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

Upgrading Your Custom Domain Configuration Templates

Using SNMP to Monitor WebLogic Server

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:

Creating Domain Templates Using the Domain Template Builder

Creating Templates and Domains Using the Pack and Unpack Commands

Using SNMP to Monitor WebLogic Server

If you use an SNMP manager to monitor WebLogic Server:

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.

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:

Oracle Fusion Middleware Release Notes for Microsoft Windows

Oracle Fusion Middleware Release Notes for Linux x86

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:

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

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.

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:

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

Correct the failure reported by the WebLogic Upgrade Wizard.

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

The script content on this page is for navigation purposes only and does not alter the content in any way.

3 Upgrading a Security Provider

If you are using a custom security provider in a WebLogic Server Version 8.1 environment, you can use the WebLogic Upgrade Wizard to upgrade your security provider for use in a WebLogic Server 10.3.6 application environment.

Notes:

As of 9.1, WebLogic Server includes two new security providers, the XACML Authorization provider and the XACML Role Mapping provider. Existing WebLogic domains that you upgrade to 10.3.6 continue to use the authorization and role mapping providers currently specified, such as third-party partner providers or the original WebLogic Authorization and Role Mapping providers. If you want, you can migrate existing domains from using WebLogic Server proprietary providers to the XACML providers, including performing bulk imports of existing policies. For more information, see "Security" in Information Roadmap for Oracle WebLogic Server .

The following sections describe how to use the WebLogic Upgrade Wizard for upgrading the Security Provider.

What Happens During a Security Provider Upgrade

Upgrading a Security Provider

For information about developing custom security providers, see Developing Security Providers for Oracle WebLogic Server.

What Happens During a Security Provider Upgrade

For a security provider upgrade, you specify the source and destination directories for the upgrade, and the WebLogic Upgrade Wizard upgrades the existing JARs so that the security provider can run in a WebLogic Server 10.3.6 application environment.

Note:

The security provider JAR must contain the appropriate MBean Definition File (MDF) that defines the MBean. An MDF is used to generate the .java files for a particular MBean type. For more information about creating MDFs, see Developing Security Providers for Oracle WebLogic Server. If an MDF is not located in the JAR file, the upgrade process fails for that specific security provider.

If an MDF contains undocumented tags, warnings are generated during the upgrade process. These warnings do not affect the upgrade, and can be ignored. To avoid any further such warnings, however, you may want to remove undocumented tags from the MDF.

Security realms defined in pre-9.2 configurations must define a lockout manager (UserLockoutManagerMBean), and must conform to the following naming convention for JMX objects: Security:Name=name. Otherwise, the upgrade process fails for the security provider.

During the upgrade, the Upgrade Wizard performs the following tasks:

Adds required classes to the security provider JAR. These classes include MBeanImpl elements, schema files, and so on.

Reads the MDF and creates the necessary schemas, MBean Implementation, and Binder classes.

Stores the upgraded JARs for the security provider in the specified location.

Appends _Upgraded to the security provider name to make the upgraded JARs distinct from the existing security provider JARs, which are maintained.

Ignores security provider JARs that are shipped with Oracle products, or JARs with names that contain _Upgraded, indicating that they have been upgraded already.

Upgrading a Security Provider

You must upgrade each custom security provider to run in the WebLogic Server 10.3.6 environment.

Note:

If you are installing WebLogic Server 10.3.6 into an existing home directoryFoot 1  that contains an installation of WebLogic Server Version 8.1, all custom security providers that reside in the default location (that is, WL_HOME\server\lib\mbeantypes, where WL_HOME represents the root directory of the pre-9.0 installation) are upgraded automatically. If all of your custom security providers reside in the default location, then you do not have to perform the security provider upgrade step described in this section.

Footnote 1 In releases of WebLogic Server before 10.3.1, this location was called the BEA Home directory. As of release 10.3.1, this location is called the Middleware home directory and is represented by the MW_HOME variable.

To verify that a custom security provider has been upgraded, locate the upgraded security provider, security_provider_name_Upgraded, in the WL_HOME\server\lib\mbeantypes directory, where WL_HOME specifies the root directory of the 10.3.6 installation, and security_provider_name specifies the name of the security provider.

You can upgrade a security provider using the WebLogic Upgrade Wizard in one of the following modes:

Graphical — For upgrading a security provider interactively, using the graphical user interface.

Silent — For upgrading a security provider silently, by specifying upgrade requirements in a file.

You must upgrade a security provider on each computer in the domain.

The following sections describe how to upgrade a security provider:

Upgrading a Security Provider in Graphical Mode

Upgrading a Security Provider in Silent Mode

Upgrading a Security Provider in Graphical Mode

The following sections describe how to upgrade a security provider by using the WebLogic Upgrade Wizard in graphical mode:

Starting the WebLogic Upgrade Wizard in Graphical Mode to Upgrade a Security Provider

Procedure for Upgrading a Security Provider

Note:

The console from which you are running the Upgrade Wizard in graphical mode must support a Java-based GUI. If you attempt to start the Upgrade Wizard in graphical mode on a system that cannot support a graphical display, the invocation fails and an error message is displayed.

Starting the WebLogic Upgrade Wizard in Graphical Mode to Upgrade a Security Provider

Note:

Before proceeding, make sure you have performed the prerequisite steps described in Prepare to Upgrade.

To start the WebLogic Upgrade Wizard in graphical mode and upgrade the security provider:

Verify that the WebLogic domain is not running.

Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX) and set up the environment as described in Step 6: Set Up the Environment.

At a command prompt, enter the following command:

java weblogic.Upgrade -type securityproviders [-out file]

The -out argument is optional. It allows you to designate a file in which you want all standard output (stdout) and error messages to be written. By default, these messages are written to the command window and a summary of them is displayed when the upgrade process is complete. After you run the command, the WebLogic Upgrade Wizard opens, as shown in Figure 3-1.

Figure 3-1 WebLogic Upgrade Wizard for Security Providers

Click Next to proceed to the Select Source Directory window.

Procedure for Upgrading a Security Provider

Table 3-1 summarizes the steps in the procedure to upgrade a security provider using the WebLogic Upgrade Wizard.

Table 3-1 Procedure for Upgrading a Security Provider

In this step ...
You ...

Select Source Directory

Select the directory that contains the security provider JARs that must be upgraded. By default, the selected directory is the current directory.

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

Note: The security provider JARs must contain the MBean Definition File (MDF) for the associated MBean. For more information about creating MDFs, see Developing Security Providers for Oracle WebLogic Server. If JAR file does not contain an MDF, the upgrade process fails for the associated security provider.

Click Next to proceed to the Select Destination Directory window.

Select Destination Directory

Select the directory in which you want to save the new security provider JAR files. The default directory is WL_HOME\server\lib\mbeantypes, where WL_HOME specifies the root directory of the WebLogic Server 10.3.6 installation.

Note: To ensure the success of the domain upgrade, you must target the upgraded security providers to the default destination directory, WL_HOME\server\lib\mbeantypes. If you prefer to keep the security providers in a different location, you can move them when the domain upgrade process is complete.

Click Next to proceed to the next window.

Upgrade Security Providers in Progress

Review progress of the wizard as it saves the upgraded JARs and deletes any temporary files that were created during the upgrade process. Progress messages are displayed in the window.

The security provider JAR must contain the MBean Definition File (MDF) for the associated MBean. For more information about creating MDFs, see Developing Security Providers for Oracle WebLogic Server. If a JAR file does not contain an MDF, the upgrade process fails for the associated security provider. For example:

Now processing mySecurityProviderToo.jar ...
No MDFs (.xmls) found in the old security provider jar with
name mySecurityProviderToo.jar

If an MDF contains undocumented tags, warnings are generated during the upgrade process. These warnings do not affect the upgrade; they can be ignored. To avoid further such messages, you may want to remove undocumented tags from the MDF.

If the wizard locates a security provider JAR that was installed with the product, that has been upgraded already, or that is invalid, it does not upgrade that JAR. For example:

Not upgrading foo.txt because either this is a Out of the Box
Oracle Security Provider jar or this Security Provider jar is
already upgraded or this is not a valid archive (may be not a .jar)

Click Next to proceed to the next window.

Upgrade Complete

Review the upgrade results, including any important messages that require further consideration.

Click Done to close the wizard.

Upgrading a Security Provider in Silent Mode

In some circumstances, for example, when the security provider resides on a remote computer, it is not practical to use the WebLogic Upgrade Wizard in graphical mode. In such situations, you can use the wizard in silent mode to upgrade a security provider.

Note:

Before proceeding, make sure you have performed the prerequisite steps described in Prepare to Upgrade.

To start the WebLogic Upgrade Wizard in silent mode and upgrade a security provider:

Verify that the WebLogic domain is not running.

Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX) and set up the environment as described in Step 6: Set Up the Environment.

(Optional) Create an XML script to define the upgrade requirements. For more information, see Appendix E, "Silent Upgrade XML Script Reference."

Navigate to the directory that contains the security provider to upgrade.

At a command prompt, enter the following command:

java weblogic.Upgrade -mode silent -type securityproviders [-responses xmlfile] [-out file]

Two arguments are optional: -responses and -out. Include these arguments to override the default values for the following:

The location of an XML file that defines the upgrade requirements. If you do not specify a file with the -responses option, the wizard uses the default values during the upgrade process. For more information about the format of the XML file and the default values, see Appendix E, "Silent Upgrade XML Script Reference."

The output file in which all standard output (stdout) and error messages are written. If you do not specify a file with the -out argument, these messages are written to the command window.

4 Upgrading Node Manager

If you are using a customized version of Node Manager in a pre-9.x environment, you can use the WebLogic Upgrade Wizard to upgrade Node Manager for use in a WebLogic Server 10.3.6 application environment.

The following sections describe how to use the WebLogic Upgrade Wizard for this purpose:

What Happens During a Node Manager Upgrade

Upgrading Node Manager

Note:

Before proceeding, make sure you have performed the prerequisite steps described in Prepare to Upgrade.

For more information about Node Manager, see "Node Manager Overview" in Node Manager Administrator's Guide for Oracle WebLogic Server.

What Happens During a Node Manager Upgrade

During a Node Manager upgrade, you specify the home directory of the Node Manager to upgrade. The WebLogic Upgrade Wizard performs the following tasks:

Upgrades Node Manager in the directory you specify so that Node Manager runs in a WebLogic Server 10.3.6 application environment. The Upgrade Wizard upgrades the nodemanager.properties file and converts the NodeManagerSerializedSystemIni.dat to nm_data.properties.

Note:

The nodemanager.properties file must be writable.

Backs up existing log and state management files and stores them in a zip file, weblogic-nodemanager-backup.zip.

Any existing Node Manager files are overwritten during the upgrade process.

You are prompted to specify the username and password to be used for Node Manager authorization when upgrading the domain. For more information, see "Enter Node Manager Credentials" in Table 5-1. If you are upgrading to WebLogic Server 10.3.6 from any pre-9.0 installation, the listen port number used by Node Manager is maintained during the upgrade process.

Note:

When installing the 10.3.6 product, you should, if possible, set the Node Manager listen port to the same port number used in any pre-9.0 installation, if applicable. The default listen port for Node Manager is 5556.

When the upgrade process is complete, perform the following:

Enroll the computer with Node Manager, as described in Step 4: Enroll the Computer with Node Manager.

Verify that the username, password, and listen port settings for Node Manager are set as desired.

Upgrading Node Manager

You must upgrade each instance of Node Manager to run in the WebLogic Server 10.3.6 environment. Specifically, you must upgrade Node Manager on every computer in the domain. You perform an upgrade using the WebLogic Upgrade Wizard in either of the following modes:

Graphical — For upgrading Node Manager interactively, using the graphical user interface

Silent — For upgrading Node Manager silently, by specifying upgrade requirements in a file

You must upgrade Node Manager on each computer in the domain.

The following sections describe how to upgrade Node Manager, including:

Upgrading Node Manager in Graphical Mode

Upgrading Node Manager in Silent Mode

Upgrading Node Manager in Graphical Mode

The following sections describe how to upgrade Node Manager using the WebLogic Upgrade Wizard in graphical mode:

Starting the WebLogic Upgrade Wizard in Graphical Mode to Upgrade Node Manager

Procedure for Upgrading Node Manager

Note:

The console from which you are running the Upgrade Wizard in graphical mode must support a Java-based GUI. If you attempt to start the Upgrade Wizard in graphical mode on a system that cannot support a graphical display, the invocation fails and an error message is displayed.

Starting the WebLogic Upgrade Wizard in Graphical Mode to Upgrade Node Manager

Note:

Before proceeding, make sure you have performed the prerequisite steps described in Prepare to Upgrade.

To start the WebLogic Upgrade Wizard in graphical mode and upgrade Node Manager:

Verify that the WebLogic domain is not running.

Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX) and set up the environment as described in Step 6: Set Up the Environment.

If the Node Manager directory resides in a pre-9.0 installation directory, for example, in the default location, WL_HOME/common/nodemanager (where WL_HOME specifies the root directory of the WebLogic Server installation), copy the contents of the Node Manager directory to the following 10.3.6 installation directory:

MW_HOME/wlserver_10.3/common/nodemanager

In this case, you must upgrade the copy Node Manager in the 10.3.6 installation directory.

Note:

Make sure you maintain the current directory structure. It is not necessary for you to copy the log (.log) files to the new location.

If the Node Manager directory resides outside of the pre-9.0 installation directory, you can skip this step.

At a command prompt, enter the following command:

java weblogic.Upgrade -type nodemanager [-out file]

The -out argument is optional. It allows you to designate a file in which you want all standard output (stdout) and error messages to be written. By default, these messages are written to the command window and a summary of them is displayed when the upgrade process is complete.

After you run the command, the WebLogic Upgrade Wizard opens, as shown in Figure 4-1.

Figure 4-1 WebLogic Upgrade Wizard for Node Manager

Click Next to proceed to the next window.

Procedure for Upgrading Node Manager

Table 4-1 summarizes the steps in the procedure to upgrade Node Manager using the WebLogic Upgrade Wizard.

Table 4-1 Procedure for Upgrading Node Manager

In this step ...
You ...

Node Manager Home Directory Selection

Select a home directory for the instance of Node Manager to be upgraded by navigating the local directory hierarchy.

The Node Manager home directory contains the nodemanager.properties file, logs, and other related files. The exact set of files generated by Node Manager varies between releases and service packs.

By default, the Node Manager home directory is WL_HOME/common/nodemanager, where WL_HOME specifies the root directory of the WebLogic Server installation.

Click Next to proceed to the next window.

Upgrade Your Node Manager Home

Review progress of the wizard as it saves the upgraded configuration and deletes any temporary files that were created during the upgrade process. Progress messages are displayed in the window.

After the process is complete, click Next to proceed to the next window.

Upgrade Complete

Review the upgrade results, including any important messages that require further consideration.

Click Done to close the WebLogic Upgrade Wizard.

Note: Before using Node Manager, you must enroll the computer, as described in Step 4: Enroll the Computer with Node Manager. This step should be performed after you complete the WebLogic domain upgrade process.

Upgrading Node Manager in Silent Mode

In some circumstances, for example, when Node Manager resides on a remote computer, it is not practical to use the WebLogic Upgrade Wizard in graphical mode. In such situations, you can use the wizard in silent mode to upgrade Node Manager.

Note:

Before proceeding, make sure you have performed the prerequisite steps described in Prepare to Upgrade.

To start the WebLogic Upgrade Wizard in silent mode and upgrade Node Manager:

Verify that Node Manager and all instances of WebLogic Server in the domain are not running.

Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX) and set up the environment as described in Step 6: Set Up the Environment.

If the Node Manager directory resides in the pre-9.0 installation directory, for example, in the default location, WL_HOME/common/nodemanager (where WL_HOME specifies the root directory of the WebLogic Server installation), copy the contents of the Node Manager directory to the 10.3.6 installation directory.

In this case, you must upgrade the copy of Node Manager in the 10.3.6 installation directory.

Note:

Make sure you maintain the current directory structure. It is not necessary to copy the log (.log) files to the new location.

If the Node Manager directory resides outside of the pre-9.0 installation directory, you can skip this step.

(Optional) Create an XML script to define the upgrade requirements. For more information, see Appendix E, "Silent Upgrade XML Script Reference."

Navigate to the Node Manager directory to upgrade.

At a command prompt, enter the following command:

java weblogic.Upgrade -mode silent -type nodemanager [-responses xmlfile] [-out file]

Two arguments are optional: -responses and -out. Include these arguments to override the default values for the following:

The location of an XML file that defines the upgrade requirements. If you do not specify a file with the -responses option, the wizard uses the default values during the upgrade process. For more information about the format of the XML file and the default values, see Appendix E, "Silent Upgrade XML Script Reference."

The output file in which all standard output (stdout) and error messages are written. If you do not specify a file with the -out argument, these messages are written to the command window.

Note:

Before using Node Manager, you must enroll the computer, as described in Step 4: Enroll the Computer with Node Manager. This step should be performed after you complete the WebLogic domain upgrade process.

5 Upgrading a WebLogic Domain

You can use the 10.3.6 WebLogic Upgrade Wizard to upgrade domains created in WebLogic Server Version 8.1.

You can also use the WebLogic Upgrade Wizard to upgrade a WebLogic domain created in WebLogic Server 9.x or 10.0 to 10.3.6, but this is optional. This type of domain runs under WebLogic Server 10.3.6 without modification. See Appendix A, "Upgrading WebLogic Server 9.x or 10.x Application Environments to 10.3.6."

The following sections describe how to use the WebLogic Upgrade Wizard for this purpose:

What Happens During a WebLogic Domain Upgrade?

Important Notes About the Domain Upgrade Process

Upgrading a Domain

Upgrading a Domain that Uses an Evaluation Database

What Happens During a WebLogic Domain Upgrade?

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

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 must be protected by the user because they might contain confidential information.

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 nondefault value for the JAVA_OPTIONS environment variable in the original script, the specified value is not preserved in the new script.

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-9.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."

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.

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 after the upgrade is successfully complete. 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 must perform multiple upgrades of a domain in which the same persistent stores are use (for example, in a test scenario), 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 must re-run the upgrade, make sure you first restore the backed up version of the JMS file store.

Saves the configuration.

Note:

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

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:

It is not necessary for WebLogic Server applications to be undeployed. 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 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 computer are updated during this process.

You must upgrade the domain on every computer 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.6.

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 nondefault file permissions 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.

In WebLogic Server 10.3.6, it might be necessary to specify a username and password when starting the server.

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.6 on a Solaris computer (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 fails 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 computer in the domain. For information about preparing remote Managed Server domain directories, see Step 5: Prepare the Remote Managed Server Domain Directories.

Note:

Before proceeding, make sure you have:

Performed the prerequisite steps described in Prepare to Upgrade.

Reviewed the important notes described in Important Notes About the Domain Upgrade Process.

Ensured that the WebLogic Domain is not running.

Backed-up the JMS Store.

The following sections provide instructions for:

Upgrading a Domain in Graphical Mode

Upgrading a Domain in Silent Mode

Upgrading a Domain in Graphical Mode

The following sections describe how to upgrade a WebLogic domain using the WebLogic Upgrade Wizard in graphical mode:

Starting the WebLogic Upgrade Wizard in Graphical Mode to Upgrade a Domain

Procedure for Upgrading a WebLogic Domain

Note:

The console from which you are running the Upgrade Wizard in graphical mode must support a Java-based GUI. If you attempt to start the Upgrade Wizard in graphical mode on a system that cannot support a graphical display, the invocation fails and an error message is displayed.

Starting the WebLogic Upgrade Wizard in Graphical Mode to Upgrade a Domain

To start the WebLogic Upgrade Wizard in graphical mode and upgrade a WebLogic domain on a Windows platform, choose the Domain Upgrade Wizard option from the Oracle program group in the Windows Start Menu by clicking Programs > Oracle WebLogic > WebLogic Server 11gR1 > Tools > Domain Upgrade Wizard.

Note:

You can only use this option if you do not have to customize the environment to specify JDBC driver classes, as described in step 3 of Step 6: Set Up the Environment.

To start the WebLogic Upgrade Wizard in graphical mode and upgrade a WebLogic domain from a Windows command prompt or on a UNIX platform:

Verify that the WebLogic domain is not running.

Backup the JMS Store, if applicable.

Open a command prompt window (on Windows) or a command shell (on UNIX) and set up the environment as described in Step 6: Set Up the Environment.

Execute the following script to upgrade your domains.

On Windows: WL_HOME\common\bin\upgrade.cmd

On Unix: WL_HOME/common/bin/upgrade.sh

The log file is available in the MW_HOME/user_projects/upgrade_logs directory.

The following command can also be used to upgrade a WebLogic domain.

java weblogic.Upgrade [-type domain] [-out file]

Two arguments are optional: -type and -out. Include these arguments to override the default values for the following:

The type of upgrade to be performed. If you do not specify a type with the -type option, a domain upgrade is performed.

The output file in which all standard output (stdout) and error messages are written. If you do not specify a file with the -out option, such messages are written to the command window, and a summary of messages is displayed when the upgrade process is complete.

The -out argument is optional. It allows you to designate a file in which you want all standard output (stdout) and error messages to be written. By default, these messages are written to the command window and a summary of them is displayed when the upgrade process is complete.

After you run the command, the WebLogic Upgrade Wizard opens, as shown in Figure 5-1.

Figure 5-1 WebLogic Upgrade Wizard

If JMS JDBC stores are used, ensure the corresponding database is running.

Click Next to proceed to the next window.

Procedure for Upgrading a WebLogic Domain

Table 5-1 summarizes the steps in the procedure to upgrade a domain using the WebLogic Upgrade Wizard.

Note:

The screens provided in this section are only indicative of what you might see. The actual screens you see depend on the combination of resources used in your domain.

Table 5-1 Procedure for Upgrading a WebLogic Domain

In this step ...
You ...

Select WebLogic Version

Select the WebLogic version of the domain that you are upgrading.

Click Next to proceed to the next window.

Select a Domain to Upgrade

Select the directory that contains the WebLogic domain to be upgraded by navigating the local directory hierarchy.

Click Next to proceed to the next window.

Inspect Domain

Review progress of the wizard as it inspects the domain. Progress messages are displayed in the window.

If you attempt to upgrade a domain in which custom security providers are used, without first upgrading those security providers, an error message is displayed and the wizard exits.

If you receive this error message, upgrade the custom security providers, as described in Chapter 3, "Upgrading a Security Provider," and start the domain upgrade procedure again.

After the inspection is complete (and if no error is encountered), the wizard advances to the next window automatically.

Select Administration Server

Select a server to function as the Administration Server in the new domain.

Note: If there is only one server defined in the domain, this window is skipped. This window is displayed only if the domain you are upgrading has multiple servers.

Click Next to proceed to the next window.

Enter Node Manager Credentials

Enter the username and password (and password confirmation) for Node Manager authorization.

For WebLogic Server 10.3.6, Node Manager requires user and password credentials to be specified for each domain. By default, the username and password are set to weblogic. If you do not use Node Manager, leave the default values unchanged.

Click Next to proceed to the next window.

Select Upgrade Options

Back up current domain (recommended) — If selected, the wizard backs up the original domain directory and stores it in a zip file. This option is selected by default.

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

Add log files to backup zip — If selected, log files are included in the backup zip file. The number and size of log files can be large and you may want to disable this option to exclude them from the backup file. By default, log files are included in the backup file.

Do not set backward compatibility flags — As of WebLogic Server 9.0, some previously supported behavior has changed to comply with J2EE 1.4. By default, the wizard sets flags to enable the previous behavior in the new domain. If you select this option, these flags are not set for backward compatibility. For more information about the backward compatibility flags, see Backward Compatibility Flags.

Directory Selection Analysis and Optional Tasks

Review progress as the wizard processes the domain information and options provided. Progress messages are displayed in the window.

After processing is complete, the wizard advances automatically to the next window.

Domain Backup

Review progress of the wizard as it prepares to back up the domain. Progress messages are displayed in the window.

After processing is complete, the wizard advances automatically to the next window.

Select Directory for Domain Backup

Note: If you did not select Back up current domain upgrade option, as described in the "Select Upgrade Options" step, skip to the "Restructure Domain Directory" step.

In this window, set values for the following:

Backup directory — Navigate the local hierarchy and select the directory in which you want to save the backup zip file. By default, the original domain directory is used.

Backup filename — Enter the name of the backup file in the text box. The default filename is weblogic-domain-backup-domain.zip, where domain specifies the name of the domain.

Click Next to proceed to the next window.

Backup Domain

Review progress as the wizard backs-up the domain. A progress bar displays the percentage of the backup process that is complete, and progress messages are displayed in the window.

Note: Backup files created by the wizard must be protected by the user because they might contain confidential information.

When the backup process is complete, the wizard advances automatically to the next window.

Restructure Domain Directory

Review progress as the wizard restructures the domain directory. Progress messages are displayed in the window.

When the process is complete, the wizard automatically advances to the next window.

Upgrade Configuration Settings

Review progress as the wizard upgrades the configuration settings. Progress messages are displayed in the window.

The configuration information is not persisted until a later step.

After the configuration upgrade is complete, the wizard advances automatically to the next window.

Upgrade Persisted Messages and Transaction Log Formats

Review progress as the wizard upgrades the persisted messages (JMS file and JDBC stores) and transaction (JTA) logs that exist in the domain. A progress bar displays the percentage complete and progress messages are displayed in the window.

After the persisted message and transaction log upgrade process is complete, the wizard advances to the next window automatically.

Upgrade RDBMS Authenticator Security Provider

Specify whether the deprecated RDBMSAuthenticator should be replaced by the SQLAuthenticator.

Note: This window appears only when an RDBMSAuthenticator Security Provider exists in the domain you are upgrading.

Click Next to proceed to the next window.

Persist Upgraded Configuration

Review progress of the wizard as it saves the upgraded configuration and deletes any temporary files that were created during the upgrade process. Progress messages are displayed in the window.

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

After this process is complete, click Next to proceed to the next window.

Upgrade Complete

Review the results of the upgrade, including any important messages that require further consideration.

Click Done to close the WebLogic Upgrade Wizard.

Upgrading a Domain in Silent Mode

Note:

Only WebLogic domains can be upgraded in the Silent mode.

In some circumstances, for example, when the domain resides on a remote computer, it is not practical to use the WebLogic Upgrade Wizard in graphical mode. In such situations, you can use the wizard in silent mode to upgrade the WebLogic domain.

Note:

Before proceeding, make sure you have performed the prerequisite steps described in Prepare to Upgrade.

To start the WebLogic Upgrade Wizard in silent mode and upgrade a WebLogic domain:

Verify that the WebLogic domain is not running.

Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX) and set up the environment as described in Step 6: Set Up the Environment.

(Optional) Create an XML script to define the upgrade requirements. For more information, see Appendix E, "Silent Upgrade XML Script Reference."

Navigate to the directory that contains WebLogic domain to upgrade. For example:

cd c:\bea\user_projects\domains\domain

where domain specifies the name of the domain.

At a command prompt, enter the following command:

java weblogic.Upgrade -mode silent -type domain [-responses xmlfile] [-out file]

The following arguments are optional: -responses and -out. Include these arguments to override the default values for the following:

The location of an XML file that defines the upgrade requirements. If you do not specify a file with the -responses option, the wizard uses the default values during the upgrade process. For more information about the format of the XML file and the default values, see Appendix E, "Silent Upgrade XML Script Reference."

The output file in which all standard output (stdout) and error messages are written. If you do not specify a file with the -out argument, these messages are written to the command window.

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.

Using PointBase in an Upgraded Domain

To continue using PointBase as the database for a domain being upgraded to WebLogic 10.3.6, complete the following steps:

When installing WebLogic Server 10.3.6, as described in Prepare to Upgrade, use the upgrade installer instead of the full installer. The upgrade installer preserves the PointBase installation from the previous WebLogic Server installation.

Note:

You must have an active My Oracle Support account to download the upgrade installer. For more information, see "Downloading an Upgrade Installer From My Oracle Support" in the Oracle WebLogic Server Installation Guide.

Complete the steps described in Upgrade Your Application Environment, and Complete Post-Upgrade Procedure.

The domain's configuration settings for PointBase are preserved.

Obtain a PointBase license, available from http://www.pointbase.com.

If you use the full installer to install WebLogic Server 10.3.6, domains that use PointBase can be upgraded to WebLogic Server 10.3.6, but PointBase is unable to start from them. For a workaround:

Restore your PointBase installation.

Add the PointBase database JARs at the beginning of the CLASSPATH environment variable definition.

Migrating an Upgraded Domain Database to Derby

If you are upgrading an examples domain to WebLogic 10.3.6 and you want to migrate the domain database from PointBase to Derby, complete the following steps:

Install WebLogic Server 10.3.6 using either the upgrade or full installer, as described in Prepare to Upgrade.

Complete the steps described in Upgrade Your Application Environment, and Complete Post-Upgrade Procedure.

Import the PointBase database schema and tables to Derby. The Apache Derby Web site has tips and resources that you might find useful, at http://db.apache.org/derby/integrate/index.html.

Add the following Derby database JARs at the beginning of the CLASSPATH environment variable definition:

WL_HOME\common\derby\lib\derbynet.jar

WL_HOME\common\derby\lib\derbyclient.jar

A Upgrading WebLogic Server 9.x or 10.x Application Environments to 10.3.6

The following sections describe the procedures for upgrading application environments from WebLogic Server 9.x or 10.x to the WebLogic Server 10.3.6 release:

Creating a New Domain

Updating an Existing Domain

Upgrading Beehive Applications

Note:

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.

Creating a New Domain

This option is useful if the process of creating and customizing a domain has been automated. The steps to create a new domain are as follows:

Install WebLogic Server 10.3.6 software.

To create your domain in 10.3.6, use a default domain template provided in 10.3.6. Alternatively, if you used a custom 9.x template to create your domain in 9.x, use the same to create a new 10.3.6 domain.

This step can be accomplished using the Configuration Wizard or using automated scripts, built using WebLogic scripting tools such as WLST. The Configuration Wizard is described in Creating Domains Using the Configuration Wizard, and WLST is described in Oracle WebLogic Scripting Tool.

You may need to update your automated scripts, for example, to reference the 10.3.6 domain template and/or to implement new features provided in the 10.3.6 release.

For example, starting in WebLogic 9.1, the default security providers are XACML-based, as described in "Security" in Information Roadmap for Oracle WebLogic Server . You may choose to add support for the security providers prior to WebLogic 9.1 or make the appropriate changes to use the new XACML-based security providers.

Deploy existing WebLogic Server 9.x applications to the new 10.3.6 domain.

Note:

If you used a custom 9.x template in step 2, the 9.x applications may already be deployed.

Updating an Existing Domain

Updating an existing domain is useful for maintaining customizations within your test domain if generation of the domain has not been automated. There are two options for upgrading an existing domain, as follows:

Option One: Manual Update

Install WebLogic Server 10.3.6 software.

Back up the existing application environment, including the domain directory, application and application data that is external to the domain, and log files (if necessary).

Update the script files in the domain to point to the installation of WebLogic Server 10.3.6. For example, set MW_HOME, MW_HOME, BEA_HOME, BEA_JAVA_HOME, JAVA_HOME, and WL_HOME to the appropriate values.

Update the CLASSPATH to remove path information that is no longer required, such as patch file information that applies to a pre-10.3.6 release.

Option two: Automated Update

Use the Domain Upgrade Wizard, as described in Chapter 5, "Upgrading a WebLogic Domain."

Upgrading Beehive Applications

If you developed Beehive applications in 9.0, 9.1 or 9.2, you must upgrade the applications as described in "Upgrade Paths" in Beehive Integration in BEA WebLogic Server, available at http://download.oracle.com/docs/cd/E13222_01/wls/docs100/beehive/introduction.html#upgrade.

Note:

Instead of using Apache Beehive, Oracle recommends that you use ADF, which offers a rich application framework and is the Oracle standard.

The script content on this page is for navigation purposes only and does not alter the content in any way.

B WebLogic Server 10.3.6 Compatibility with Previous Releases

This section describes important compatibility information that you should consider before upgrading to WebLogic Server 10.3.6.

Also see "WebLogic Server Compatibility" in Information Roadmap for Oracle WebLogic Server and What's New in Oracle WebLogic Server.

Compatibility considerations are provided in the following sections:

Core Server

Evaluation Database

JMX 1.2 Implementation

Diagnostics

Dynamic Configuration Management

Changes to Schema Namespaces and Locations

Modular Configuration and Deployment of JDBC Resources

JDBC Feature Changes

JMS

Messaging

Plug-Ins

Thread Management

JTA

Enterprise Java Beans (EJBs)

Middleware Home Directory

Security

WebLogic Service Component Architecture (WebLogic SCA)

Web Services

Web Applications, JSPs, and Servlets

XML Implementation

XMLBeans and XQuery Implementation

WebLogic Administration and Configuration Scripts

Deployment Descriptor Validation and Conversion

Deprecated Startup and Shutdown Classes

Administration Console

Resource Adapters

WLEC

SNMP MIB Refresh Interval and Server Status Check Interval No Longer Used

Backward Compatibility Flags

Deprecated and Removed APIs

Core Server

As of WebLogic Server 10.3.3, the WebLogic Server Runtime MBean Server is configured by default to contain platform MXBeans for the corresponding server. The Domain Runtime MBean Server contains the platform MXBeans for all of the servers in the domain.

Using the platform MBean server for the Runtime MBean Server is controlled by the PlatformMBeanServerUsed attribute in the JMX MBean. In previous releases, the default value for the PlatformMBeanServerUsed attribute was false so the platform MBean server was not used unless explicitly enabled. In WebLogic Server 10.3.6, the default value for the PlatformMBeanServerUsed attribute is true for domains that are at version 10.3.3.0 or higher. For more information, see "Using the Platform MBean Server" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server.

WebLogic Persistent Store

As of WebLogic Server 10.3.3, WebLogic File Store behavior and tuning for default file stores and custom file stores have changed. File stores may be used by JTA, JMS, and WS applications, among others, but the changes should be transparent to most users.

For more information, see "Guidelines for Configuring a Synchronous Write Policy" in Configuring Server Environments for Oracle WebLogic Server.

Evaluation Database

As of WebLogic Server 10.3.3, the evaluation database available from the WebLogic Server installation program has been changed from PointBase to Apache Derby. If you select the Evaluation Database option on the Choose Products and Components screen, the Derby database is installed in the WL_HOME\common\derby directory. If you select a Typical installation, Derby is installed by default.

Server Examples

The WebLogic Server Medrec and Medrec-Spring server examples have been modified to use the evaluation Derby database that is included with WebLogic Server (see the next section). They have also been modified to use Oracle TopLink as the Java Persistence Architecture (JPA) persistence provider, where such a provider is used.

Continued Use of PointBase Requires License

If you have a domain based on PointBase and you want to continue using PointBase after upgrading the domain to WebLogic Server 10.3.3 or later, you must obtain a PointBase license from http://www.pointbase.com. (Note that the upgrade installer for WebLogic Server preserves the PointBase installation directory; the full installer does not.) As an alternative using to PointBase, you can migrate the domain database to Derby.

For more information, see Upgrading a Domain that Uses an Evaluation Database.

JMX 1.2 Implementation

As of WebLogic Server 9.0, WebLogic Server uses the Java Management Extensions (JMX) 1.2 implementation that is included in JDK 5.0. Before 9.0, WebLogic Server used its own JMX implementation based on the JMX 1.0 specification.

The JMX 1.2 reference implementation introduces serialization incompatibilities. Despite these incompatibilities in the reference implementation, JMX clients created for WebLogic Server 8.1 can be used with 9.2 and later releases as follows:

If your JMX client accesses only WebLogic Server MBeans and uses only weblogic.management.MBeanHome, it can be run in a WebLogic Server 9.2 or later instance without being upgraded.

A JMX client in which WebLogic Server 8.1 classes are used can interact with JMX agents in WebLogic Server 9.2 or later if all of the following are true:

The client accesses only WebLogic Server MBeans.

The client uses only weblogic.management.MBeanHome; it does not use the JDK MBeanServer interface.

The WebLogic Server classes are from 8.1 SP4 with any appropriate patches applied.

If the standard JMX MBeanServer interface is used in your JMX client, either to interact with WebLogic Server MBeans or to create and access custom MBeans, you must include the following JDK startup option for the WebLogic Server 9.2 or later instance: -Djmx.serial.form=1.0.

This startup option causes the JVM to use JMX 1.0 class descriptions when it is serializing objects. The option is required when JMX 1.0 clients communicate with JMX 1.2 agents using the standard JDK classes.

If your JMX client interacts with security provider MBeans, see Security MBeans.

Oracle recommends that you update your JMX clients to be compliant with WebLogic Server 10.3.6. Before 9.0, WebLogic Server supported a typed API layer over its JMX layer. It was possible for your JMX application classes to import type-safe interfaces for WebLogic Server MBeans, retrieve a reference to the MBeans through the weblogic.management.MBeanHome interface, and invoke the MBean methods directly.

Deprecated Features

For information about functionality that has been deprecated in WebLogic Server, see "Deprecated Functionality (WebLogic Server 11g Release 1)" in What's New in Oracle WebLogic Server.

If any of your classes import the type-safe interfaces (available under weblogic.management), Oracle recommends that you update them to use the standard JMX programming model. For more information, see "Understanding WebLogic Server MBeans" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server.

Runtime MBean Registration

For domains that are at version 10.3.3.0 or later, WebLogic Server registers its run-time MBeans in the JVM's platform MBean server. To change the default and use a separate MBean Server, set the PlatformMBeanServerUsed attribute in the JMX MBean to be false using either the Administration Console or WLST. For more information, see "Using the Platform MBean Server" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server.

Diagnostics

As of WebLogic Server 10.3.3, the WebLogic Server Diagnostic Framework (WLDF) includes the following features:

Oracle JRockit Flight Recorder Integration

Change to DisplayArgumentsAction Behavior

Monitoring Dashboard and Request Performance Pages

Oracle JRockit Flight Recorder Integration

WebLogic Server provides specific integration points with Oracle JRockit Flight Recorder. WebLogic Server events are propagated to the Flight Recorder for inclusion in a common data set for run-time or post-incident analysis. The flight recording data is also included in WLDF diagnostic image captures, enabling you to capture flight recording snapshots based on WLDF watch rules. This full set of functionality enables you to capture and analyze run-time system information for both the JVM and the Fusion Middleware components running on it, in a single view.

In version 10.3.3, the WebLogic Diagnostic Framework introduced the WLDF diagnostic volume setting, which controls the amount of data that is automatically produced by WebLogic Server at run time and captured in the JRockit Flight Recorder file. By default, the WLDF diagnostic volume is set to Off in version 10.3.3. However, as of version 10.3.4, the default setting is changed to Low.

For information about WLDF integration features with JRockit Flight Recorder, see "Using WLDF with Oracle JRockit Flight Recorder" in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.

Change to DisplayArgumentsAction Behavior

The behavior of the DisplayArgumentsAction, which is used with custom diagnostic monitors, has been modified in WebLogic Server 10.3.3 to prevent sensitive data in your application from being inadvertently transmitted when an instrumentation event captures input arguments to, or return values from, a joinpoint.

If you must override this behavior change, WLDF adds a new operator, the percent sign (%), which can be specified in pointcut expressions to designate the value of a non-static class instantiation, parameter, or return specification as not containing or exposing sensitive information.

For more information, see "Defining Pointcuts for Custom Monitors" in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.

Monitoring Dashboard and Request Performance Pages

As of WebLogic Server 10.3.3, the WLDF Console Extension has been removed from the WebLogic Server Administration Console and replaced by the following:

Monitoring Dashboard—Provides views and tools for graphically presenting diagnostic data about servers and applications running on them. The underlying functionality for generating, retrieving, and persisting diagnostic data is provided by the WebLogic Diagnostic Framework. The Monitoring Dashboard provides additional tools for presenting that data in a wide range of built-in and custom views. For more information, see "Using the Monitoring Dashboard" in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.

Diagnostics Request Performance page—Displays information about the real-time and historical views of method performance that has been captured by WLDF instrumentation capabilities. For more information, see "Creating Request Performance Data" in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.

Dynamic Configuration Management

Configuration attributes are classified as dynamic or non-dynamic.

Changes to dynamic configuration attributes are available as soon as they are activated, without restarting the affected server or system resource. These changes are made available to the server and run-time hierarchies when they are activated.

Changes to non-dynamic configuration attributes are not immediately available. When a non-dynamic configuration attribute is changed, the server or system resource must be restarted to make the change effective.

WebLogic Server 9.0 introduced a change management process to provide a secure, predictable means for applying configuration changes in a domain. A batch change mechanism changes the way dynamic changes are applied when they are mixed with non-dynamic changes. Specifically, when a configured server or system resource is affected by a change to a non-dynamic attribute, no other changes (even dynamic changes) take effect, in current or future batches, until after the server or system resource is restarted. In this case, Oracle recommends that you restart the entity as soon as possible after the batch change is completed to ensure the system is in a consistent state and to allow future changes to be accepted.

You should test your configuration scripts to determine whether a non-dynamic change has been applied, and if so, restart the server. To determine whether a change is non-dynamic and requires a server restart:

Before you activate a change, you can:

View the change listed in the Change Center in the Administration Console, as described in "Dynamic and Non-Dynamic Changes" in Introduction to Oracle WebLogic Server.

Use the following WLST commands: isRestartRequired or showChanges. For more information, see WebLogic Scripting Tool Command Reference.

After you activate a change, you can:

Review the server log to identify whether the change is categorized as non-dynamic.

Check the value of the RestartRequired or PendingRestartSystemResources attribute that is associated with the changed object, if applicable.

To determine which security attributes are dynamic or non-dynamic, see "Security Configuration MBeans" in Securing Oracle WebLogic Server.

For more information, see "Managing Configuration Changes" in Understanding Domain Configuration for Oracle WebLogic Server.

Changes to Schema Namespaces and Locations

Namespace URIs and schema locations that contained www.bea.com have been changed as of WebLogic Server 10.3.3 to refer to xmlns.oracle.com. In addition, the WebLogic Server version numbers (920, 90) have been removed.

See the Oracle WebLogic Server Schema home at http://www.oracle.com/technology/weblogic/index.html. Also see "XML Deployment Descriptors" in Developing Applications for Oracle WebLogic Server.

Modular Configuration and Deployment of JDBC Resources

As of WebLogic Server 9.0, the number of JDBC resource types was reduced to simplify JDBC configuration and to reduce the likelihood of configuration errors. Now, instead of configuring a JDBC connection pool and then configuring a data source or transactional data source to point to the connection pool and bind to the JNDI tree, you can configure a data source that encompasses a connection pool. For more information about simplified JDBC resource configuration introduced in WebLogic Server 9.0, see "Simplified JDBC Resource Configuration" in Configuring and Managing JDBC for Oracle WebLogic Server, available at http://download.oracle.com/docs/cd/E13222_01/wls/docs90/jdbc_admin/jdbc_intro.html#simple_res_config.

The WebLogic Upgrade Wizard automatically converts JDBC data sources, connection pools, MultiPools, and data source factories to their new counterparts in WebLogic Server 10.3.6, as described in the following sections:

JDBC Data Sources and Connection Pools

MultiPools

Data Source Factories

Note:

Each upgraded JDBC module contains an internal properties section. WebLogic Server uses internal properties to manage the data sources for backward compatibility. Also, some legacy attributes are preserved as properties in the Properties attribute of the JDBC data source file. Do not manually edit any internal properties.

For information about JDBC features, methods, interfaces, and MBeans that were deprecated as of WebLogic Server 9.0, see "Deprecated Functionality (WebLogic Server 11g Release 1)" in What's New in Oracle WebLogic Server.

JDBC Data Sources and Connection Pools

The Upgrade Wizard converts legacy JDBC data source/connection pool pairs to two data source system resource modules, one for the data source and one for the connection pool:

The data source that replaces the existing data source or transactional data source defines the data source parameters and refers to the second data source for its connection pool and related attributes.

The data source that replaces the connection pool contains the JDBC driver parameters, the connection pool parameters, and the XA parameters.

Note:

Only data sources that are converted as part of a domain upgrade can refer to another data source for its connection pool. In all other cases, each data source contains its own pool of database connections.

During an upgrade, the Upgrade Wizard sets the GlobalTransactionsProtocol parameter for a data source based on the type of data source being converted (transactional or non-transactional) and the type of driver used in the related connection pool, as noted in Table B-1.

Table B-1 Parameter Settings for Global Transaction Protocol Parameter Setting

Legacy Data Source Type
Driver Type
Emulate Two-Phase Commit
GlobalTransactionProtocol

Tx Data Source

XA

N/A

TwoPhaseCommit

Tx Data Source

Non-XA

False

OnePhaseCommit (by default; not explicitly set)

Tx Data Source

Non-XA

True

EmulateTwoPhaseCommitFoot 1 

Data Source

Non-XA

N/A

None

Footnote 1 Depending on your environment, you may want to consider using the LoggingLastResource (LLR) transaction protocol in place of the EmulateTwoPhaseCommit protocol for transaction processing because of its performance benefits. For more information see "Understanding the Logging Last Resource Transaction Option" in Configuring and Managing JDBC for Oracle WebLogic Server.

MultiPools

The Upgrade Wizard converts a MultiPool to a multi-data source, which is another instance of a data source object that provides load balancing or failover between data sources.

Data Source Factories

For information, see "Deprecated Functionality (WebLogic Server 11g Release 1)" in What's New in Oracle WebLogic Server.

JDBC Feature Changes

The following sections describe changes to JDBC support:

JDBC 4.0 Support

Deprecated JDBC Drivers

WebLogic-Branded Data Direct Drivers

Oracle RAC Support

Reorganization of JDBC Resources and Data Source Factories in the Administration Console

Socket Direct Protocol

Connection-based System Properties

Keep Connection After Local Transaction

getVendorConnectionSafe

JDBC Debugging Enhancements

Miscellaneous New Features

For details about new JDBC features, see "JDBC" in What's New in Oracle WebLogic Server.

JDBC 4.0 Support

As of 10.3, WebLogic Server is compliant with the JDBC 4.0 specification, with the following enhancements and exceptions:

SQLXML is fully supported on the server side. On the RMI client side, SQLXML is partially supported. You cannot use the getSource and setResult APIs on the client side.

WebLogic Server JDBC supports standard Wrapper Pattern functionality and extends the functionality on the server side. The JDBC standard requires support for the Wrapper operation on the interface. WebLogic Server supports the Wrapper operation on both the interface and on the concrete class on the server side.

WebLogic Server enhances statement pool management as follows.

For the Statement interface:

Call isPoolable() always returns false

Call setPoolable() does not change the poolable state.

For the PreparedStatement and CallableStatement interfaces:

Call isPoolable() returns the current poolable state, the default value is true

Call setPoolable() modifies the poolable state.

For the PreparedStatement or CallableStatement interface, the following occurs when you call the close() method:

If the current poolable state is false, PreparedStatement or CallableStatement is closed.

If the current poolable state is true, PreparedStatement or CallableStatement reverts to the statement cache.

Updated third-party JDBC drivers:

Oracle Thin driver updated from 10g to 11g

PointBase database server and driver updated from 5.1 to 5.7

Deprecated JDBC Drivers

For information about JDBC drivers that have been deprecated in WebLogic Server, see "Deprecated Functionality (WebLogic Server 11g Release 1)" in What's New in Oracle WebLogic Server.

WebLogic-Branded Data Direct Drivers

Oracle provides WebLogic-branded versions of DataDirect drivers for DB2, Informix, MS SQL Server, and Sybase. For information about changes to these drivers, including to support JDBC 4.0, see "Updated WebLogic Type 4 JDBC Drivers" in the WebLogic Server 10.3 Release Notes.

Oracle RAC Support

As of 10.3, WebLogic Server includes support for Oracle Database 11g and Oracle Real Application Clusters (RAC) 11g. Support for connecting data sources and multi data sources to services running on Oracle RAC nodes was added in release 10.3.4. For more information, see "Using WebLogic Server with Oracle RAC" in Configuring and Managing JDBC for Oracle WebLogic Server.

As of release 10.3.4, WebLogic Server also provides a new data source type, a Grid Link Data Source, to provide enhanced support for Oracle RAC. For more information, see "Using Grid Link Data Sources" in Configuring and Managing JDBC for Oracle WebLogic Server

Reorganization of JDBC Resources and Data Source Factories in the Administration Console

As of WebLogic Server 10.3.4, the presentation of JDBC resources and Data Source Factories in the Domain Tree in the WebLogic Server Administration Console have changed as follows:

Generic Data Sources, Grid Link Data Sources, and Multi Data Sources are all located under the Services > Data Sources branch.

Data Source Factories (deprecated) are still supported in this release but do not appear in the domain tree unless you have upgraded an existing domain that contains Data Source Factories. If your upgraded domain contains Data Source Factories, they are located under the Services > Data Source Factories branch.

Socket Direct Protocol

This release supports Socket Direct Protocol (SDP), a high-performing socket implementation. If your environment supports SDP, see "Enable Socket Direct Protocol for a network channel" in the Oracle WebLogic Server Administration Console Help.

Connection-based System Properties

This release supports setting driver properties using the value of system properties. The value of each property is derived at run time from the named system property. You can configure connection-based system properties using the Administration Console by editing the System Properties attribute of your data source configuration.

Keep Connection After Local Transaction

This release provides a new attribute on the JDBCXAParamsBean, KeepLogicalConnOpenOnRelease, which enables WebLogic Server to keep a physical database connection associated with a logical connection when committing or rolling back a local transaction. See KeepLogicalConnOpenOnRelease in the Oracle WebLogic Server MBean Reference.

getVendorConnectionSafe

This release provides the getVendorConnectionSafe method on the weblogic.jdbc.extensions.WLConnection interface to access a physical connection. Similar to the getVendorConnection method, this mechanism returns the underlying physical connection (the vendor connection) from a pooled database connection (a logical connection). However, when the connection is closed, it is returned to the pool, independent of the setting of the JDBCConnectionPoolParamsBean.RemoveInfectedConnections attribute. For some applications, the getVendorConnectionSafe method may enhance performance by eliminating the excessive creation of connections. For more information, see "Getting a Physical Connection from a Data Source" in Programming JDBC for Oracle WebLogic Server.

JDBC Debugging Enhancements

Two diagnostic monitors were added in WebLogic Server 9.0 that can be configured in a WLDF module at the server level to provide additional visibility when JDBC connections are reserved and released:

JDBC_After_Reserve_Connection_Internal

JDBC_After_Release_Connection_Internal

For more information, see "Diagnostic Monitor Library" in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.

Miscellaneous New Features

The following features were added in WebLogic Server 10.3.3:

Bulk Load — improves and expands upon current methods for inserting mass amounts of data into a database as quickly as possible.

Freeze/unfreeze the statement pool — allows you to "freeze" the state of the statement pool. When frozen, important statements in the statement pool remain in the pool and are not replaced until the connection is closed or the application "unfreezes" the state of the statement pool.

For more information about new JDBC features, see What's New in Oracle WebLogic Server.

JMS

Note the following changes to JMS:

Modular Configuration and Deployment of JMS Resources

JMS Message ID Format

Improved Message Paging

Modular Configuration and Deployment of JMS Resources

As of WebLogic Server 9.0, JMS configurations are stored as modules, defined by XML documents that conform to the new weblogic-jmsmd.xsd schema. With modular deployment of JMS resources, you can promote your application and the JMS configuration from one environment to another. For example, you can promote your application and the required JMS configuration from a testing environment to a production environment, without opening an EAR file and without extensive manual JMS reconfiguration.

For more information, see:

"New and Changed JMS Features in This Release" in Configuring and Managing WebLogic JMS (published for WebLogic Server 9.0, available at http://download.oracle.com/docs/cd/E13222_01/wls/docs90/jms_admin/intro.html#WhatsNewJMS).

"Understanding JMS Resource Configuration" in Configuring and Managing JMS for Oracle WebLogic Server.

"Deploying JDBC, JMS, and WLDF Application Modules" in Deploying Applications to Oracle WebLogic Server.

The WebLogic Upgrade Wizard automatically converts pre-9.0 JMS resources to a JMS Interop module file named interop-jms.xml, which is copied to the domain's config\jms directory. For more information, see "JMS Interop Modules" in Configuring and Managing JMS for Oracle WebLogic Server.

Please note the following JMS configuration changes:

When generating new JMS resources, you must define all attributes in the JMS module (that is, not using the pre-9.0 configuration file).

The Allow Persistent Downgrade option enables you to specify whether JMS clients receive an exception when they send persistent messages to a destination targeted to a JMS server that does not have a persistent store configured. This option is provided for backward compatibility with previous releases.

By default, the option is set to false, specifying that clients receive an exception when they send persistent messages to a JMS server for which no store is configured. When the option is set to true, persistent messages are downgraded to non-persistent, but, the send operations are allowed to continue. This parameter is effective only when the Store Enabled parameter is disabled (that is, when it is set to false).

For more information, see "AllowsPersistentDowngrade" in "JMSServerBean" in Oracle WebLogic Server MBean Reference.

A Temporary Template is created, by default, for JMS Servers. In previous releases, no default template was provided. You can also configure a temporary template, using the JMS server's Temporary Template attribute.

You can control whether the JMS Server can host a temporary destination by setting the Hosts Temporary Destinations attribute. In previous releases, a JMS Server was enabled to host temporary destinations if and only if the TemporaryTemplate attribute was set.

JMS templates specified for distributed destinations are no longer supported as of WebLogic Server 9.0, and they are ignored. As of WebLogic Server 9.0, this functionality is replaced by uniform distributed destinations. For more information, see "Creating Uniform Distributed Destinations" in Configuring and Managing JMS for Oracle WebLogic Server.

The AllowCloseInOnMessage attribute for JMS Connection Factories is enabled by default. For more information, see "ClientParamsBean" in Oracle WebLogic Server MBean Reference.

Usage of the getExpirationLoggingPolicy attribute in the DeliveryFailureParamsBean should be updated in your applications to use the Message Life Cycle Logging feature described in "Message Life Cycle Logging" in Configuring and Managing JMS for Oracle WebLogic Server. It should also be noted that the getExpirationLoggingPolicy attribute now removes any leading and trailing white space that may have been embedded in an application. For information about other functionality that has been deprecated in WebLogic Server, see "Deprecated Functionality (WebLogic Server 11g Release 1)" in What's New in Oracle WebLogic Server.

JMS Message ID Format

As of WebLogic Server 9.0, the format of the JMS message ID has changed. Oracle continues to support the pre-9.0 format for existing consumers, producers, and servers. For example, existing JMS consumers may continue to view messages in the pre-9.0 format, even when received from a new JMS producer and JMS server.

Improved Message Paging

As of WebLogic Server 9.0, the message paging feature for freeing up JVM heap space during peak message load situations is always enabled on JMS servers. Additionally administrators are not required to create a dedicated message paging store because paged out messages can be stored in a directory on your file system. However, for the best performance you should specify that messages be paged to a directory other than the one used by the JMS server's persistent store.

See "Paging Out Messages To Free Up Memory" in Performance and Tuning for Oracle WebLogic Server.

Messaging

As of WebLogic Server 10.3.3, the following messaging features have changed:

Changes to weblogic.jms.extension API

The following internal methods of the weblogic.jms.extensions.WLMessage interface have been removed from the Oracle WebLogic Server API Reference:

public void setSAFSequenceName(String safSequenceName);
public String getSAFSequenceName();
public void setSAFSeqNumber(long seqNumber);
public long getSAFSeqNumber();

Your applications should not use these internal methods. Internal methods may change or be removed in a future release without notice.

Persistent Store Updates

As of release 10.3.3, WebLogic File Store behavior and tuning have changed for default file stores and custom file stores. For more information, see WebLogic Persistent Store.

Plug-Ins

The version 1.1 plug-ins provided with WebLogic Server as of release 10.3.3 contain the following new features:

Apache Plug-In support for Oracle HTTP Server

Standard encryption strength support for simplified naming

Use of Oracle SSL Toolkit

Use of Oracle Security Framework

Support for IPv6

Support for two-way SSL

For information about these features, see Using Web Server 1.1 Plug-Ins with Oracle WebLogic Server.

Thread Management

Oracle recommends using Work Manager concepts to manage threads because execute queues are no longer the default method used as of WebLogic Server 9.0. You define the rules and constraints for your application by defining a Work Manager and applying it either globally to a WebLogic domain or specifically to an application component. For more information, see "Using Work Managers to Optimize Scheduled Work" in Configuring Server Environments for Oracle WebLogic Server.

In WebLogic Server 8.1, processing was performed in multiple execute queues. If you had been using execute queues to improve performance in 8.1, you may continue to use them after you upgrade your application domains. Oracle provides a use81-style-execute-queues flag that enables you to disable the self-tuning execute pool and provide backward compatibility for upgraded applications to continue to use user-defined execute queues. For information about enabling the backward compatibility flag, and configuring and monitoring execute queues, see "How to Enable the WebLogic 8.1 Thread Pool Model" in WebLogic Server Performance and Tuning for Oracle WebLogic Server.

JTA

The following sections describe JTA feature changes:

Resource Registration Name

JTA Transaction Log Migration

Resource Registration Name

As of WebLogic Server 10.3.1, the behavior of the resource registration name for XA data source configurations has changed. In previous releases, the JTA registration name was simply the name of the data source. Now, the registration name is a combination of data source name and domain.

For more information, see "Registering an XAResource to Participate in Transactions" in Programming JTA for Oracle WebLogic Server.

JTA Transaction Log Migration

All JTA domain configuration options are persisted from the legacy configuration file. The only changes are at the server level. As of WebLogic Server 9.0, the Transaction Manager uses the default WebLogic persistent store to store transaction log records. During the upgrade, the Upgrade Wizard copies transaction log records to the default store. The transaction log file prefix from the existing server configuration is used only to locate the transaction log (.tlog) files during an upgrade; it is not preserved after the upgrade.

If the entire domain resides on a single computer, the Upgrade Wizard handles the upgrade (and copies transaction log records to the default store) for all Managed Servers during the initial domain upgrade. If Managed Servers reside on separate machines, you must upgrade each Managed Server individually, as described in Upgrade Your Application Environment.

Please note the following:

When an explicit upgrade is performed (see Upgrading a Domain), transaction recovery does not run during the upgrade process, but it starts running when you start the server(s).

When an implicit upgrade is performed, as described in Appendix F, "Upgrading a Domain at Administration Server Startup (Implicit Mode)," transaction recovery runs during the server boot process.

If you have put your transaction log files in network storage in preparation for Transaction Recovery Service migration, the log file location is not preserved after the upgrade. In this release, the WebLogic Server Transaction Manager uses the WebLogic default persistent store to store transaction log files. You can achieve the same result by moving the location of the WebLogic default persistent store to a network location. Note that you must manually copy the DAT file from the default location of the current default store to the new location of the default store.

If transactions span multiple domains, you must configure your domain to enable inter-domain transactions. For more information, see "Configuring Domains for Inter-Domain Transactions" in Programming JTA for Oracle WebLogic Server.

Enterprise Java Beans (EJBs)

In this release, you can leverage the features of Oracle TopLink with your EJB 3.0 applications. Oracle TopLink is an advanced, object-persistence and object-transformation framework that provides development tools and run-time capabilities that reduce development and maintenance efforts, and increase enterprise application functionality. For more information, see Oracle Fusion Middleware Developer's Guide for Oracle TopLink.

In addition, when you use Oracle TopLink as the persistence provider in this release of WebLogic Server, you can install a patch that provides support for Java Persistence Architecture (JPA) 2.0. JPA 2.0 includes improvements and enhancements to domain modeling, object/relational mapping, EntityManager and Query interfaces, and the Java Persistence Query Language (JPQL), and more. For more information, see "Using JPA 2.0 with TopLink in WebLogic Server" in Programming WebLogic Enterprise JavaBeans, Version 3.0 for Oracle WebLogic Server.

Middleware Home Directory

As of WebLogic Server 10.3.1, the notion of the BEA Home directory is replaced by the Middleware Home. The default path of this directory is <drive:>Oracle/Middleware. This change has the following impact on WebLogic Server:

A new environment variable is introduced in several WebLogic scripts in 10.3.1 to represent the Middleware Home directory: MW_HOME. The directory to which this variable is set generally is the same as BEA_HOME, which is also still used in WebLogic Server scripts.

By default, the WebLogic Server installation program selects <drive:>Oracle/Middleware as the root product installation directory. However, if a directory containing an existing WebLogic Server installation is detected, that directory is selected instead by default.

The WebLogic Server 10.3.1 documentation now uses the term Middleware Home, instead of BEA Home. However, this revision is functionally only a change in terminology and does not imply that any WebLogic software, custom domains, or applications must be moved, or that any existing environment variables that represent those locations must be changed.

This change does not affect any existing WebLogic Server installations, custom domains, applications, or scripts on your computer. You may continue to use the BEA_HOME environment variable as before.

Security

The following sections identify changes to security.

SSL Support Changes

Performance Enhancements for Security Policy Deployment

Deprecated Authentication Providers

XACML Security Providers

SAML V2 Providers

SAML 2.0 Providers

Oracle Internet Directory and Oracle Virtual Directory Authentication Providers

RDBMS Security Store

Password Validation Provider

Security MBeans

Password Encryption

Security for HTTP Requests

Secure Access to MBeanHome

Message-Level Security in Web Services

RSA Cryptographic Services Upgrade

Validation of Security Certificates

SAML Single Sign-On Attribute Support

SSL Support Changes

As of WebLogic Server 10.3.3, the Certicom SSL implementation in Weblogic Server is replaced with an SSL implementation based on Java Secure Socket Extension (JSSE). JSSE is the Java standard framework for SSL and TLS and includes both blocking-IO and non-blocking-IO APIs, and a reference implementation including several commonly-trusted CAs.

Note also the following:

The Certicom SSL implementation will eventually be removed from WebLogic Server. However, this release of WebLogic Server continues to support the Certicom SSLPlus Java version 4.0 SSL implementation, as well as RSA Cert-J version 2.1.1 and Crypto-J version 3.5.

The SSLMBean has been modified in this release to support additional SSL configuration capabilities, including the ability to enable or disable the JSSE adapter.

For a list of the differences in the way the JSSE SSL implementation handles the WebLogic system properties, see "System Property Differences Between the JSSE and Certicom SSL Implementations" in Securing Oracle WebLogic Server.

For more information about SSL support in WebLogic Server, see "Secure Sockets Layer (SSL)" in Understanding Security for Oracle WebLogic Server.

Performance Enhancements for Security Policy Deployment

As of release 10.3.3, WebLogic Server includes a deployment performance enhancement for Deployable Authorization providers and Role Mapping providers that are thread safe. Weblogic Server by default supports thread-safe parallel modification to security policy and roles during application and module deployment. For this reason, deployable Authorization and Role Mapping providers configured in the security realm should support parallel calls. The WebLogic deployable XACML Authorization and Role Mapping providers meet this requirement.

However, if your custom deployable Authorization or Role Mapping providers do not support parallel calls, you must disable the parallel security policy and role modification and instead enforce a synchronization mechanism that results in each application and module being placed in a queue and deployed sequentially. You can turn on this synchronization enforcement mechanism from the Administration Console or by using the DeployableProviderSynchronizationEnabled and DeployableProviderSynchronizationTimeout attributes of the RealmMBean.

See "Enabling Synchronization in Security Policy and Role Modification at Deployment" in Securing Oracle WebLogic Server for additional information.

Deprecated Authentication Providers

For information about Authentication providers that have been deprecated in WebLogic Server, see "Deprecated Functionality (WebLogic Server 11g Release 1)" in What's New in Oracle WebLogic Server. Use one or more of the other supported Authentication providers instead.

XACML Security Providers

As of 9.1, WebLogic Server includes two new security providers, the XACML Authorization provider and the XACML Role Mapping provider. Previous releases of WebLogic Server used an authorization provider and a role mapping provider based on a proprietary security policy language. These XACML security providers support the eXtensible Access Control Markup Language (XACML) 2.0 standard from OASIS. These providers can import, export, persist, and execute policy expressed using all standard XACML 2.0 functions, attributes, and schema elements.

WebLogic domains created using WebLogic Server 9.1 and later include the XACML providers by default. The new XACML providers are fully compatible with policies and roles created using the WebLogic Authorization provider (DefaultAuthorizer) and WebLogic Role Mapping provider (DefaultRoleMapper). Existing WebLogic domains that you upgrade to 10.3.6 continue to use the authorization and role mapping providers currently specified, such as third-party partner providers or the original WebLogic Authorization and Role Mapping providers. If you want, you can migrate existing domains from using WebLogic Server proprietary providers to the XACML providers, including performing bulk imports of existing policies. For more information, see "Security" in Information Roadmap for Oracle WebLogic Server .

SAML V2 Providers

For SAML 1.1 support, new versions of the SAML Credential Mapping provider and SAML Identity Assertion provider were added in WebLogic Server 9.2. The SAML Credential Mapping V1 provider and SAML Identity Assertion V1 provider are still available in WebLogic Server, but you should use the V2 versions of the SAML Credential Mapping and SAML Identity Assertion providers instead.

Although the version number of the providers has been incremented to V2, the new SAML security providers implement the SAML 1.1 standard, as did the V1 providers.

Note:

For web single sign-on, the SAML 1.1 providers described in this section are not compatible with a WebLogic Server instance that has been configured with SAML 2.0 services.

SAML 2.0 Providers

For SAML 2.0 support, the SAML 2.0 Credential Mapping provider and SAML 2.0 Identity Assertion provider were added in WebLogic Server 10.3. These new providers can be used, respectively, to generate and consume SAML 2.0 assertions in the following use cases:

SAML 2.0 Web Single Sign-On Profile

WS-Security SAML Token Profile version 1.1

For SAML 2.0 Web Single Sign-On, the assertions generated by the SAML 2.0 Credential Mapping provider may be consumed only by the SAML 2.0 Identity Assertion provider. They are not compatible with SAML 1.1 assertions.

SAML Token Profile 1.1 is supported by WebLogic Server Web Services as of Release 10.3. This feature includes support for SAML 2.0 and SAML 1.1 assertions, and is backward compatible with SAML Token Profile 1.0 SAML tokens are configured for a Web Service through use of the appropriate WS-SecurityPolicy assertions.

Note:

SAML Token Profile 1.1 is supported only through WS-SecurityPolicy. The earlier "WebLogic Server 9.2 Security Policy" supports SAML Token Profile 1.0/SAML 1.1 only.

Oracle Internet Directory and Oracle Virtual Directory Authentication Providers

Two new LDAP authentication providers were added to WebLogic Server 10.3.2 — the Oracle Internet Directory Authentication Provider and the Oracle Virtual Directory Authentication Provider. These authentication providers can store users and groups in, and read users and groups from, the Oracle Internet Directory and Oracle Virtual Directory LDAP servers, respectively.

For information about configuring and using these new security providers, see "Configuring LDAP Authentication Providers" in Securing Oracle WebLogic Server.

RDBMS Security Store

WebLogic Server 10.3 added the option of using an external RDBMS as a data store that is used by the following security providers:

XACML Authorization provider

XACML Role Mapping provider

The following providers for SAML 1.1:

SAML Identity Assertion provider V2

SAML Credential Mapping provider V2

The following providers for SAML 2.0:

SAML 2.0 Identity Assertion provider

SAML 2.0 Credential Mapping provider

WebLogic Credential Mapping provider

PKI Credential Mapping provider

Certificate Registry

This data store, called the RDBMS security store, is strongly recommended for the use of SAML 2.0 services in two or more WebLogic Server instances in that domain, such as in a cluster. When the RDBMS security store is configured in a domain, an instance of any of the preceding security providers that has been created in the security realm automatically uses only the RDBMS security store as a data store, and not the embedded LDAP server. WebLogic security providers configured in the domain that are not among those in the preceding list continue to use their respective default stores; for example, the WebLogic Authentication provider continues to use the embedded LDAP server.

In order to use the RDBMS security store, the preferred approach is first to create a domain in which the external RDBMS server is configured. Before you boot the domain, create the tables in the data store that are required by the RDBMS security store. The WebLogic Server installation directory contains a set of SQL scripts that create these tables for each supported database.

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.

Password Validation Provider

The Password Validation provider was added in WebLogic Server 10.3. This provider can be configured with one of the following authentication providers to enforce a set of configurable password composition rules:

WebLogic Authentication provider

SQL Authenticator provider

LDAP Authentication provider

Active Directory Authentication provider

iPlanet Authentication provider

Novell Authentication provider

Open LDAP Authentication provider

When a password is created or modified using an authentication provider that has been configured with the Password Validation provider, the password is automatically validated against a set of composition rules. The password composition rules are configurable and can govern the minimum length of passwords, minimum number of alphabetic or numeric characters that are required, the number of non-alphanumeric characters that are required, and more.

As of WebLogic Server 10.3.2, the Password Validation provider can be configured in the WebLogic Server Administration Console.

Security MBeans

Table B-2 lists the changes to security MBeans as of WebLogic Server 9.0.

Table B-2 Changes to Security MBeans as of WebLogic Server 9.0

Type of Security MBean
Description

All security MBeans

In WebLogic Server 8.1, when you updated a security MBean attribute, the values were available to the security configuration and management hierarchy immediately, and to the security run-time hierarchy following a server reboot.

As of WebLogic Server 9.0, whether a security MBean attribute change is effective and available to the configuration, management, and run-time hierarchies immediately or upon server reboot is controlled by setting that attribute as dynamic or non-dynamic. For more information, see Dynamic Configuration Management.

RealmMBean, UserLockoutManagerMBean, and all security provider MBeans

In place of the wls_getDisplay method, you should use the new getName method instead. In addition, the following security methods have been removed:

wls_getAttributeTag
wls_getConstructorTag
wls_getMBeanTag
wls_getNotificationTag
wls_getOperationTag

The weblogic.Admin tools and pre-9.2 JMX security APIs can no longer be used to configure security MBeans. These utilities and APIs can still be used, however, to view and invoke methods on the security MBeans.

For security provider MBeans (only):

When adding or removing a security provider, you must reboot the server before any changes take effect.

When modifying an existing security provider, if you modify any non-dynamic attributes, the server must be rebooted before any (that is, non-dynamic or dynamic) changes take effect. For more information, see Dynamic Configuration Management.

All custom security provider MBeans

By default, all custom security provider MBeans attributes are non-dynamic. For more information, see Dynamic Configuration Management.

You can set an MBean attribute to be dynamic by setting Dynamic="true" for the attribute within the MDF file. For example:

<MBeanAttribute
Name        = "Foo"
Type        = "java.lang.String"
Dynamic = "true"
Description = "Specifies that this attribute is a dummy."
/>

Password Encryption

To prevent unauthorized access to sensitive data such as passwords, some attributes in configuration MBeans are encrypted. The attributes persist their values in the domain configuration files as an encrypted string. For further security, the in-memory value is stored in the form of an encrypted byte array to help reduce the risk of the password being snooped from memory.

In pre-9.0 releases, you could edit the config.xml file to specify an encrypted attribute, such as a password, in clear-text or encrypted format. In this case, when booted, the WebLogic Server encrypts the information the next time it writes to the file.

As of WebLogic Server 9.0, when operating in production mode, the password of an encrypted attribute must be encrypted in the configuration files. In development mode, the password of an encrypted attribute can be either encrypted or clear-text.

You can use the weblogic.security.Encrypt command-line utility to encrypt the passwords, as follows:

java weblogic.security.Encrypt

You are prompted to enter a password, and the command returns the encrypted version. Then, copy the encrypted password returned into the appropriate file.

This utility is not just used for passwords in the configuration files. It can also be used to encrypt passwords in descriptor files (for example, a JDBC or JMS descriptor) and in deployment plans. For more information, see "encrypt" in Command Reference for Oracle WebLogic Server.

Security for HTTP Requests

By default, when an instance of WebLogic Server responds to an HTTP request, its HTTP response header does not include the WebLogic Server name and version number. This behavior is different from releases before WebLogic Server 9.0.

To have the name and version number included in the HTTP response header when responding to an HTTP request, enable the Send Server Header attribute for the WebLogic Server instance in the Administration Console. The attribute is located on the Server > ServerName > Protocols > HTTP tab under the Advanced Options section. Note that enabling this feature may creates a security risk if a possible attacker knows about a vulnerability in the specified version of WebLogic Server.

For more information about ensuring security, see "Securing the WebLogic Security Service" in "Ensuring the Security of Your Production Environment" in Securing a Production Environment for Oracle WebLogic Server.

Secure Access to MBeanHome

In pre-9.0 releases of WebLogic Server, anonymous access to MBeanHome was enabled by default. With the security enhancements delivered as of WebLogic Server 9.0, anonymous access to MBeanHome is no longer allowed.

Although doing so is not recommended, you can re-enable anonymous access by specifying the following flag when starting the server:

-Dweblogic.management.anonymousAdminLookupEnabled

Message-Level Security in Web Services

As of WebLogic Server 9.0, message-level security in Web Services is enhanced to use the standards-based Web Services Policy Framework (WS-Policy). WS-Policy provides a flexible and extensible grammar for expressing the capabilities, requirements, and general characteristics of entities in an XML Web Services-based system. For more information about WS-Policy, see "Using WS-SecurityPolicy 1.2 Policy Files" in Security and Administrator's Guide for Web Services.

In 8.1, the implementation was based on an OASIS implementation of the Web Services Security (WSS) standard. This implementation is supported for backward compatibility. For more information about this implementation, see http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss. For information about functionality that is deprecated in WebLogic Server, see "Deprecated Functionality (WebLogic Server 11g Release 1)" in What's New in Oracle WebLogic Server.

RSA Cryptographic Services Upgrade

As of version 10.3.4, WebLogic Server supports the RSA cryptographic services in JDK 6. For information about SSL support in WebLogic Server, see "Secure Sockets Layer (SSL)" in Understanding Security for Oracle WebLogic Server.

Validation of Security Certificates

As of release 10.3.4, WebLogic Server adds the ability to examine details contained in an end user request to determine whether authentication should succeed or fail. The details may include the end user's certificate, Subject, and IP address. For more information about this feature, see "Checking the Validity of End User Certificates" in Securing Oracle WebLogic Server.

SAML Single Sign-On Attribute Support

WebLogic Server 10.3.6 enhances the SAML 1.1 and 2.0 Credential Mapping provider and Identity Assertion provider mechanisms to support the use of a custom attribute mapper that can obtain additional attributes (other than group information) to be written into SAML assertions, and to then map attributes from incoming SAML assertions. For more information, including details about the SAML attribute APIs that have been added for this enhancement and examples, see "Configuring SAML Single Sign-On Attribute Support" in Programming Security for Oracle WebLogic Server.

WebLogic Service Component Architecture (WebLogic SCA)

As of WebLogic Server 10.3.3, WebLogic SCA supports the following new features:

Enhanced data binding support in Web Service bindings:

SOAP attachments in TopLink/EclipseLink JAXB bindings. Both SOAP Message Transmission Optimization Mechanism (MTOM) and SOAP Messages with Attachments (SwA) are supported.

Java Collection Objects in TopLink/EclipseLink JAXB bindings.

Dispatch policies for EJB service bindings

For more information about WebLogic SCA, see Developing WebLogic SCA Applications for Oracle WebLogic Server.

Web Services

WebLogic Server 8.1 Web Services can be run in version 9.0 and later, although the 8.1 Web Services run-time engine has been deprecated as of 9.0.

No Web service upgrade is required going from 9.2 to 10.0, or from 10.0 to either 10.3 or 10.3.x.

Oracle strongly recommends that you upgrade all of your 8.1 Web services to 10.3.6.

For information about upgrading your existing 8.1 Web Services to 10.3.6, see "Upgrading WebLogic Web Services From Previous Releases to 10g Release 3" in Getting Started With JAX-RPC Web Services for Oracle WebLogic Server.

Note:

See also Message-Level Security in Web Services.

New Web Services Features

The following new features have been added in WebLogic Server as of release 10.3.3:

Support for Web services atomic transactions — WebLogic Web services enable interoperability with other external transaction processing systems, such as WebSphere, JBoss, Microsoft .NET.

Enhanced support for Web services in a clustered environment

Enhanced monitoring of Web services and clients

Attachment of Oracle WSM policies to WebLogic Web services using Fusion Middleware Control

EclipseLink DBWS support for declarative Web service solution for accessing relational databases

Method-Level policy attachment behavior change — Before WebLogic Server 10.3.3, if a policy was attached, through the Administration Console, to a method of one Web service, the policy was also attached to all methods of the same name for all Web services in that module. As of WebLogic Server 10.3.3, the policy is attached only to the method of the appropriate Web service.

policy: prefix now removed from OWSM policy names

Web services WSDL tab now removed — Before WebLogic Server 10.3.3, you could view the WSDL for the current Web service by selecting the Configuration > WSDL tab. The WSDL tab has been removed as of WebLogic Server 10.3.3.

New development tools — Oracle JDeveloper and Oracle Enterprise Pack for Eclipse (OEPE)

Integration with Oracle Enterprise Manager Fusion Middleware Control

Support for Oracle WebLogic Services Manager (WSM) security policies

Support for WS-SecureConversation 1.3 on JAX-WS and MTOM with WS-Security on JAX-WS

For more information, see "Web Services" in What's New in Oracle WebLogic Server.

Web Applications, JSPs, and Servlets

The following sections provide important compatibility information for Web applications, JSPs, and Servlets in WebLogic Server 10.3.6:

ActiveCache

Class Caching

Deprecated and Obsolete Web Application Features

BASIC Authentication with Unsecured Resources

Backward Compatibility Flags

Servlet Path Mapping

ActiveCache

As of WebLogic Server 10.3.3, applications deployed on WebLogic Server can easily use Coherence data caches, and seamlessly incorporate Coherence*Web for session management and TopLink Grid as an object-to-relational persistence framework. Collectively, these features are called ActiveCache.

ActiveCache provides replicated and distributed data management and caching services that you can use to reliably make an application's objects and data available to all servers in a Coherence cluster.

For more information, see Using ActiveCache.

Class Caching

As of release 10.3.3, WebLogic Server allows you to enable class caching. The advantages of using class caching are:

Reduces server startup time.

The package level index reduces search time for all classes and resources.

Class caching is supported in development mode when starting the server using a startWebLogic script. Class caching is disabled by default and is not supported in production mode. The decrease in startup time varies among different JRE vendors. For more information, see "Configuring Class Caching" in Developing Applications for Oracle WebLogic Server.

Deprecated and Obsolete Web Application Features

For a list of Web application features that are deprecated or are not supported as of WebLogic Server 10.3.6, see "Deprecated Functionality (WebLogic Server 11g Release 1)" in What's New in Oracle WebLogic Server.

BASIC Authentication with Unsecured Resources

For WebLogic Server versions 9.2 and later, client requests that use HTTP BASIC authentication must pass WebLogic Server authentication, even if access control is not enabled on the target resource.

The setting of the Security Configuration MBean flag "enforce-valid-basic-auth-credentials" determines this behavior. (The DomainMBean can return the new Security Configuration MBean for the domain.) It specifies whether the system should allow requests with invalid HTTP BASIC authentication credentials to access unsecured resources.

Note:

The Security Configuration MBean provides domain-wide security configuration information. The enforce-valid-basic-auth-credentials flag effects the entire domain.

The enforce-valid-basic-auth-credentials flag is true by default, and WebLogic Server authentication is performed. If authentication fails, the request is rejected. WebLogic Server must therefore have knowledge of the user and password.

See "Understanding BASIC Authentication with Unsecured Resources" in Programming Security for Oracle WebLogic Server for complete information.

Backward Compatibility Flags

For WebLogic Server 10.0 and later, backward compatibility for WebLogic Server 9.2 or earlier is supported by using the backward-compatible element within the jsp-descriptor element, as described in this section and in "jsp-descriptor" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.

JSP 2.1 Support and Compatibility With JSP 2.0 Web Applications

JSP 2.1 is supported as of WebLogic Server 10.0. Depending on the version of the Web application (version 2.4 or 2.5) and the setting of the backward-compatible element, Weblogic Server 10.0 and later also supports JSP 2.0.

See "Backward Compatibility Flags" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server for important information about the buffer suffix setting and implicit servlet 2.5 package imports.

Support for JSP 2.0

JSP 2.0 was supported as of WebLogic Server 9.0, and continues to be supported as described in Backward Compatibility Flags. Please note the following changes to the JSP behavior as required in support of JSP 2.0:

If a JSP does not participate in a session (or if the session in which a JSP participates is invalid), an IllegalStateException is thrown when the following command is executed:

PageContext.getAttribute(name, PageContext.SESSION_SCOPE)

If you are not concerned about this type of error, you can catch and ignore it.

JspWriterImpl now replaces \n with System.getProperty("line.separator") for each printline function. This replacement causes problems with JSPs that:

Contain multiple page directives that appear on new lines. For example:

<%@ page import="com.foo.bar.*" %>
<%@ page import="com.foo.xyz.*" %>
...

Generate output in XML format.

Generate an XML declaration following the page directives.

Are served by Windows systems. In this case, \r\n is output for each page directive.

Are viewed using Internet Explorer.

When viewed in Internet Explorer, each page directive outputs an empty \r\n and the XML declaration (<?xml version="1.0" encoding="iso-8859-1"?>) appears after every new line. Internet Explorer displays an error message indicating that it cannot locate the declaration and that the page cannot be viewed, even though it can be compiled.

To work around any issues caused by changes to JspWriterImpl, you can perform one or both of the following tasks:

Define the XML declaration at the top of the page.

Group the page directives into a single declaration, for example:

<%@ page import="com.foo.bar.*, com.foo.baz.*"
contentType="text/html" pageEncoding="UTF-8" errorPage="Error.jsp" %>

The JSP <param name> tag no longer allows run-time expression values. For example:

<jsp:param name="<%= AdminActions.RETURN_LINK %>" value="<%= returnlink %>" />

You can continue to support this feature by disabling the Do not set backward compatibility flags upgrade option during the domain upgrade, as described in "Select Upgrade Options" in Table 5-1, or enabling the backwardCompatible flag in the weblogic.xml file, as follows:

<jsp-descriptor>
<jsp-param>
<param-name>backwardCompatible</param-name>
<param-value>true</param-value>
</jsp-param>
</jsp-descriptor>

Servlet Path Mapping

As of version 2.3 of the Java Servlet Specification, the following syntax is used to define mappings:

A servlet path string that contains only the / (slash) character indicates the default servlet of the application. The servlet path resolves to the request URI minus the context path; in this case, the path resolves to null.

A String that begins with an * (asterisk) specifies an extension mapping.

These changes introduce a change in behavior with the following HttpServletRequest methods:

getPathInfo

getServletPath

To better illustrate the change in behavior, consider the request /abc/def.html that resolves to ServletA:

If / maps to ServletA, then servletPath="abc/def.html" and pathInfo=null.

If /* maps to ServletA, then servletPath="" and pathInfo="abc/def.html".

To ensure that the path info returned is non-null, replace all occurrences of the / (slash) servlet mapping string with /*.

The Java Servlet Specification can be downloaded from the following location:

http://www.oracle.com/technetwork/java/javaee/servlet/index.html

XML Implementation

Please note the following changes to XML support as of WebLogic Server 9.0:

The default XML parser is the XML parser shipped with the Sun Java 2 JDK. The previous default XML parser, the Apache Xerces parser (weblogic.apache.xerces.*), is deprecated as of 9.0.

You can modify the XML parser that is used by default using the Administration Console. For information about configuring the XML parser, see "Difference In Default Parsers Between Versions 8.1 and 9.0 of WebLogic Server" in Programming XML for Oracle WebLogic Server.

As of 9.0, WebLogic Server supports Streaming API for XML (StAX), a standard specification from the Java Community Process that provides an easy and intuitive means of parsing and generating XML documents. StAX gives you more control over XML parsing than the WebLogic XML Streaming API, which is deprecated as of 9.0. For information about using StAX, see "Using the Streaming API for XML (StAX)" in Programming XML for Oracle WebLogic Server.

You can no longer parse XML documents from within a servlet using the setAttribute and getAttribute methods without some preliminary setup. Specifically, as of 9.0, you must configure a WebLogic Server servlet filter called weblogic.servlet.XMLParsingHelper (deployed, by default, on all WebLogic Server instances) as part of your Web application. For more information, see "Parsing XML Documents in a Servlet" in Programming XML for Oracle WebLogic Server.

XMLBeans and XQuery Implementation

As of 9.0, the XMLBean implementation in WebLogic Server has been moved from an internal library (com.bea.xml) to the Apache open source project (org.apache.xmlbeans).

If you used XMLBeans in your WebLogic Server 8.1 applications, you must perform the following steps:

Update the package name used by XMLBeans from com.bea.xml to org.apache.xmlbeans.

Recompile your XMLBean schemas to update the schema metadata (.xsb) files and generated code.

As of 9.0, the XMLQuery (XQuery) implementation conforms to the following specifications:

XQuery 1.0 and XPath 2.0 Data Model—W3C Working Draft 23 July 2004 available from the W3C Web site at http://www.w3.org/TR/2004/WD-xpath-datamodel-20040723.

XQuery 1.0: An XML Query Language—W3C Working Draft 23 July 2004 available from the W3C Web site at http://www.w3.org/TR/2004/WD-xquery-20040723.

In WebLogic Server 8.1, the XQuery implementation conformed to XQuery 1.0 and XPath 2.0 Functions and Operators—W3C Working Draft 16 August 2002, available from the W3C Web site at http://www.w3.org/TR/2002/WD-xquery-operators-20020816/. The 2002 XQuery implementation is deprecated as of 9.0.

In most cases, simple XQuery and XPath operations in pre-9.0 code behaves the same in 10.0. To ensure that the XQuery and XPath operations produce the expected results, you can review or update the existing XMLObject.selectPath() and XMLObject.execQuery() method calls using one of the following methods:

To guarantee 8.1-style behavior, update the existing method calls to include a new parameter that specifies that the 2002 XQuery engine is to be used instead of the new 2004 XQuery engine. For example:

import org.apache.xmlbeans.impl.store.Path;
XmlObject xo = ?
xo.selectPath(".//c", (new XmlOptions()).put(Path._forceXqr12002ForXpathXQuery));

Note:

The 2002 XQuery engine is deprecated as of WebLogic Server 9.0, and is available for backward compatibility. It is only used if you specify this parameter. Otherwise, the 2004 XQuery engine is used, by default.

To guarantee conformance with the 2004 XQuery engine, review your pre-9.0 scripts to identify any changes that may be required with the syntax or semantics of the XQuery strings that are passed to the method calls and update methods accordingly.

As of 9.0, the behavior of XMLCursor.moveXML() has changed. In 8.1, a cursor that was inside a moved fragment remained on the original document. As of 9.0, cursors move with fragments.

WebLogic Administration and Configuration Scripts

Due to changes with the MBean hierarchy, Oracle does not guarantee that pre-9.2 configuration and administration scripts (such as WLST, wlconfig, weblogic.Admin, Ant, and so on) run in 10.3.6. Oracle recommends that you update your scripts to take advantage of the new features provided in WebLogic Server in version 9.2 and later. For more information about new features and changes in the MBean hierarchy, see the documents listed in Table B-3:

Table B-3 New Features in WebLogic Server by Release

For the following release . . .
. . . see the following for a description of new features

9.2

"What's New in WebLogic Server 9.2" at:

http://download.oracle.com/docs/cd/E13222_01/wls/docs92/notes/new.html

10.0

"What's New in WebLogic Server 10.0" at:

http://download.oracle.com/docs/cd/E13222_01/wls/docs100/notes/new.html

10.3

"What's New in WebLogic Server" for version 10.3 at:

http://download.oracle.com/docs/cd/E12840_01/wls/docs103/notes/new.html

10.3.1

What's New in Oracle WebLogic Server for 11g Release 1 (10.3.1) at:

http://download.oracle.com/docs/cd/E12839_01/web.1111/e13852/toc.htm

10.3.2

What's New in Oracle WebLogic Server for 11g Release 1 (10.3.2) at:

http://download.oracle.com/docs/cd/E15523_01/web.1111/e13852/toc.htm

10.3.3

What's New in Oracle WebLogic Server for 11g Release 1 (10.3.3) at:

http://download.oracle.com/docs/cd/E14571_01/web.1111/e13852/toc.htm

10.3.4

What's New in Oracle WebLogic Server for 11g Release 1 (10.3.4) at:

http://download.oracle.com/docs/cd/E17904_01/web.1111/e13852/toc.htm

10.3.5

What's New in Oracle WebLogic Server for 11g Release 1 (10.3.5) at:

http://download.oracle.com/docs/cd/E21764_01/web.1111/e13852/toc.htm

10.3.6

What's New in Oracle WebLogic Server for 11g Release 1 (10.3.6)

For additional information about upgrading your application infrastructure and the scripting tools that have been deprecated, see Step 1: Upgrade Your Application Infrastructure.

Deployment Descriptor Validation and Conversion

This section describes changes in the use of deployment descriptors in a WebLogic Server environment, as of release 9.0:

Deployment descriptor validation is more strict as of the 9.0 release of the EJBGen and ejbc tools. For example, an error is returned if a cmr-field is defined in @ejbgen:relation, but there are no methods tagged with @ejbgen:cmr-field in the Bean class.

Note:

Oracle recommends you should use appc instead of ejbc. For more information, see "appc Reference" in Programming WebLogic Enterprise JavaBeans for Oracle WebLogic Server.

In pre-9.0 versions of WebLogic Server, applications that define multiple modules, as illustrated in the following excerpt from a configuration file, are deployed successfully regardless of whether a META-INF\application.xml deployment descriptor is defined as part of the application:

<Application Deployed="true" Name="SessionBeanLifeCycleBean"
Path="C:\bea\weblogic70\tools\deployment\ejb" TwoPhase="false">
            <EJBComponent Name="CMFinderTestBean" Targets="myserver" URI="CMFinderTestBean.jar"/>
            <EJBComponent Name="SessionBeanLifeCycleBean" Targets="myserver"
URI="SessionBeanLifeCycleBean.jar"/>
</Application>

As of 9.0, the META-INF\application.xml deployment descriptor is required if a deployed application defines multiple modules. If this type of deployment descriptor is not provided, the upgrade fails with an error similar to the following:

[J2EE Deployment SPI:260089]Unable to determine type of application at path 'C:\bea\weblogic70\tools\deployment\ejb' and upgrade will not succeed.

When upgrading a domain, make sure that the deployed applications adhere to the proper Java EE application format. For example, if required by the application, make sure that the applications define the META-INF\application.xml or META-INF\weblogic-application.xml deployment descriptors.

For more information about the deployment descriptors, see "Enterprise Application Deployment Descriptor Elements" in Developing Applications for Oracle WebLogic Server.

So that your applications can take advantage of the features in the current Java EE specification and release of WebLogic Server, Oracle recommends that you upgrade deployment descriptors when you upgrade applications to a new release of WebLogic Server. For more information, see "Upgrading Deployment Descriptors From Previous Releases of J2EE and WebLogic Server" in Developing Applications for Oracle WebLogic Server.

Deprecated Startup and Shutdown Classes

As of 9.0, application-scoped startup and shutdown classes were deprecated in WebLogic Server, in favor of applications that respond to application lifecycle events. Oracle recommends that you update your application environment to use the lifecycle events in place of application-scoped and domain-level startup and shutdown classes. For more information, see "Programming Application Life Cycle Events" in Developing Applications for Oracle WebLogic Server.

Administration Console

The following sections describe changes to the Administration Console:

Console Configuration Features

Administration Console Extension Architecture

Console Configuration Features

WebLogic Server 10.3 introduced new options that were added for configuring Console behavior, including the ability to do the following:

Lock a domain configuration so you can make changes to the configuration while preventing other accounts from making changes during your edit session

Specify whether to deploy internal applications such as the Administration Console, UDDI, and the UDDI Explorer on demand (upon first access) instead of during server startup

Locate any WebLogic Server Configuration MBean that contains the string specified in its name, using a new search feature added to the banner toolbar region

Use additional capabilities for automatically migrating failed servers and services from one server to another

Deploy and control Service Component Architecture (SCA) deployments

Inspect Spring applications

For more information, see "What's New in WebLogic Server" in the WebLogic Server 10.3 Release Notes.

Administration Console Extension Architecture

In WebLogic Server version 9.0, the Administration Console was built on the WebLogic Portal Framework, which makes it more open and more readily extensible. The architecture necessitated new procedures for extending the Administration Console. WebLogic Server console extensions built for releases of WebLogic Server before 9.0 do not function with the new console infrastructure.

The following features were added in WebLogic Server 10.3.2:

A sample Look and Feel is provided, which you can modify to create a custom Look and Feel for the WebLogic Server Administration Console.

Online help can be created and associated with console extensions.

For more information about extending the WebLogic Server Administration Console, see Extending the Administration Console for Oracle WebLogic Server.

Important Console-Extension Information for Version 9.2

Version 9.2 of WebLogic Server introduced the following changes to console extensions:

Before this release, Administration Console extensions could import a set of third-party JSP tag libraries by specifying a path name to the tag library file. For example,

<%@ taglib uri="/WEB-INF/beehive-netui-tags-template.tld" prefix="beehive-template" %>

As of 10.0, Administration Console extensions that use these third-party JSP tag libraries from the WebLogic Server installation must use pre-defined, absolute URIs to specify the tag libraries. For example:

<%@ taglib uri="http://beehive.apache.org/netui/tags-template-1.0" prefix="beehive-template" %>

The Administration Console's web.xml file maps these URIs to tag libraries within the WebLogic Server installation. This mapping facility enables Oracle to reorganize its installation directory without requiring you to change your JSPs.

Any Administration Console extensions that use the old path name syntax to import Apache Struts, Apache Beehive, or the JSTL tag libraries must update all path names to the new URIs.

The URI for the WebLogic Server Console Extension tag library (console-html.tld) remains unchanged: /WEB-INF/console-html.tld.

For more information, see "JSP Templates and Tag Libraries" in Extending the Administration Console for Oracle WebLogic Server.

By convention, portal include files (.pinc) files are now called portal book files (.book).

WebLogic Portal Skeleton URI References Should be Fully Qualified

WebLogic Portal requires that any explicit Skeleton URI references be fully qualified relative to the webapp. However, the documentation and some console extension examples have sometimes used relative references to these skeletons. Consider the following incorrect example:

<netuix:singleLevelMenu markupType="Menu" markupName="singleLevelMenu" skeletonUri="singlelevelmenu_children2.jsp"/>

This example should have been correctly specified as:

<netuix:singleLevelMenu markupType="Menu" markupName="singleLevelMenu" skeletonUri="/framework/skeletons/default/singlelevelmenu_children2.jsp"/>

For this release, relative skeleton URI references continue to work. However, any console extensions that you have written should be updated to use fully qualified skeleton URIs, because these relative references may no longer function correctly in a future release.

Resource Adapters

Table B-4 lists the configuration settings for resource adapters that are deprecated or no longer supported. For more information about new features and changes, see "What's New in WebLogic Server".

Table B-4 Deprecated or Unsupported Resource Adapter Configuration Settings

This element ...
As of WebLogic Server 9.0 ...

Link-Ref Mechanism

This element has been deprecated and replaced by the new Java EE libraries feature. For more information about Java EE libraries, see "Creating Shared J2EE Libraries and Optional Packages" in Developing Applications for Oracle WebLogic Server.

The Link-Ref mechanism is still supported in this release for resource adapters developed under the J2CA 1.0 Specification. For more information about using the Link-Ref mechanism with 1.0 resource adapters, see "(Deprecated) Configuring the Link-Ref Mechanism" in "Configuring the weblogic-ra.xml File" in Programming Resource Adapters for Oracle WebLogic Server.

<shrink-period-minutes>

This element has been deprecated and replaced by <shrink-frequency-seconds>, which you can use to specify the shrink period in increments of seconds, instead of minutes.

The <shrink-frequency-seconds> element overrides the <shrink-period-minutes> element if both are set.

<connection-maxidle-time>

This element has been deprecated and is replaced by <inactive-connection-timeout-seconds>, which you can use to specify the connection timeout in increments of seconds.

The <inactive-connection-timeout-seconds> element overrides the <connection-maxidle-time> element if both are set.

<security-principal-map>

This element is no longer supported; the security principal map is configured using the Administration Console.

You should remove the <security-principal-map> definition from the weblogic-ra.xml file. Otherwise, deployment of the resource adapter fails.

<connection-cleanup-frequency>

This element is no longer supported and is ignored during deployment.

<connection-duration-time>

This element is no longer supported and is ignored during deployment.

WLEC

WLEC was deprecated in WebLogic Server 8.1. WLEC users should move applications to the WebLogic Tuxedo Connector, as described in Tuxedo Connector Migration Guide for WLEC to Oracle WebLogic Server.

SNMP MIB Refresh Interval and Server Status Check Interval No Longer Used

The "SNMPAgentMBean" MBean "MibDataRefreshInterval" and "ServerStatusCheckIntervalFactor" attributes were deprecated in WebLogic Server 10.0 and are ignored.

Backward Compatibility Flags

The configuration flags in Table B-5 are available to support backward compatibility when you upgrade a domain. By default, these flags are set to support backward compatibility, unless you disable them by selecting the Do not set backward compatibility flags option during an upgrade, as described in Upgrading a Domain in Graphical Mode.

Table B-5 Backward Compatibility Flags

Category
Backward Compatibility Flag
For more information, see ...

Security

EnforceStrictURLPattern—Specifies whether the server should enforce strict adherence of URL patterns to the Servlet 2.4 specification. During an upgrade, this flag is set to false for backward compatibility.

WebAppFilesCaseInsensitive—Specifies whether the URL-pattern matching behavior is case-insensitive for security constraints, servlets, filters, virtual hosts, and so on, in the Webapp container and external security policies. During an upgrade, this flag is set to os, which sets URL-pattern matching as case-sensitive on all platforms except Windows, for compatibility with pre-9.0 releases. As of WebLogic Server 9.0, URL-pattern matching is strictly enforced across operating systems

"SecurityConfigurationMBean"

Web Application

backward-compatible—Specifies which JSP version is supported. Depending on the version of the Web application (version 2.4 or 2.5) and the setting of the backward-compatible element, Weblogic Server 10.3.6 supports JSP 2.1 or JSP 2.0.

backward-compatible is located within the "jsp-descriptor" element, as described in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.

AllowAllRoles—Specifies that a wildcard (*) character can be used to set the role name to enable all users/roles in the realm to have access to the resource collection. As of WebLogic Server 9.0, if you specify the wildcard (*) character as the role name, all users/roles in the Web application have access to the resource collection.

FilterDispatchedRequestsEnabled—Specifies whether to apply filters to dispatched requests. As of WebLogic Server 9.0, the new Dispatcher element makes this behavior explicit.

JSPCompilerBackwardsCompatible—Specifies whether to allow JSPs that do not comply with the JSP 2.0 specification.

ReloginEnabled—Specifies whether to allow users multiple attempts to log in to a Web page if the original credentials were not supported. As of WebLogic Server 9.0, the FORM/BASIC authentication behavior has been modified to return the 403 (FORBIDDEN) Web page.

RtexprvalueJspParamName—Specifies whether to allow run-time expression values for the JSP <param name> tag. As of WebLogic Server 9.0, the JSP Compiler no longer allows run-time expression values.

"WebAppContainerMBean"

Deprecated and Removed APIs

Information about deprecated functionality for WebLogic Server can be found on My Oracle Support at https://support.oracle.com/. Enter the following document ID in the Search Knowledge Base field:

888028.1

C WebLogic Domain Directory Structure Enhancements

As of 9.0, WebLogic Server offers the following enhancements to the structure of the WebLogic domain directory:

To improve configuration management and promote XML file validation, WebLogic Server supports the specification of domain configuration data in multiple files, including config.xml, in the new domain_name/config directory. (Here, domain_name specifies the domain directory.) In previous releases, the config.xml file was the repository for all configuration information. Now, new subdirectories of config maintain configuration modules for diagnostic, JDBC, JMS, and Node Manager subsystems. Each configuration file adheres to an XML Schema definition.

Startup and shutdown scripts are maintained in the domain_name/bin directory. In previous releases, they were stored in the root directory of the domain.

In addition to the structural enhancements to the domain directory, WebLogic Server supports utilities for managing changes to server configuration. These tools enable you to implement a secure, predictable means for distributing configuration changes in a domain. For more information, see "Managing Configuration Changes" in Understanding Domain Configuration for Oracle WebLogic Server.

For more details about the WebLogic domain directory structure, see "Domain Configuration Files" in Understanding Domain Configuration for Oracle WebLogic Server.

Figure C-1 compares the domain directory structures introduced in WebLogic Server 10.0 with WebLogic Server 8.1.

Figure C-1 WebLogic Server 10.3.6 and WebLogic Server 8.1 Directory Structures

The following sections describe the domain directory structures for WebLogic Server 8.1.

WebLogic Server 8.1 Domain Directory Structure

In WebLogic Server 8.1 environments, the domain directory structure created by the Configuration Wizard contains:

A domain root directory with the same name as the domain, such as mydomain or petstore. This directory contains the following:

config.xml file for the domain

Scripts used to start server instances and establish the environment

Subdirectory for storing applications for the domain, typically named applications.

When you start a server instance in a domain for the first time, WebLogic Server creates the following subdirectories in the domain directory:

Files containing security information

logs directory for storing domain-level logs

For each server running in the domain, a directory for storing server logs and HTTP access logs

For more details about the WebLogic Server 8.1 domain directory structure, see "Overview of WebLogic Server Domains" in Configuring and Managing WebLogic Server, available at http://download.oracle.com/docs/cd/E13222_01/wls/docs81/adminguide/overview_domain.html. For a summary of the directory structure contents for the default configuration templates, see "Template Reference" in Creating and Configuring WebLogic Domains Using the Configuration Wizard, available at http://download.oracle.com/docs/cd/E13196_01/platform/docs81/confgwiz/tempref.html.

D Upgrade Wizard Command-Line Reference

The command to invoke the WebLogic Upgrade Wizard has the following syntax:

java weblogic.Upgrade [-help | -h | -? | -usage] [-type type] [-mode mode] [-responses xmlfile] [-out file]

Table D-1 describes each of the arguments that may be specified in this command.

Table D-1 Command-Line Arguments for the WebLogic Upgrade Wizard

Argument
Description

-help | -h | -? | -usage

Displays help information.

-type type

Specifies one of the following types of upgrade: domain, nodemanager, or securityproviders. The default value is domain.

Note: The -type domain option can only be used to upgrade a WebLogic domain in silent mode. For more information, see Upgrading a Domain in Silent Mode.

-mode mode

Specifies one of the following modes of upgrade: gui or silent. The default value is gui.

-responses xmlfile

Specifies the location of the XML file that contains the upgrade requirements to be used during a silent upgrade. This argument is valid only when -mode is set to silent. For more information about the format of the responses file, see Appendix E, "Silent Upgrade XML Script Reference."

-out file

Specifies the file in which standard output and errors are stored. By default, log output is sent to stdout.

Examples

The following command upgrades a domain in interactive mode:

java weblogic.Upgrade

The following command upgrades a domain in silent mode:

java weblogic.Upgrade -mode silent -type domain

The script content on this page is for navigation purposes only and does not alter the content in any way.

E Silent Upgrade XML Script Reference

Before using the WebLogic Upgrade Wizard in silent mode, you have the option of creating an XML script that defines your upgrade requirements, and passing that script to the wizard on the command line.

When run in silent mode, the Upgrade Wizard searches the domain's root directory for an XML script with a name that indicates the type of upgrade task to be performed. If the wizard does not locate an XML script, it uses default system values.

This appendix provides the following sample XML upgrade scripts:

Security Provider Upgrade Script

Node Manager Upgrade Script

Domain Upgrade Script

Depending on the particular configuration of the environment you are upgrading, you can modify specific values in these scripts, as explained in this appendix, and have the WebLogic Upgrade Wizard use them instead. This appendix identifies those values and their defaults, and explains how they can be modified.

Note:

Only WebLogic domains can be upgraded using silent mode.

About Modifying the Sample XML Scripts

To create an XML script for a silent mode upgrade, modify one of the sample scripts provided in this appendix. Note the following:

The XML definition (<?xml version="1.0" encoding="UTF-8"?>) must be at the very beginning of the XML script. No spaces or line breaks are allowed before the XML definition.

You must follow XML guidelines for characters when modifying values. That is, you cannot use characters reserved for use in XML, such as <, >, [, and ].

Save the sample script as an XML file in the root directory of the domain to upgrade. You must use the same name for the script as identified in this appendix.

Security Provider Upgrade Script

To upgrade the security providers in a domain, the WebLogic Upgrade Wizard looks for an XML script named weblogic-upgrade-securityproviders-responses.xml, which is displayed in Example E-1. The values that may be modified are shown in bold.

Example E-1 Sample Silent-Mode XML Script for Upgrading Security Providers

<?xml version="1.0" encoding="UTF-8"?>

<plugin-silent-responses>
</plugin-silent-responses>

<!--
<plugin-silent-responses>
  <group name="SecurityProviderUpgradeGroup">
    <plugin name="SecurityProviderUpgradeStepOne">
      <input-adapter name="IA">
        <bind-property name="selectedFileNames">
          <value>__INPUT_DIRECTORY__</value>
        </bind-property>
      </input-adapter>
    </plugin>
    <plugin name="SecurityProviderUpgradeStepTwo">
      <input-adapter name="IA">
        <bind-property name="selectedFileNames">
          <value>__OUTPUT_DIRECTORY__</value>
        </bind-property>
      </input-adapter>
    </plugin>
  </group>
</plugin-silent-responses>

Table E-1 identifies the keywords contained in this script, the values you can specify for those keywords, and the default values that are used by the WebLogic Upgrade Wizard if you do not modify them.

Table E-1 Silent-Mode XML Script Values for Upgrading Security Providers

For this keyword...
Set the value to the...
This keyword defaults to the...

INPUT_DIRECTORY

Path of the directory that contains the security provider JARs to be upgraded. For example:

d:/bea/weblogic81/server/lib/mbeantypes

By default, security providers are located in WL_HOME\server\lib\mbeantypes, where WL_HOME specifies the root directory of the pre-9.0 installation.

Path of directory from which the Upgrade Wizard is run, such as:

c:\bea\wlserver_10.3\server\lib\mbeantypes

OUTPUT_DIRECTORY

Path of the directory in which you want to save the new security provider JAR files. For example:

d:/bea/wlserver_10.3/server/lib/mbeantypes

WL_HOME\server\lib\mbeantypes, where WL_HOME specifies the root directory of the WebLogic Server 10.x installation.

Node Manager Upgrade Script

To upgrade the Node Manager from an existing domain, the WebLogic Upgrade Wizard looks for an XML script named weblogic-upgrade-nodemanager-responses.xml, which is displayed in Example E-2. The values that may be modified are shown in bold.

Example E-2 Sample Silent-Mode XML Script for Upgrading a Node Manager

<?xml version="1.0" encoding="UTF-8"?>

<plugin-silent-responses>
</plugin-silent-responses>

<!--
<plugin-silent-responses>
  <group name="NodeManagerPlugInGroup">
    <plugin name="NodeManagerPlugIn">
      <input-adapter name="IA">
        <bind-property name="selectedFileNames">
          <value>__NODE_MANAGER_HOME__</value>
        </bind-property>
      </input-adapter>
    </plugin>
  </group>
</plugin-silent-responses>

Table E-2 identifies the keyword contained in this script, the value you can specify for that keyword, and the default value used by the WebLogic Upgrade Wizard if you do not modify it.

Table E-2 Silent-Mode XML Script Value for Upgrading the Node Manager

For this keyword...
Set the value to the...
This keyword defaults to the...

NODE_MANAGER_HOME

Path of the directory of Node Manager to be upgraded by navigating the local directory hierarchy.

By default, the Node Manager home directory is located in WL_HOME\common\nodemanager, where WL_HOME specifies the root directory of the pre-9.0 installation.

Directory from which the Upgrade Wizard is run. For example, c:\bea\wlserver_10.3\common\nodemanager.

Domain Upgrade Script

To upgrade an existing domain, the WebLogic Upgrade Wizard looks for an XML script named weblogic-upgrade-domain-responses.xml, which is displayed in Example E-3. The values that may be modified are shown in bold.

Note:

Specifying the name of the domain Administration Server, as described in Table E-3 for the keyword ADMIN_SERVER_NAME, is required because there is no default value.

Example E-3 Sample Silent-Mode XML Script for Upgrading a Domain

<?xml version="1.0" encoding="UTF-8"?>

<plugin-silent-responses>
</plugin-silent-responses>

<!-- SAMPLE BELOW -->
<!--
<plugin-silent-responses>
  <group name="DomainSelectionGroup">
    <plugin name="SelectWebLogicVersionPlugIn">
      <input-adapter name="ChoiceIA">
        <bind-property name="selectedChoiceIds">
          <value>__WEBLOGIC_VERSION__</value>
        </bind-property>
      </input-adapter>
    </plugin>
    <plugin name="DomainDirectorySelectionPlugIn">
      <input-adapter name="IA">
        <bind-property name="selectedFile">
          <value>__DOMAIN_DIR__</value>
        </bind-property>
      </input-adapter>
    </plugin>
  </group>
  <group name="PostDirSelectionGroup">
    <plugin name="AdminServerSelectionPlugIn">
      <input-adapter name="IA">
        <bind-property name="selectedChoiceIds">
          <value>__ADMIN_SERVER_NAME__</value>
        </bind-property>
      </input-adapter>
    </plugin>
    <plugin name="NodeManagerCredentialsPlugIn">
      <input-adapter name="UsernameIA">
        <bind-property name="value">
          <value>__NODE_MANAGER_USERNAME__</value>
        </bind-property>
      </input-adapter>
      <input-adapter name="PasswordIA">
        <bind-property name="value">
          <value>__NODE_MANAGER_PASSWORD__</value>
        </bind-property>
      </input-adapter>
      <input-adapter name="PasswordConfirmIA">
        <bind-property name="value">
          <value>__NODE_MANAGER_PASSWORD__</value>
        </bind-property>
      </input-adapter>
    </plugin>
    <plugin name="OptionalGroupsSelectionPlugIn">
      <input-adapter name="IA">
        <bind-property name="selectedChoiceIds">
          <value>__OPTIONAL_ACTION_1__</value>
          <value> . . . </value>
        </bind-property>
      </input-adapter>
    </plugin>
  </group>
  <group name="PostDirSelectionPost81Group">
    <plugin name="AdminServerSelectionPlugIn">
      <input-adapter name="IA">
        <bind-property name="selectedChoiceIds">
          <value>__ADMIN_SERVER_NAME__</value>
        </bind-property>
      </input-adapter>
    </plugin>
    <plugin name="OptionalGroupsSelectionPlugIn">
      <input-adapter name="IA">
        <bind-property name="selectedChoiceIds">
          <value>__OPTIONAL_ACTION_1__</value>
          <value> . . . </value>
        </bind-property>
      </input-adapter>
    </plugin>
  </group>
  <group name="DomainBackupGroup">
    <plugin name="DomainDirectoryBackupPlugIn">
      <input-adapter name="FileSelectionIA">
        <bind-property name="selectedFileNames">
          <value>__BACKUP_DIR__</value>
        </bind-property>
      </input-adapter>
      <input-adapter name="TextIA">
        <bind-property name="value">
          <value>___BACKUP_FILE_NAME__</value>
        </bind-property>
      </input-adapter>
    </plugin>
  </group>
</plugin-silent-responses>

-->

Table E-3 identifies the keywords contained in this script, the values you can specify for the keywords, and the default values used by the WebLogic Upgrade Wizard if you do not modify them.

Table E-3 Silent-Mode XML Script Value for Upgrading a Domain

For this keyword...
Set the value to...
The keyword defaults to...

WEBLOGIC_VERSION

The version of WebLogic Server contained in the domain being upgradedFoot 1 .

The version of WebLogic Server identified in the configuration file (config.xml) of the domain being upgraded. For example, 8.1.4.0.

If the software version number is not specified in the domain configuration file, the wizard displays the version number as 8.1.0.0, by default. In this case, there is no impact if the default value does not match the actual version number of the pre-9.0 domain.

ADMIN_SERVER_NAME

Name of the domain's Administration Server instance.

Note: Assigning a value for this keyword is required because there is no default. If you do not provide the Administration Server name, this silent upgrade script generates an exception and terminates.

No default value is assigned.

DOMAIN_DIR

The path of the directory that contains the WebLogic domain to be upgraded.

The directory from which the Upgrade Wizard is run. For example, c:\bea\user_projects\domains\mydomain.

NODE_MANAGER_USERNAME

The username for Node Manager.

weblogic

NODE_MANAGER_PASSWORD

The password for Node Manager.

weblogic

NODE_MANAGER_PASSWORD

The confirmation password for Node Manager.

weblogic

OPTIONAL_ACTION_1

One or more of the following options:

DOMAIN_DIRECTORY_BACKUP_SELECTED_VALUE

If this option is specified, the wizard backs up the original domain directory and stores it in a zip file.

DOMAIN_DIRECTORY_BACKUP_LOG_FILES_INCLUDED_SELECTED_VALUE

If this option is specified, log files are included in the backup zip file. The number and size of log files can be large, so you may want to exclude them from the backup file by disabling this option. By default, log files are included in the backup file.

SKIP_BACKWARDS_COMPATIBILITY_FLAGS_SELECTED_VALUE

Some behavior supported in pre-9.0 releases of WebLogic Server has been changed as of 9.0 to comply with J2EE 1.4. By default, the wizard sets flags to enable the previous behavior in the new domain. If you specify this option, these flags for backward compatibility are not set.

Note that OPTIONAL_ACTION_1 may be specified so that one of multiple options is used. For example:

DOMAIN_DIRECTORY_BACKUP_SELECTED_VALUE OR
DOMAIN_DIRECTORY_BACKUP_LOG_FILES_INCLUDED_SELECTED_VALUE OR
SKIP_BACKWARDS_COMPATIBILITY_FLAGS_SELECTED_VALUE

DOMAIN_DIRECTORY_
BACKUP_SELECTED_VALUE, DOMAIN_DIRECTORY_
BACKUP_LOG_FILES_INCLUDED_SELECTED_VALUE

BACKUP_DIR

Path of the directory in which you want to save the backup zip file.

Directory from which the Upgrade Wizard is run. For example, c:\bea\user_projects\domains\mydomain.

BACKUP_FILE_NAME

Name of the backup zip file.

weblogic-domain-backup-mydomain.zip

Footnote 1 You can specify multiple versions of WebLogic Server, as in the following example: 6.1 OR 7.0 OR 8.1 OR "9.0 or higher"

F Upgrading a Domain at Administration Server Startup (Implicit Mode)

The implicit mode of upgrade enables you to upgrade a WebLogic domain automatically at server startup. This mode should be used only in a development environment, and it is valid only for the computer on which the Administration Server resides. The implicit mode of upgrade is not recommended for use in a production environment.

Note:

The implicit mode of upgrade can only be used to upgrade a WebLogic domain.

Before proceeding, make sure that you have performed the prerequisite steps described in Prepare to Upgrade.

To start the WebLogic Upgrade Wizard in implicit mode:

Verify that the WebLogic domain is not running.

Open an MS-DOS command prompt window (on Windows) or a command shell (on UNIX) and set up the environment as described in Step 6: Set Up the Environment.

Update the startup scripts in the domain to reference the WebLogic Server 10.3.6 installation.

For example, make sure WL_HOME is set to the WebLogic Server 10.3.6 installation. For example: c:\Oracle\Middleware\wlserver_10.3.

By default, the WebLogic Upgrade Wizard prompts you for confirmation before starting the upgrade process. You can disable the prompt by specifying, in the startup script, the following command argument for starting the server:

-Dweblogic.ForceImplicitUpgradeIfNeeded=true

Start up the Administration Server in your domain.

Respond to the upgrade confirmation prompt, if necessary.

The WebLogic Upgrade Wizard checks whether the domain directory was generated using a valid version of WebLogic Server (8.1 or 9.0), and, if the result is true, it automatically upgrades the domain. This process occurs only once: the first time you start the Administration Server.

Note:

Implicit upgrade is not available for WebLogic Server version 9.x or 10.x to 10.3.6 because upgrade is optional between these two versions. You can run a 9.x or 10.x domain under 10.3.6 without modifications.

G WebLogic Server Rolling Upgrade

Rolling Upgrade is the process of upgrading a running WebLogic Server cluster with a patch, maintenance pack, or minor release without shutting down the entire cluster or domain. During the rolling upgrade of a cluster, each server in the cluster is individually upgraded and restarted while the other servers in the cluster continue to host your application.

Before the WebLogic Server 9.2 release, to upgrade a cluster, you had to either shut down the entire domain, or install the upgraded server version on a parallel domain on additional hardware and use a load balancer to transfer load from the old domain to the new domain. The rolling upgrade process minimizes downtime and allows you to install a patch, maintenance pack, or minor release while the domain is still running.

The following topics are included:

Scope of the Rolling Upgrade Process

Before you Begin

Rolling Upgrade Process

Rolling Uninstall

Limitations

Scope of the Rolling Upgrade Process

Support for rolling upgrade was available starting with WebLogic Server 9.2. The scope of rolling upgrade support encompasses installation of patches and maintenance packs as they are made available for WebLogic Server 10.x.

Note:

Rolling upgrade should be used only when upgrading WebLogic Server to the next sequential version within a major product release. For example, if you have WebLogic Server 10.3.4 and you want to upgrade to version 10.3.6, you first must upgrade to version 10.3.5, and then again from 10.3.5 to 10.3.6. Do not skip WebLogic Server versions with rolling upgrade; for example, do not use rolling upgrade to move from version 10.0 to 10.3.6 in a single upgrade operation. You cannot use rolling upgrade to upgrade from a release in one major product version to a release of a subsequent major version; for example, you cannot use rolling upgrade for upgrading from WebLogic Server 9.0 to 10.0.

Rolling upgrade is most applicable to a cluster of WebLogic Server instances, however, you can also install updates to a domain of Managed Servers that are not in a cluster. This documentation focuses on installing upgrades in a cluster.

You can also uninstall a patch, maintenance pack, or minor release in a rolling fashion.

You can still upgrade to the latest patch using other strategies including bringing applications down in order to perform WebLogic Server upgrades, and restarting applications after WebLogic Server upgrades are complete. The rolling upgrade process provides you with an option of upgrading a running WebLogic Server cluster without shutting down the entire cluster or domain.

Before you Begin

Before you begin the upgrade process, make sure that you take any necessary precautions such as:

Back up your applications, database schema, other application data, and domains.

If required, obtain latest third party plug-ins or components that are compatible with required non-Oracle components. For example, Apache Web Server libraries.

Rolling Upgrade Process

The rolling upgrade process includes stopping the Administration Server, installing the upgrade, restarting the Administration Server, and then doing the same for each Managed Server in the cluster. See the following sections for more information:

Quiescing and Stopping Servers

Installing a Patch, Maintenance Pack, or Minor Release

Restarting Servers

Quiescing and Stopping Servers

Before you install the WebLogic Server update on a server, you must first shut down the server. Before server shutdown, depending on your environment, it might be necessary for you to:

Stop load balancers or Web Servers from sending requests or traffic to the server.

Complete any pending processes.

Gracefully shut down the server.

Shutdown Servers in a Cluster

You can shut down a Managed Server from the command line, in a WLST script, or from the Administration Console.

From the command line, you can gracefully shut down the server using the Graceful Shutdown command. This command waits for all the in-process work to be completed before shutting down the server or cluster.

For information about using the Graceful Shutdown command, see "shutdown" in WebLogic Scripting Tool Command Reference. For information about how to shut down the Managed Server from the Console, see "Shutdown servers in a cluster" in Oracle WebLogic Server Administration Console Help.

Notes:

Observe the following:

When using the WLST shutdown() command, make sure that you are connected to the Managed Server instance you want to stop. For information about using WLST to shut down servers, see "Managing the Server Life Cycle" in Oracle WebLogic Scripting Tool.

Make sure that you stop all server instances that use the same installed WebLogic Server files.

Installing a Patch, Maintenance Pack, or Minor Release

After you stop the running server on your computer, install the maintenance upgrade. For information obtaining the maintenance upgrade, see the appropriate topic listed in the following table:

For information about . . .
. . . see the following document

Downloading and installing patches
"Downloading and Applying Patches" in Oracle Smart Update Installing Patches and Maintenance Packs

Downloading an installer for a minor release
Either of the following in Oracle WebLogic Server Installation Guide:

"Downloading the Installer from Oracle E-Delivery"

"Downloading the Installer From Oracle Technology Network"

Downloading an upgrade installer
"Downloading an Upgrade Installer From My Oracle Support" in Oracle WebLogic Server Installation Guide

There are multiple methods for installing the maintenance upgrade. The following sections provide information about each of these options.

Installing Patches Using Smart Update

You can use the Smart Update feature to periodically check for available patches. When you start Smart Update, it checks the version numbers of the products installed (associated with the current Middleware Home directory), and then connects to My Oracle Support to check for available patches. For more information about using Smart Update, see Oracle Smart Update Installing Patches and Maintenance Packs.

Using the Command Line Interface

In most cases, the maintenance upgrade can be distributed and installed using a script. You can create a mechanism for replicating a specific maintenance level of an Oracle product that is installed on multiple machines. This capability is especially valuable in production environments, in which the distribution of software updates to machines must be implemented in a controlled, reliable, and reproducible manner.

You can use the Smart Update bsu command, which you can use to apply patches, interactively or by using a script, that have been downloaded into a patch download directory. For more information, see "Using the Command-Line Interface" in Oracle Smart Update Installing Patches and Maintenance Packs.

Silent Installation

Silent-mode installation is a way of setting installation configurations only once and then using those configurations to duplicate the installation on many machines. During installation in silent mode, the installation program reads the settings for your configuration from an XML file that you create before beginning the installation. The installation program does not display any configuration options during the installation process. Silent installation applies only to a minor version installation. For more information, see "Running the Installation Program in Silent Mode" in the Oracle WebLogic Server Installation Guide.

Additional Information

For complete information about installing Oracle WebLogic products, see Oracle WebLogic Server Installation Guide.

For sample scenarios and best practices during upgrade, see "Best Practices for Distributing Maintenance Updates" in Oracle Smart Update Installing Patches and Maintenance Packs.

Restarting Servers

After you install the maintenance upgrade, it might be necessary to modify start scripts before you restart your server. For more information, see "Activating Applied Patches in Your Installations and Applications" in Oracle Smart Update Installing Patches and Maintenance Packs. In addition, other post install tasks that you must do vary depending on your environment and the type of maintenance that you installed.

For an overview of methods for starting and stopping server instances, see "Starting and Stopping Servers" in Managing Server Startup and Shutdown for Oracle WebLogic Server.

If required, it might be necessary for you to reconfigure your Web server or load balancer after the server is started so that requests are again sent to the server.

Steps in Rolling Upgrade Process for a Patch and Minor Release

A patch is a file containing a fix or a small number of fixes that you can install using Smart Update. A patch is typically created to fix a software defect. A patch can be installed using Smart Update (recommended) or by referencing the patch at the beginning of the classpath.

A maintenance pack is a group of fixes combined into one file. Maintenance packs can be installed by downloading an installer from My Oracle Support. Both maintenance packs and patches are applied to an existing installation.

Note:

You cannot use Smart Update to download and install the WebLogic 10.3.6 release over an existing WebLogic Server 10.3.x release. Instead, you must download the appropriate WebLogic Server Upgrade installer from My Oracle Support.

You can still use Smart Update to download and install a patch set or maintenance pack for any supported release before WebLogic Server 10.3.4. You can also still use Smart Update to download individual patches for any supported release, including patches for WebLogic Server 10.3.6.

While the WebLogic domain is running, follow these steps:

Shutdown the Administration Server. For more information, see Quiescing and Stopping Servers.

On the computer that hosts the Administration Server, install the WebLogic Server patch. For more information, see Installing a Patch, Maintenance Pack, or Minor Release.

Restart the Administration Server. For more information, see Restarting Servers.

For each Managed Server, you must do the following tasks in sequence:

Shut down the server as described in Quiescing and Stopping Servers.

Install the software update as described in Installing a Patch, Maintenance Pack, or Minor Release.

Restart the server as described in Restarting Servers.

Note:

You can also modify the start scripts using Smart Update to automate the restart process. For more information, see "Modifying a Start Script" in Oracle Smart Update Installing Patches and Maintenance Packs.

You have now completed the upgrade process.

Steps in Rolling Upgrade Process for Minor WebLogic Server Releases

A minor version is a new release that includes fixes and new features. A minor release is installed in a completely new directory. Existing domains from the same release family can be run using the new minor release. WebLogic Server 10.3.5 and WebLogic Server 10.3.6 are existing examples of minor versions of WebLogic Server 10.3.

While the WebLogic domain is running, follow these steps:

Shut down the Administration Server. For more information, see Quiescing and Stopping Servers.

On the computer that hosts the Administration Server, install the new version of WebLogic Server. For more information about installing Oracle products, see Oracle WebLogic Server Installation Guide.

Update your start scripts for the domain so that the new files are in your classpath.

Update your environment variables, such as JAVA_HOME, MW_HOME, BEA_HOME, and WLS_HOME, to point to the new version of WebLogic Server.

Restart the Administration Server. For more information, see Restarting Servers.

For each Managed Server, you must do the following tasks, in sequence:

Stop the server as described in Quiescing and Stopping Servers.

Install the software update as described in Installing a Patch, Maintenance Pack, or Minor Release.

Update your start scripts for the domain so that the new files are in your classpath.

Update your environment variables, such as JAVA_HOME, MW_HOME, BEA_HOME, and WLS_HOME, to point to the new version of WebLogic Server.

Restart the server as described in Restarting Servers.

Rolling Uninstall

You can uninstall a patch, maintenance pack, or minor release without shutting down the entire cluster or domain. The following sections provide more information.

Uninstalling a Patch or Maintenance Pack

At times you may want to uninstall a maintenance upgrade. You can use Smart Update to revert your system installation to an earlier version of the release. For more information, see "Uninstalling Maintenance Packs and Patches" in Oracle Smart Update Installing Patches and Maintenance Packs.

The procedure for uninstalling a patch or maintenance pack is in the opposite order of the rolling upgrade:

On each Managed Server, you must do the following tasks:

Stop the server as described in Quiescing and Stopping Servers.

Uninstall the patch or maintenance pack.

For more information, see "Uninstalling Maintenance Packs and Patches" in Oracle Smart Update Installing Patches and Maintenance Packs.

Restart the server as described in Restarting Servers.

After all Managed Servers have been downgraded, do the following tasks on the Administration Server:

Stop the server as described in Quiescing and Stopping Servers.

Uninstall the patch or maintenance pack.

Restart the server as described in Restarting Servers.

The applied patch or maintenance pack is now uninstalled.

Uninstalling a Minor Release

For information about uninstalling a minor release, see "Uninstalling the Software" in the Oracle WebLogic Server Installation Guide.

The procedure is in the opposite order of the rolling upgrade:

On each Managed Server, do the following tasks:

Stop the server as described in Quiescing and Stopping Servers.

Uninstall the patch or maintenance pack.

For more information, see "Uninstalling the Software" in Oracle WebLogic Server Installation Guide.

Updating the start scripts so that the previous version of WebLogic Server is in the classpath and all environment variables refer to the previous version of WebLogic Server.

Restart the server as described in Restarting Servers.

After all Managed Servers have been downgraded, do the same steps on the Administration Server:

Stop the server as described in Quiescing and Stopping Servers.

Uninstall the patch or maintenance pack.

Update the start scripts so that the previous version of WebLogic Server is in the classpath and all environment variables refer to the previous version of WebLogic Server.

Restart the server as described in Restarting Servers.

The new version of WebLogic Server is now uninstalled.

Limitations

Note the following limitations of rolling upgrade:

Rolling upgrade applies only to upgrading to the next sequential release within a major product version. For example, you can use rolling upgrade from 10.3.5 to 10.3.6, but not from 9.0 to 10.3.6.

When WebLogic Server is installed on a computer and multiple Managed Servers are run from this same installation, you must shut down all Managed Servers that use the same installation before you can upgrade.

During the upgrade process, it might be necessary to replace certain installed files. However, because the WebLogic Server instance uses these installed files while it is running, the files can be replaced during the upgrade process only after you shutdown the server instance. If multiple Managed Servers share the same installation of WebLogic Server, all instances that use the set of files must be shut down and upgraded at the same time. In support of rolling upgrade, Oracle recommends that each Managed Server have its own installation of WebLogic Server.

During the upgrade, you can use new features only after the entire domain has been upgraded.

You should not make configuration changes during the upgrade process until all the servers in the cluster have been upgraded. This is especially true for new configuration options. Servers silently ignore settings that they do not understand, and the local configuration file may not be updated properly. Also, using new configuration options may prohibit the capability of uninstalling a maintenance upgrade in a rolling fashion.

For a minor release, during the rolling upgrade, there must be two entirely separate installation directories. That is, the location of the old installation and the location of the new installation must be two different directories.

This graphic compares the domain directory structures introduced in WebLogic Server 10.0 with WebLogic Server 8.1. In WebLogic Server 10.3.5, the WebLogic domain directory has the following structure:

The top-level, or root, directory contains the domain name.

The following subdirectories exist immediately below the top-level directory. A plus sign (+) adjacent to a directory name indicates that it has additional subfolders, which are not shown in this figure.

autodeploy
bin
  nodemanager
  server_migration
  service_migration
config
  configCache
  deployments
  diagnostics
  jdbc
  jms
  lib
  nodemanager
  startup
console-ext
init-info
lib
security
servers
  examplesServer
    +cache
    +data
    +logs
    security
    +tmp
  WseeFileStore

By contrast, in WebLogic Server 8.1, the WebLogic domain has the following structure:

The top-level, or root, directory contains the domain name.

The following subdirectories exist immediately below the top-level directory. A plus sign (+) adjacent to a directory name indicates that it has additional subfolders, which are not shown in this figure.

applications
logs
rmfilestore

The following files are located in the top-level directory:

boot.properties
config.xml
DefaultAuthenticatorInit.ldift
DefaultAuthorizorInit.ldift
DefaultRoleMapperInit.ldift
fileRealm.properties
installService.cmd
pointbase.ini
SerializedSystemini.dat
setEnv.cmd
setEnv.sh
startManagedWebLogic.cmd
startManagedWebLogic.sh
startWebLogic.cmd
startWebLogic.sh
stopWebLogic.cmd
stopWebLogic.sh
uninstallService.cmd

This graphic shows the graphical user interface of the WebLogic Upgrade Wizard displayed when upgrading a domain. The following components of this window are displayed:

The title of the window is Oracle WebLogic Upgrade Wizard.

The subtitle is Welcome. The message below the subtitle is:

This wizard will upgrade a domain to WebLogic Server 10.3.5.0.

The main display area of the window contains the following text:

This wizard streamlines the upgrade of domains to WebLogic 10.3.
Upgrade of WebLogic Server 6.1 or higher domains is supported.  For
Portal, Integration, and Workshop domains, Version 8.1SP4 of later is
supported.

Prerequisites:
- Shut down the domain you want to upgrade.
- Backup the domain, including your domain directory, JMS
  database store tables, and the entire Portal database, if
  applicable. The wizard will also activate your domain directory
  contents before upgrade.
- JDBC drivers required for JMS must be on classpath.

What to expect:
- The wizard logs to standard output.  By default this is redirected
  to an audit file in user_projects/upgrade_logs under
  your Middleware Home.
- You will see a summary of key information at the end.

Three buttons are listed at the bottom: Exit, Previous, and Next. Only the Exit and Next buttons are active. The default button is Next.

This graphic shows an example WebLogic application environment. It depicts three clients invoking Managed Server instances that are configured in a cluster in a WebLogic domain. The client requests are received by a load balancer, which exists behind the enterprise firewall. The load balancer forwards each client request to a target Managed Server instance. No Managed Server instance is exposed or directly accessible by client applications that are outside the firewall; only the load balancer is exposed externally.

The cluster consists of four Managed Server instances. Two Managed Server instances are hosted on one physical machine, and two are hosted on a second machine. A third machine in the WebLogic domain hosts the Administration Server. Each machine in the WebLogic domain hosts an instance of the Node Manager.

The security realm in the WebLogic domain is configured with a custom security provider. This custom security provider is depicted with each machine instance to indicate that the provider can be used by each WebLogic Server instance in the domain.

The Managed Server instances share a common application directory, which exists on the machine hosting the Administration Server. The domain is configured with a connection to an RDBMS system, which is depicted as physically outside the WebLogic domain because the RDBMS system typically is shared with other enterprise resources.

This graphic describes the overall roadmap for upgrading your application environment as procedure consisting of the following steps:

If you have custom security providers, you should upgrade those providers on each machine in your application environment.

If you are using the Node Manager, you should upgrade the Node Manager on each machine in your application environment.

Upgrade the WebLogic domain on the machine hosting the Administration Server.

If you have Managed Server instances hosted on remote machines, you should upgrade the WebLogic domain on each machine that hosts those Managed Servers.

This graphic shows the initial window that is displayed when you launch the graphical user interface of the WebLogic Upgrade Wizard for security providers. The following components of this window are displayed:

The title of the window is Oracle WebLogic Upgrade Wizard.

The subtitle is Upgrade Old Security Providers. The message below the subtitle is, "Have directory containing Old Security Provider jars ready. (By default, it should be in previous-BEA-Home/server/lib/mbeantypes)

Three buttons are listed at the bottom: Exit, Previous, and Next. Only the Exit and Next buttons are active. The default button is Next.

This graphic shows the initial window that is displayed when you launch the graphical user interface of the WebLogic Upgrade Wizard for upgrading Node Manager. The following components of this window are displayed:

The title of the window is Oracle WebLogic Upgrade Wizard.

The subtitle is Node Manager Upgrade. The message below the subtitle is, "Please select your node manager home directory below".)

Three buttons are listed at the bottom: Exit, Previous, and Next. Only the Exit and Next buttons are active. The default button is Next.

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2010, Oracle and/or its affiliates. All rights reserved.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

Hazardous Applications Notice

This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.

Trademark Notice

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

Third-Party Content, Products, and Services Disclaimer

This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.