| products | dev2dev | support | askBEA
 Download Docs   Site Map   Glossary 

WebLogic Server 8.1 Upgrade Guide

 Previous Next Contents View as PDF  

Upgrading WebLogic Server 6.x to Version 8.1

Upgrading WebLogic Server 6.x to version 8.1, under the simplest circumstances, involves changing your WebLogic Server start command scripts and environment settings.

BEA Systems recommends copying your WebLogic Server 6.x domain directory to a new directory. If you do this, ensure that relative paths to external files remain accurate.

Upgrading may also require changes specific to the subsytem being upgraded.

The following sections contain information necessary to upgrade your system from WebLogic Server 6.x to WebLogic Server 8.1:

For instructions on how to upgrade the Pet Store application from WebLogic Server 6.1 to WebLogic Server 8.1 and how to upgrade the WebLogic 6.0 and 6.1 Examples Servers to WebLogic Server 8.1, see Upgrading Example Applications to WebLogic Server 8.1.

For information on upgrading to WebLogic Platform 8.1, see the Upgrading section of the WebLogic Server FAQs.

Note: Throughout this document "upgrade" refers to upgrading to a later version of WebLogic Server and "port" refers to moving your applications from an earlier version of WebLogic Server to a later version.


Upgrading Your WebLogic Server Configuration: Main Steps

Take the following steps to upgrade from WebLogic Server 6.x to WebLogic Server 8.1:

  1. Make a backup copy of your 6.x domain before you begin the upgrade procedure. After you start running your domain using WebLogic Server 8.1, you cannot convert it back to 6.1.
  2. Install WebLogic Server 8.1. See the the Installation Guide.

    Note: The installer will prevent you from installing the new version directly over the old version. You must select a new directory location.

  3. Modify your 6.x startup scripts to work with WebLogic Server 8.1. See Modifying Startup Scripts.
  4. Ensure that you have considered differences in the WebLogic Server 8.1 directory structure that may require you to make file location changes before startup. See Understanding the WebLogic Server 8.1 Directory Structure.
  5. Upgrade your applications to WebLogic Server 8.1. See Upgrading an Application from WebLogic Server 6.x to WebLogic Server 8.1.
  6. If necessary, perform other upgrade procedures as described in Additional Upgrade Procedures and Information.

To upgrade a cluster of servers, follow the above steps for each server and then follow the steps outlined in Setting Up WebLogic Clusters in Using WebLogic Server Clusters. In cases where you invoke an application by using RMI/T3 or RMI/IIOP, WebLogic Server 6.1 and 8.1 are interoperable. Within a domain, however, all servers must be of the same version.

For information on upgrading WebLogic Server license files, see Upgrading Licenses from WebLogic Server 6.x in the Installation Guide.


Modifying Startup Scripts

If you used WebLogic Server startup scripts with a previous version of the product, modify them to work with WebLogic Server 8.1.

Modify the startup scripts as described here. For another example of how to modify the startup scripts, see Upgrading WebLogic Server 6.x to Version 8.1.

Modify the startup scripts as described here.

  1. Modify bea.home property

    to point to your BEA home directory containing the license.bea file for WebLogic Server 8.1. For example:


  2. Modify WL_HOME

    must point to your WebLogic Server 8.1 installation directory. For example:


  3. Modify PATH

    so that it includes your %WL_HOME% 8.1 home. For example:


  4. Modify CLASSPATH

    so that it points to the WebLogic Server 8.1 classes. For example:


  5. Modify or eliminate any WebLogic Server 6.x startup script directory structure tests. For example, if your script tries to verify a relative path, either fix the directory structure test or remove it.

WebLogic Server 8.1 installs the JVM, JDK 1.4.1, with the server installation. The scripts provided with the server all point to the JVM. The latest information regarding certified JVMs is available at the Certifications Page.


Understanding the WebLogic Server 8.1 Directory Structure

The directory structure in WebLogic Server 8.1 is different from that of 6.x. For complete information on the updated directory structure see Understanding the WebLogic Server Directory Structure in Performing Post-Installation Tasks in the Installation Guide.

If you are booting your WebLogic Server 6.x domain with the WebLogic Server 8.1 environment, the new directory structure is created automatically. However, if you have custom tools or scripts that rely on the WebLogic Server 6.x domain directory structure, you need to update those tools relative to the new directory structure. Similarly, if you have a scripted tool for creating domains in the WebLogic Server 6.x environment, you will have to change those scripts. It is best to use the Configuration Wizard which can be scripted.


Upgrading an Application from WebLogic Server 6.x to WebLogic Server 8.1

The following steps upgrade an application from WebLogic Server 6.1 to WebLogic Server 8.1:

This section describes these steps in detail.

  1. Install WebLogic Server 8.1, if you have not already done so. See the Installation Guide for instructions.

    Note: Installing the new version in the exact location of the old version is explicitly prohibited by the installer.

  2. Create or select a directory for the WebLogic Server 8.1 domain that will house all the configuration information for your application after you have upgraded it.

    Each 6.1 and 8.1 domain must have its own directory, because it is not possible to have multiple config.xml files in the same directory.

    If your 6.1 /config/domain directory is not located in the WebLogic Server 6.1 installation, you can re-use your WebLogic 6.1 location for WebLogic Server 8.1.

  3. If you are not reusing the directory your application used for its WebLogic Server 6.1 domain, copy the application's /config/domain directory to the directory location you chose or created for the WebLogic Server 8.1 domain.

    Tip: You can delete any directories that begin with a dot ("."), which are files or directories that WebLogic Server has created for its own use.

  4. Make the relative paths in the application's deployment descriptor files (web.xml, weblogic.xml, ejb-jar.xml, weblogic-ejb-jar.xml, application.xml, and others) point to the actual locations of any external files to which they refer.

    WebLogic Server configurations rely on a number of files that may be stored on the file system. Typically, these files are persistence repositories (log files, file-based repositories, etc.) or utilities (Java compiler). These files can be configured using fully qualified or relative paths.

    If all external files are defined using relative paths and are located in or below the domain directory, skip the remainder of this step.

    For external files that are defined using relative paths that are located outside the domain directory, re-create the directory structure relative to the new config directory and copy the associated files into the new directories. For external files that are defined using fully qualified paths, determine whether it is appropriate to re-use these files in the WebLogic Server 8.1 deployment.

    For example, log files and persistence stores can be re-used; however, you may want to update utilities such as the Java compiler to use the latest version. For files that should be updated, use the WebLogic Server 8.1 Administration Console to configure the appropriate attribute to use the new file or utility before proceeding to the next step.

  5. If you have not already edited the server start scripts, do so now. See Modifying Startup Scripts for detailed instructions.

Note: WebLogic Server 8.1 will not deploy applications that have deployment descriptor errors.


Additional Upgrade Procedures and Information

The following sections provide additional information that may be useful about deprecated features, upgrades, and the important changes that have been made in WebLogic Server 8.1.

Note: WebLogic Server 8.1 uses PointBase 4.2 as a sample database and does not bundle the Cloudscape database.

Apache Xalan XML Transformer

The built-in transformer in WebLogic Server 8.1 is based on the Apache Xalan 2.2 transformer.

Use of the Xalan APIs directly has been deprecated. If you are still using those APIs and encounter difficulties, you should use the Java API for XML Processing (JAXP) to use XSLT.

Changes were made to Apache's Xalan code to enable Xerces and Xalan to work together. You may encounter problems if you use Xalan from Apache, because it will not include these changes.

In general, it is best to use JAXP and to port any vendor-specific code to a neutral API such as JAXP for SAX, DOM, and XSL processing.

Previous versions of WebLogic Server included the unmodified versions of the Xerces parser and Xalan transformer from in the WL_HOME\server\ext\ file. The ZIP file no longer includes these classes and interfaces. Download the unmodified Xerces parser and Xalan transformer directly from the Apache Web site.

Apache Xerces XML Parser

The built-in XML parser for WebLogic Server 8.1 is based on the Apache Xerces 1.4.4 parser. The parser implements version 2 of the SAX and DOM interfaces. Users who used older parsers that were shipped in previous versions may receive deprecation messages.

WebLogic Server 8.1 also includes the WebLogic FastParser, a high-performance XML parser specifically designed for processing small to medium size documents, such as SOAP and WSDL files associated with WebLogic Web services. Configure WebLogic Server to use FastParser if your application handles mostly small to medium size (up to 10,000 elements) XML documents.

Previous versions of WebLogic Server included the unmodified versions of the Xerces parser and Xalan transformer from in the WL_HOME\server\ext\ file. The ZIP file no longer includes these classes and interfaces. Download the unmodified Xerces parser and Xalan transformer directly from the Apache Web site.

To see the explicit differences between the old and new parsers, use a tool contained in the file located on dev2dev Online.

Applications Directory

In WebLogic Server 6.1, 7.0, and 8.1 there is a division between runtime modes. The two modes are "development" and "production." The runtime mode is selected using a command line parameter when starting the Weblogic Server (-Dweblogic.ProductionModeEnabled=true | false). If this parameter is not set, the server runs in development mode. In development mode the server behavior is consistent with WebLogic Server 6.0. In production mode, however, the auto-deployment feature is disabled. Deployment units in the applications directory that are not explicitly deployed in the configuration repository (config.xml) will not be automatically deployed.


WebLogic Server 8.1 uses a two-phase deployment model. For more information on this deployment model and other 8.1 deployment features, see WebLogic Server Deployment. By default, statically configured applications use the 6.x deployment model. Deployments initiated through the console or the new weblogic.Deployer command line utility use the new two-phase deployment model.

WebLogic Server 8.1 will not deploy an application that has any errors in its deployment descriptor. Previous versions of WebLogic Server would deploy an application that had errors in its deployment descriptor. For example, if your 6.x application was missing a reference description stanza in the deployment descriptor, the application will not deploy in the 8.1 server until you add that stanza. A typical stanza looks like:


Using WebLogic Server 8.1, you can no longer deploy through the console using the 6.x protocol. As a result, you must use the new deployment APIs. If your application is previously deployed in 6.x and you're just starting your server, the applications will get deployed with one-phase deployment. The weblogic.deploy and weblogic.refresh command line utilities and the, and are deprecated in 8.1.

See Deprecated APIs and Features for information on deprecated MBean attributes and operations.

The applications in the applications directory in development mode on the Administration Server are now staged. In 6.x, they were not. For more information see Application Staging in the section called Two-PhaseDeployment in Developing WebLogic Server Applications.

EJB 2.0

The EJB 2.0 specification has changed substantially between WebLogic Server 6.0 and WebLogic Server 8.1, and somewhat between WebLogic Server 6.1 and WebLogic Server 8.1.

Some of the prominent changes are listed here. To see a complete listing of the specification changes from WebLogic Server 6.0 to WebLogic Server 8.1, you can view and download the EJB 2.0 final specification at

For more information about the changes between WebLogic Server 6.0 and WebLogic Server 6.1, see EJB Enhancements in WebLogic Server in Introducing WebLogic Server Enterprise JavaBeans in the WebLogic Server 6.1 documentation. EJB 1.1 beans that worked in WebLogic Server 6.x should work just as well in WebLogic Server 8.1 with no alteration.

You may have to make the following changes to EJB 2.0 beans:

Other major changes that resulted from the EJB 2.0 specification changes are as follows:

If you have trouble with a servlet within the scope of application deployment see Deployment. Changes

Beginning in Weblogic Server 6.1 and continuing in WebLogic Server 8.1, the interface changed so that it extends both ComponentMBean and EJBContainerMBean. Any methods that implement EJBComponentMBean (for example, getVerboseEJBDeploymentEnabled) must be changed to support EJBContainerMBean when you upgrade from WebLogic Server 6.0 to 8.1.

max-beans-in-cache Parameter

In WebLogic Server 8.1 the max-beans-in-cache parameter controls the maximum number of beans in the cache for Database concurrency. In earlier WebLogic Server versions, max-beans-in-cache was ignored; the size of the cache was unlimited. You may need to increase the size of this parameter.

Fully Qualified Path Expressions

In an EJB QL Query on WebLogic Server 8.1, all path-expressions must be fully qualified. This is a change from WebLogic Server 6.x. If you see an ejbc error while running ejbc on WebLogic Server 8.1 using a 6.x EJB, you need to correct either your ejb-ql elements in your ejb-jar.xml file or your weblogic-ql elements in your weblogic-cmp-jar.xml file. For example:


For information about upgrading from WebLogic jCOM 6.1 to WebLogic jCOM 8.1 see Upgrading Considerations in Programming WebLogic jCOM.


WebLogic Server 8.1 supports the JavaSoft JMS specification version 1.0.2.

All WebLogic JMS 6.x applications are supported in WebLogic JMS 8.1. However, if you want your applications to take advantage of the new highly available JMS features, you will need to configure your existing physical destinations (queues and topics) to be part of a single distributed destination set. For more information on using JMS distributed destinations, see Using Distributed Destinations in Programming WebLogic JMS.

For more information on porting your WebLogic JMS applications, see Porting WebLogic JMS Applications in Programming WebLogic JMS.


All public WebLogic Server 6.x MBeans and attributes are supported in WebLogic Server 8.1. However, if you are employing internal MBeans or attributes, you may encounter porting issues.

See Deprecated APIs and Features for information on deprecated MBean attributes and operations.

Jolt Java Client

Jolt users will need to upgrade to Jolt Java Client 8.0.1 to enable BEA Tuxedo services for the Web using BEA WebLogic Server 8.1. The Jolt Java Client 8.0.1 is available from the BEA Product Download Center. Follow the link to BEA WebLogic Server 7.0 and select the Jolt Java Client 8.0.1 from the Modules for WebLogic Server list.


Due to changes in the JSP specification, null request attributes return the string "null" instead of an empty string. For more information, see information about issue 074843 in the Release Notes.

Managed Servers

A Managed Server running WebLogic Server 6.x cannot obtain its configuration and boot using an Administration Server running WebLogic Server 8.1. Make sure that you do not copy the running-managed-servers.xml file from your WebLogic Server 6.x installation directory to your WebLogic Server 8.1 installation directory.

MBean API Change

In previous versions, the class had the static method, getActiveDomain(). In Weblogic Server 8.1, getActiveDomain() is no longer static. In its place, use Admin.getInstance().getAdminMBeanHome().getActiveDomain();

For an example of how to use this alternative API, see Determining the Active Domain and Servers in Programming WebLogic Server JMX Services.


Update your web.xml file so that it uses the following new classes:


instead of




instead of


If you have trouble with a servlet within the scope of application deployment see Deployment.

Thread Pool Size

In WebLogic Server 6.0, the number of worker threads was specified via the ThreadPoolSize parameter on the server MBean. Starting in WebLogic Server 6.1, the number of worker threads is defined via an ExecuteQueue on the Server MBean.

WebLogic Server 8.1 provides a porting path for this parameter, so that if it is specified in the config.xml file, or if it is passed to the client or server on the command line (-Dweblogic.ThreadPoolSize=<xx>), WebLogic Server ports your ThreadPoolSize to the ThreadCount setting automatically.

Setting the number of worker threads:

In WebLogic Server 6.x:


Starting in WebLogic Server 7.0:

... >
ThreadCount="23" />

To change the thread count value via the Console:

1. In the console, select Servers > myServer > Monitoring > .

2. Click on Monitor all Active Queues.

3. Click on "default" queue (a list of threads and what they are doing appears).

4. Click on Configure Execute Queues (at the top of the page).

5. Click on "default" queue.

6. Enter the number of threads associated with this server.

7. Restart the server to make changes take effect.

Web Applications

The API (in WebLogic Server 6.0) has changed to in WebLogic Server 6.1 and 7.0 and 8.1. You will have to update your source code and recompile if you are using this interface.

With Java Servlet Specification 2.3, authorization-on-forward is no longer default behavior. To obtain authorization when you forward to a secure resource, add <check-auth-on-forward> to the weblogic.xml file.

Servlet Request and Response objects have a new API. Some serializable, lightweight implementations of these may no longer compile without implementing the new API. It is strongly recommended that you use the Servlet 2.3 model and substitute your implementations of Servlet Request and Response objects. If you did this in WebLogic Server 6.0, you were probably relying on the undocumented, internal implementations of these objects. WebLogic Server 8.1 supports Servlet 2.3, so you should be able to take advantage of the new ServletRequest/ResponseWrapper objects.

WebLogic Server Clusters on Solaris

Certain applications (heavy EJB apps) deployed in a WebLogic Server cluster on Solaris will perform better using the client JVM rather than the server JVM. This is especially true under heavy loads.

Web Services

Due to changes in the Web service runtime system and architecture between versions 6.1 and 8.1 of WebLogic Server, you must upgrade Web services created in version 6.1 to run on version 8.1.

The WebLogic Web services client API included in WebLogic Server 6.1 of has been deprecated and you cannot use it to invoke 8.1 Web services. WebLogic Server 8.1 includes a new client API, based on the Java API for XML-based RPC (JAX-RPC).

For detailed information on upgrading a 6.1 WebLogic Web service to 8.1, see Upgrading 6.1 WebLogic Web Services to 8.1.

For examples of using JAX-RPC to invoke WebLogic Web services, see Invoking Web Services.

For general information on the differences between 6.1 and 8.1 Web services, see Overview of WebLogic Web Services.

Writable config.xml File

WebLogic Server 8.1 automatically updates configuration information read from the 6.x config.xml file to include WebLogic Server 8.1 information. In order for these changes to be retained between invocations of the server, the config.xml file must be writable. To allow the file to be writable, make a backup copy of your config.xml file from your 6.x configuration and change the file attributes.

Deprecated APIs and Features

Removed APIs and Features

WebLogic Enterprise Connectivity (WLEC) examples have been removed.


Back to Top Previous Next