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:

• Upgrading Your WebLogic Server Configuration: Main Steps
• Modifying Startup Scripts
• Understanding the WebLogic Server 8.1 Directory Structure
• Upgrading an Application from WebLogic Server 6.x to WebLogic Server 8.1
• Additional Upgrade Procedures and Information

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:

   -Dbea.home=C:\bea700

2. Modify WL_HOME

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

   WL_HOME=c:\bea700\weblogic700

3. Modify PATH

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

   PATH=%WL_HOME%\bin;%PATH%

4. Modify CLASSPATH

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

   CLASSPATH=%WL_HOME%\lib\weblogic_sp.jar;%WL_HOME%\lib\weblogic.jar

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 setenv.sh 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:

• Install WebLogic Server 8.1
• Create or select a directory for your application's WebLogic Server 8.1 configuration domain
• Copy your configuration information to the new domain directory
• Make sure that relative paths to external files are correct.
• Edit server start scripts.

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
• Apache Xerces XML Parser
• Applications Directory
• Deployment
• EJB 2.0
• jCOM
• JMS
• JMX
• Jolt Java Client
• JSP
• Managed Servers
• MBean API Change
• Servlets
• Thread Pool Size
• Web Applications
• WebLogic Server Clusters on Solaris
• Web Services
• Writable config.xml File
• Deprecated APIs and Features
• Removed APIs and Features

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 www.apache.org in the WL_HOME\server\ext\xmlx.zip 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 www.apache.org in the WL_HOME\server\ext\xmlx.zip 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 apichange.zip 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.

Deployment

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:

<ejb-reference-description>
<ejb-ref-name>ejb/acc/Acc</ejb-ref-name>
<jndi-name>estore/account</jndi-name>
</ejb-reference-description>

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 weblogic.management.tools.WebAppComponentRefreshTool, 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 http://java.sun.com/products/ejb/2.0.html.

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:

• If your deployment descriptor contains a 6.0 element that has a different name in 8.1, you have to manually change the name in your deployment descriptor. The following are some examples of element names that you may need to change in 8.1:
• In 8.1, the name of the element that is used to identify a particular EJB that participates in a relationship is relationship-role-source. In 6.0, the element name was role-source.
• In 8.1, the name of the element that specifies whether the destination is a queue or a topic is destination-type. In 6.0, the element name was jms-destination-type.
• In 8.1, the name of the element that specifies whether the destination is a queue or a topic is run-as. In 6.0, the element name was run-as-specified-identity.
• In 8.1, EJB-QL queries require a SELECT clause.
• All EJB 2.0 CMP beans must have an abstract-schema-name element specified in their ejb-jar.xml in WebLogic Server 8.1.

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

• There were no local interfaces in 6.0, but they exist in 6.1 and 7.0 and 8.1.
• Remote relationships do not exist in 6.1 and 7.0 and 8.1.
• The new implementation of read-only beans in Acadia does not require NOT_SUPPORTED for a transaction attribute. It also doesn't do exclusive locking, but gives each transaction its own instance of the read-only bean to use.
• In pre-2.0 final versions of our EJB implementation you could refer to a CMP or CMR field in a EJB QL query without using a qualified path. However, as of the final specification, all EJB QL queries must have a qualified path.
• The new implementation of read-only beans in Acadia does not require NOT_SUPPORTED for a transaction attribute. The new implementation also does not do exclusive locking, but gives each transaction its own instance of the read-only bean to use.

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

weblogic.management.configuration.EJBComponentMBean Changes

Beginning in Weblogic Server 6.1 and continuing in WebLogic Server 8.1, the interface weblogic.management.configuration.EJBComponentMBean 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:

• WebLogic Server 6.x would allow the following query to compile:

SELECT address FROM CustomerBean AS c WHERE zip = ?1 

• For WebLogic Server 8.1 to allow the same query to be compiled, the address and zip fields must be qualified:

SELECT c.address FROM CustomerBean AS c WHERE c.zip = ?1

jCOM

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

JMS

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.

JMX

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.

JSP

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 weblogic.management.Admin 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.

Servlets

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

weblogic.servlet.proxy.HttpClusterServlet

instead of

weblogic.servlet.internal.HttpClusterServlet

and

weblogic.servlet.proxy.HttpProxyServlet

instead of

weblogic.t3.srvr.HttpProxyServlet

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:

<Server
Name="myserver"
ThreadPoolSize="23"
...
/Server>

Starting in WebLogic Server 7.0:

<Server
Name="myserver"
... >
<ExecuteQueue
Name="default"
ThreadCount="23" />
/Server>

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 weblogic.management.runtime.ServletRuntimeMBean.getName() API (in WebLogic Server 6.0) has changed to weblogic.management.runtime.ServletRuntimeMBean.getServletName() 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

• WebLogic Time Services is deprecated and should be replaced by JMX Timer Service. For documentation of JMX Timer Service, see Interface TimerMBean and Class Timer.
• WebLogic Workspaces
• Zero Administration Client (ZAC) is deprecated in this release of WebLogic Server 8.1. It is replaced by JavaWebStart.
• WebLogic Enterprise Connectivity (WLEC) is deprecated in this release of WebLogic Server 8.1. Tuxedo CORBA applications using WLEC should migrate to WebLogic Tuxedo Connector. For more information, see WebLogic Tuxedo Connector.
• weblogic.deploy is deprecated in this release of WebLogic Server 8.1 and has been replaced by weblogic.Deployer. For more information, see Deployment Tools and Procedures in WebLogic Server Deployment.
• weblogic.management.tools.WebAppComponentRefreshTool and weblogic.refresh are both deprecated in this release of WebLogic Server 8.1. They have been replaced by weblogic.Deployer.
• If you did programmatic deployment or used the weblogic.Admin command in order to create application and component MBeans, set the attributes on the MBeans, and invoke operations on those MBeans to cause them to get deployed in the system, the following MBean attributes and operations have been deprecated:

Deprecated ApplicationMBean operations:

deploy

load

undeploy

Deprecated ApplicationMBean attributes:

LastModified

LoadError

isDeployed

Please refer to the WebLogic Server 8.1 javadocs for the ApplicationMBean interface to see what has replaced these attributes and operations.

Removed APIs and Features

WebLogic Enterprise Connectivity (WLEC) examples have been removed.