Skip navigation.
Downloads | Product Documentation | Support

WebLogic Server 8.1 Upgrade Guide

# Upgrading WebLogic Server 7.0 to Version 8.1

Upgrading WebLogic Server 7.0 to version 8.1 involves copying your domain to a new directory and changing your WebLogic Server start command scripts and environment settings.

The following sections of this document contain information about upgrading your domain from WebLogic Server 7.0 to WebLogic Server 8.1:

- Understanding the WebLogic Server 8.1 Directory Structure
- Contents of a Domain Directory
- Upgrading Your WebLogic Server 7.0 Domain to Version 8.1
- Modifying Start Scripts
- Upgrading the Pet Store Application from WebLogic Server 7.0 to WebLogic Server 8.1
- Additional Upgrade Procedures and Information

To see an example of a domain being upgraded from WebLogic Server 7.0 to WebLogic Server 8.1, see Upgrading the Pet Store Application from WebLogic Server 7.0 to WebLogic Server 8.1.

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

For information on upgrading WebLogic Server license files, see "Installing and Updating WebLogic Platform License Files" in Installing WebLogic Platform.

For information on upgrading WebLogic Server security, see Security.

# Understanding the WebLogic Server 8.1 Directory Structure

BEA WebLogic recommends that you locate domain directories outside the WebLogic Server installation directory. Starting with WebLogic Server 7.0, domain directories can be in any location that can access the WebLogic Server installation and the JDK.

If you change the location of your domain directory, remember to update any custom tools or scripts relative to the new directory structure. Similarly, if you use a scripted tool for creating domains, change its scripts. The scriptable Configuration Wizard is the recommended tool for creating domains.

# Contents of a Domain Directory

When you upgrade from WebLogic Server 7.0 to 8.1, you are upgrading a WebLogic Server domain. For a full description of WebLogic Server domains see Overview of WebLogic Server Domains in Configuring and Managing WebLogic Server.

Domain configuration settings are stored in the `config.xml` file of the domain directory. `config.xml` stores the name of the domain and the configuration parameter settings for each server instance, cluster, resource, and service in the domain.

The domain directory also contains the server start script files that you can use to start the Administration Server and Managed Servers in the domain.

The domain directory structure has a root directory with the same name as the domain, such as mydomain or petstore. This directory contains the following:

- The configuration file (usually `config.xml`) for the domain.
- Any scripts you use to start server instances and establish your environment.
- Optionally, a subdirectory for storing the domain's application files.

For more information about WebLogic Server domains, see WebLogic Server Domains in Configuring and Managing WebLogic Server.

# Upgrading Your WebLogic Server 7.0 Domain to Version 8.1

To upgrade a domain with multiple server instances, upgrade as you would a single-server domain. In a nutshell, you upgrade a domain by installing WebLogic Server 8.1 alongside your 7.0 installation, copying the contents of your 7.0 domain into a new 8.1 domain directory, and changing the domain scripts and environment settings to point to the new 8.1 domain and server instances.

If the domain includes a cluster and you want to take advantage of new clustering features in WebLogic Server 8.1, refer to Setting Up WebLogic Clusters in Using WebLogic Server Clusters for WebLogic Server 8.1 cluster configuration guidelines.

As a prerequisite to performing the upgrade procedures in this section, install WebLogic Server 8.1 on all the machines that contain 7.0 server instances whose domain you will upgrade. See Installing WebLogic Platform for installation instructions for WebLogic Server 8.1.

- Shut Down WebLogic 7.0 Server Instances
- Create a WebLogic Server 8.1 Domain Directory
- Copy Contents of Your 7.0 Domain into the 8.1 Directory
- Delete WebLogic Server 7.0 Settings from the 8.1 Domain
- Modify Server Start Scripts
- Upgrade Applications
- Start 8.1 Administration and Managed Servers
- Configure and Deploy Your Applications

## Shut Down WebLogic 7.0 Server Instances

Shut down all server instances in the WebLogic Server 7.0 domain you are upgrading.

Shutting down the servers ensures that any recent changes to the domain or its applications are persisted. See Starting and Stopping Servers: Quick Reference.

## Create a WebLogic Server 8.1 Domain Directory

Create a new directory where your 8.1 domain will reside.

Consider that after you move the contents of your 7.0 domain directory to this new 8.1 domain directory, any references from within the 7.0 domain to resources outside the domain will need to change unless the new domain directory is in the same relative location to the external resources.

## Copy Contents of Your 7.0 Domain into the 8.1 Directory

Copy the contents of your WebLogic Server 7.0 domain directory to the new 8.1 domain directory, including the server start scripts and configuration settings (see Contents of a Domain Directory).

Once you have upgraded the domain to WebLogic Server 8.1, you may not be able to convert it back to WebLogic Server 7.0, so it is a good idea to leave the original domain as a backup.

BEA Systems recommends that domains be located outside of the WebLogic Server install directory.

Note: At this point, application paths in the newly created domain still point to the applications that were deployed in the 7.0 domain. Do not try to start server instances in either domain until you have completed the domain conversion—if you simultaneously run server instances that deploy the same applications under different versions of WebLogic Server, problems are likely to occur.

## Delete WebLogic Server 7.0 Settings from the 8.1 Domain

In the new domain directory, delete the contents of all `.internal` and `.wlnotdelete` directories. These directories may contain version-specific generated settings that can cause problems in the 8.1 domain.

The location of these directories depends on your domain configuration. In the Petstore upgrade example (see Upgrading the Pet Store Application from WebLogic Server 7.0 to WebLogic Server 8.1), these directories are located at `C:\petstorefrom70to81\server\config\petstore\petstoreServer\.internal` and `C:\petstorefrom70to81\server\config\petstore\petstoreServer\.internal\.wlnotdelete`.

## Modify Server Start Scripts

Modify the server start scripts in the 8.1 domain directory to start WebLogic Server 8.1 server instances instead of 7.0 server instances. Do this for all Administration Servers and Managed Servers in the upgraded domain. The names of default start scripts created with new WebLogic Server domains are `startWebLogic.cmd` (or .`sh`) (for Administration Servers) and `startManagedWebLogic.cmd` (or `.sh`) (for Managed Servers).

The server start scripts in both the 7.0 and the 8.1 domains reference a server start script `startWLS.cmd` in the `WL_HOME\server\bin` directory, where `WL_HOME` is the WebLogic Server installation.

Edit server start scripts that call the `startWLS.cmd` script in your WebLogic Server 7.0 `WL_HOME70\server\bin` directory to call instead the `startWLS.cmd` script in your WebLogic Server 8.1 `WL_HOME81\server\bin` directory.

Depending on your server start script, it is likely that you need to change the settings of several of its properties. See Modifying Start Scripts.

## Upgrade Applications

Upgrade your applications to WebLogic Server 8.1.

This may involve editing your application's deployment descriptor files and the domain configuration file, `config.xml`.

1. Make sure that when your applications reference a file outside of your new 8.1 domain, they still reference the correct address of the external file.

References to external files may have been made inaccurate when you moved your application to the new 8.1 domain, if the 8.1 domain is in a location relative to the external files that is not the same as the location of the old 7.0 domain. Deployment descriptor files and `config.xml` must accurately reference external files (for example log files, file-based repositories, the Java compiler) relative to the new domain directory.

2. Optionally, upgrade references to utilities that you want to upgrade.

For example, update the Java compiler to a newer version by using the WebLogic Server 8.1 Administration Console to update the appropriate attribute for the new version of the utility. For example, to change the Java compiler in the Administration Console, select the server in the left hand pane, go to Configuration | General in the right hand pane, and change the value in the Java Compiler field. If you plan to recompile your applications using WebLogic Server 8.1, reference JDK 1.4 when you build (see Reference JDK 1.4 When Compiling in 8.1).

3. Your application may require additional upgrade steps to account for other factors (for example, new parsers, new or deprecated deployment descriptor elements, altered APIs). See Additional Upgrade Procedures and Information for information about these factors.

## Start 8.1 Administration and Managed Servers

Start WebLogic Server 8.1 Administration and Managed servers. For information about starting WebLogic Server 8.1, see Starting and Stopping Servers: Quick Reference.

Note: WebLogic Server 8.1 automatically updates configuration information read from the 7.0 `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. If you have made your `config.xml` read-only, access its file properties and change the attribute so that it is writable. For example, in Windows, right-click the file in Windows Explorer, select Properties, and make sure that the Read-Only attribute is unchecked.

## Configure and Deploy Your Applications

For information about configuring and deploying your applications, see Deployment.

# Modifying Start Scripts

For a concrete example of a 7.0 start script being modified to 8.1, see Upgrading the Pet Store Application from WebLogic Server 7.0 to WebLogic Server 8.1.

The following general procedure shows how to modify start scripts from WebLogic Server 7.0 to work with WebLogic Server 8.1.

1. In the new 8.1 domain created in Upgrading Your WebLogic Server 7.0 Domain to Version 8.1, edit the WebLogic 7.0 start scripts which still point to the 7.0 `startWLS.cmd` (or `.sh`) script to point to the WebLogic Server 8.1 `startWLS.cmd` (or `.sh`) script.

Change all of your WebLogic 7.0 server start scripts to 8.1 server start scripts, including start scripts based on the scripts that the WebLogic Server 7.0 Domain Configuration Wizard generated for your WebLogic Server 7.0 domain Administrative and Managed Servers.

These scripts still point to the WebLogic Server 7.0 script located at `WL_HOME70\server\bin\startWLS.cmd` (or `.sh`); edit them to point to the new WebLogic Server 8.1 script.

For example, change:

>     call "WL_HOME70\server\bin\startWLS.cmd"

to:

>     call "WL_HOME81\server\bin\startWLS.cmd"

Where:

- `WL_HOME70` is the install directory for WebLogic Server 7.0, typically`C:\bea\70platform\weblogic700`
- `WL_HOME81` is the install directory for WebLogic Server 8.1, typically `C:\bea\weblogic81`

An alternative method for changing this value in a server start script is to define a `WL_HOME` variable at the start of the script, for example:

>     set WL_HOME=C:\bea\weblogic81

and then change the value from

>     call "C:\bea\70platform\weblogic700\server\bin\startWLS.sh"

to:

>     call "%WL_HOME%/server/bin/startWLS.sh"

Depending on what settings your start scripts contain, you may need to modify additional settings such as those described in the remaining steps of this section.

1. Modify `JAVA_HOME`

to point to the JDK that WebLogic Server 8.1 uses. For example, change:

>     set JAVA_HOME=WL_HOME\jdk131_03

to:

>     set JAVA_HOME=WL_HOME\jdk141

See Java 2 Platform, Standard Edition Version 1.4.0 Compatibility with Previous Releases for information if you receive error messages about JDK 1.4.1.

2. 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:\bea810`

3. Modify `WL_HOME` to point to the WebLogic Server 8.1 installation directory. For example:

`WL_HOME=c:\bea810\weblogic810`

4. Modify `PATH` to include your `%WL_HOME%` 8.1 home. For example:

`PATH=%WL_HOME%\bin;%PATH%`

5. Modify `CLASSPATH` to point to the WebLogic Server 8.1 classes. For example:

`CLASSPATH=%WL_HOME%\lib\weblogic.jar`

6. Modify or eliminate any WebLogic Server 7.0 start script directory structure tests.

For example, if your script contains a test such as

>     if not exist lib\weblogic.jar goto wrongplace

and `lib\weblogic.jar` is not accurate from the location of the script, either change it to point to the relative location of `weblogic.jar`, or simply delete the line.

7. Consider upgrading your JVM to JRockit (see Upgrading Your JVM to JRockit).

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

# Upgrading the Pet Store Application from WebLogic Server 7.0 to WebLogic Server 8.1

This section walks through an actual upgrade of Sun's Pet Store application from WebLogic Server 7.0 to 8.1. This walkthrough uses the version of Pet Store that is included with WebLogic Server 7.0.

The prerequisite for the following procedures is WebLogic Server 7.0 and 8.1 installed on the same machine.

1. Create a new directory in which to upgrade the WebLogic Server 7.0 domain to a WebLogic Server 8.1 domain. In this walkthrough, the new directory is located at `C:\petstorefrom70to81`. This domain should reside outside the WebLogic Server 8.1 installation directory.
2. From the WebLogic Server 7.0 installation, copy the `WL_HOME``\samples\server` directory and its contents to `C:\petstorefrom70to81`.
3. Open the `config.xml` file in `C:\petstorefrom70to81\server\config\petstore.` Make the following edits.

1. Edit the application paths to point to `C:/petstorefrom70to81`. Replace:

>     Path="WL_HOME/samples/server/stage/petstore/petstore.ear" TwoPhase="true">

with:

>     Path="c:/petstorefrom70to81/server/stage/petstore/petstore.ear" TwoPhase="true">

For `petstoreadmin.ear`, `opc.ear`, and `supplier.ear`, and `tour.war`, likewise replace the WebLogic Server 7.1 `WL_HOME` path with the `c:\petstorefrom70to81` path.

2. Add `XAConnectionFactoryEnabled="true"` to the "Topic" JMSConnectionFactory configuration so that it is automatically enlisted in JTA transactions. Replace:

>     <JMSConnectionFactory JNDIName="jms/TopicConnectionFactory" Name="Topic" Targets="petstoreServer" />

with:

>     <JMSConnectionFactory JNDIName="jms/TopicConnectionFactory"
>     Name="Topic" Targets="petstoreServer" XAConnectionFactoryEnabled="true" />

3. Optionally replace the `XAServerEnabled` attribute in the "Queue" JMSConnectionFactory with `XAConnectionFactoryEnabled`. Replace:

>     <JMSConnectionFactory JNDIName="jms/QueueConnectionFactory" Name="Queue" Targets="petstoreServer" XAServerEnabled="true" />

with:

>     <JMSConnectionFactory JNDIName="jms/QueueConnectionFactory" Name="Queue" Targets="petstoreServer" XAConnectionFactoryEnabled="true" />

`XAServerEnabled` is deprecated in WebLogic Server 8.1, but is still supported for backward compatibility.

4. Change the path to the Java compiler, if necessary.

4. Open the `startpetstore.cmd` (or .sh) script in `C:\petstorefrom70to81\server\config\petstore` and make the following changes:

1. Change the `%JAVA_HOME%` alias from the JDK that your WebLogic Server 7.0 installation uses to the JDK that your WebLogic Server 8.1 installation uses. For example:

>     set JAVA_HOME=WL_HOME\jdk131_03

becomes:

>     set JAVA_HOME=WL_HOME\jdk141

2. Change the `%SAMPLES_HOME%` alias from the WebLogic Server 7.0 `\samples` directory to the WebLogic Server 8.1 `\samples` directory. For example:

>     set SAMPLES_HOME=WL_HOME\samples

becomes:

>     set SAMPLES_HOME=C:\petstorefrom70to81

3. Change the `startWLS.cmd` (or `.sh`) path from the WebLogic Server 7.0 installation to the WebLogic Server 8.1 installation:

>     call "C:\bea70sp1\weblogic700\server\bin\startWLS.cmd"

4. Under `JAVA_OPTIONS`, change the `cacerts` path from the WebLogic Server 7.1 installation to the WebLogic Server 8.1 installation.

>     -Dweblogic.security.SSL.trustedCAKeyStore=WL_HOME\server\lib\cacerts

5. Test the upgrade by using the `startpetstore.cmd` or `.sh` command to start Pet Store, and then browsing to `http://localhost:7001/petstore` to run the application.

# Additional Upgrade Procedures and Information

This section contains additional information that you need to be aware of when upgrading from WebLogic Server 7.0 to 8.1.

- Built-in Transformer Based on Apache Xalan XML 2.2 Transformer
- Apache Xerces XML Parser
- Connectors
- Applications with Errors Will Not Deploy
- Upgrading jCOM
- JDBC
- Upgrading Your JDK
- JMS Configuration Checking Is Stricter
- Upgrading Your JVM to JRockit on page 17
- Changes to Timeouts for Pool, JTS/JTA, and RMI Connections
- Prepared Statement Cache Algorithm
- Default Names for Execute Queues Have Changed
- Security
- URIs
- Web Applications
- Web Services
- EJB 2.0
- Writable config.xml File

## Built-in Transformer Based on Apache Xalan XML 2.2 Transformer

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

Direct use of the Xalan APIs has been deprecated. If you use those APIs and encounter difficulties, use the Java API for XML Processing (JAXP) to use XSLT.

WebLogic Server's built-in transformer contains changes to Apache's Xalan code that 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.

## Apache Xerces XML Parser

The Xerces XML parser used in Weblogic Server 8.1 is stricter than the one used in WebLogic Server 7.0, and may refuse to parse erroneous XML that was accepted by the WebLogic Server 7.0 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. Parsers from previous versions may trigger 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. For more information, see Administering WebLogic Server XML.

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.

## Connectors

The following sections describe changes to resource adapter functionality in WebLogic Server 8.1.

### Last-Resource Commit Optimization

Normally, for a client to perform operations on multiple resource adapter connections to participate in a global / XA transaction, the resource adapters involved are required to support XATransaction. However, resource adapters that only support local transactions may also be involved in a global / XA transaction, in a limited manner. This is due to the fact that they do not receive two-phase commit messages from the Transaction Manager.

In WebLogic Server 8.1, if the server detects a Local Transaction capable resource adapter connection in a global transaction, the transaction manager first issues prepare messages to the XAResources involved in the transaction. Then, after all XAResources have prepared successfully, the operation on the local transaction-capable resource adapter is performed. If the operation is successful, the global transaction is committed. If the operation fails, the global transaction is rolled back. This prevents the possibility of the Local Transaction resource adapter's commit failing after an XA resource has already been committed.

Notes: This optimization allows multiple XAResources but not more than one Local Transaction capable resource adapter to participate in a global transaction. Attempts to include more than one Local Transaction capable resource adapter in a global / XA transaction will fail with an exception.

Prior to WebLogic Server 8.1, there was no restriction on the number of Local Transaction capable resource adapters that could be involved in a global / XA transaction. Also, the ordering of the prepares and commits was not coordinated specially for Local Transaction capable resource adapters as it now is in WebLogic Server 8.1. It was previously possible for a call to commit on a Local Transaction capable resource adapter to fail after some of the XA Transaction resource adapters had already been successfully committed. This event caused some resources to be committed and some rolled back for a global / XA transaction. The optimization resolves this previous issue.

### Application Container Managed Security Log Messages

Messages indicating whether the client is using application or container-managed security are no longer written to the server log.

### Classloader and Packaging Issues

In WebLogic Server 8.1 each resource adapter has its own classloader to load its classes in the same manner as Web applications. With this change in effect, components like Web applications and EJBs that are packaged along with a resource adapter in an application archive (`.ear` file), do not have visibility into the resource adapter's classes. If visibility is required, place the classes of the resource adapter in `APP-INF/classes` or (packaged in a JAR file) in `APP-INF/lib` directory of the application archive.

## Applications with Errors Will Not Deploy

Unlike previous versions, WebLogic Server 8.1 will not deploy an application that has any errors in its deployment descriptor. For example, if your WebLogic Server 7.0 application was missing a reference description stanza in the deployment descriptor, the application will not deploy in WebLogic Server 8.1 until you add that stanza. A typical stanza looks like this:

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

## Upgrading jCO M

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

## JDBC

This section outlines JDBC-related changes in WebLogic Server 8.1.

### Removed Interfaces

Several interfaces that were previously marked deprecated have been removed:

- DB Kona
- JDBCService

### Removed Classes

In WebLogic Server 8.1, the `weblogic.jdbc.pool` classes were removed, except for the `weblogic.jdbc.pool.Driver` class. These classes were removed because they were incompatible with an internal change that enables and enhances support for JDBC extensions provided in JDBC drivers.

If your application uses these classes, to migrate your application to WebLogic Server 8.1, you must change the application to use vendor-specific JDBC driver classes. For example, if your application uses the `weblogic.jdbc.pool.CallableStatement` class, you should change it to use the class from the JDBC driver, such as `oracle.jdbc.OracleCallableStatement`:

Change this line:

>     weblogic.jdbc.pool.CallableStatement cStat = (weblogic.jdbc.pool.CallableStatement)connection.prepareCall(call);

To this:

>     oracle.jdbc.OracleCallableStatement cStat = (oracle.jdbc.OracleCallableStatement)connection.prepareCall(call);

### Removed Drivers

The following JDBC drivers were removed from WebLogic Server 8.1:

- The WebLogic Sybase jDriver
- The WebLogic MSSQL jDriver

### Interoperability Limitation

When a WebLogic Server 8.1 client interoperates with an older version of the server (accessing data sources, for instance), it is not possible to use Oracle JDBC extensions.

### Statement Caches

Releases before WebLogic Server 8.1 had separate statement cache implementations for XA and non-XA JDBC connection pools. In WebLogic Server 8.1, one statement cache implementation serves both XA and non-XA connection pools. Connection pool attributes in the `JDBCConnectionPoolMBean` for configuring the statement cache are now deprecated.

In version 8.1, Weblogic Server enforces the following order of precedence for these MBean attributes:

`PreparedStatementCacheSize`

`XAPreparedStatementCacheSize`

`StatementCacheSize`

For example, if the `PreparedStatementCacheSize` for a JDBC connection pool is set to 5 and the `StatementCacheSize` is set to 10, the actual statement cache size for each connection in the connection pool will be 5 because `PreparedStatementCacheSize` takes precedence over `StatementCacheSize`.

Other changes:

- Global pools: applications cannot disable statement caching by setting `PreparedStatementCacheSize` to 0.
- Global pools: when upgraded from 7.0 SP3 or later, the `XAPreparedStatementCacheSize` value is ignored when you configure the cache. Instead, use `PreparedStatementCacheSize` to assign the cache size.
- Application-scoped pools: application-specified values for `XaParamsMBean`.`PreparedStatementCacheSize` are ignored when configuring the cache. Instead, `PreparedStatementMBean.CacheSize` is used.
- If you are upgrading an application from 7.0 SP3 or later that is using the XA statement cache, if you want to disable XA statement caching, in WebLogic Server 8.l set the non-XA control (`PreparedStatementMBean.CacheSize`) to 0.

For more information, see Configuring and Managing the Statement Cache for a Connection Pool, in Configuring and Using WebLogic JDBC.

## Upgrading Your JDK

This section addresses issues you may encounter when upgrading to a later JDK.

### Stricter JSP Parsing in JDK 1.3.1_09

Improper code that was acceptable under JDKs before 1.3.1_09 may cause errors under JDK 1.3.1_09 and later. This failure occurs for JSPs and all beans that are subject to the Introspector API. Specifically, disagreement between a property's setter and getter types may cause startup errors like the following after you migrate to JDK 1.3.1_09 or later:

>     Error in using tag library uri='/WEB-INF/tlds/taglib.tld' prefix='j2ee': There is no setter method for property 'numItems', for Tag class 'com.sun.j2ee.blueprints.petstore.taglib.list.SearchListTag' probably occurred due to an error in /template.jsp line 8: <%@ taglib uri="/WEB-INF/tlds/taglib.tld" prefix="j2ee" %>

When a class fails conform to Java bean specifications about type agreement, the `java.beans.Introspector` API no longer returns read or write methods for the offending property. Correct such errors by ensuring that the setters and getters in your classes do not disagree in type. If the setter is an integer, the getter must be an integer also, and must not be a string.

For example, the following snippet shows a valid setter and getter from which we can expect the Introspection API to return valid read and write method(s):

>                     private String foo;

>         public void setFoo(String f) {

>                             foo = f;

>                     }

>                     public String getFoo() {

>                             return foo;

>         }

The following snippet demonstrates bad code that does not conform to Java bean specifications:

>     private int foo; // note that foo is an int

>     public void setFoo(String f) {

>                 foo = Integer.parseInt(f);

>     }

>     public int getFoo() {

>                 return foo;

>     }

In the second case, the type disagreement between the setter and getter will cause an error under JDK 1.3.1_09 and later, because the newer JDKs adhere strictly to the Java bean specifications. */

### Reference JDK 1.4 When Compiling in 8.1

If you compile your application in WebLogic Server 8.1, it is advisable to do subsequent builds referencing JDK 1.4 rather than earlier JDKs.

Some APIs and other items added in JDK 1.4 have been removed in the WebLogic Server 8.1 version of `weblogic.jar`. Such APIs and other items cease to be available to your application in WebLogic Server 8.1 after you compile your application with the 8.1 `weblogic.jar` in place of the earlier version of `weblogic.jar` in your classpath.

JAXP, for example, was included in previous versions of `weblogic.jar`, but is absent from the WebLogic Server 8.1 `weblogic.jar`. JAXP is not in the JDK 1.3, so if your WebLogic Server 7.0 application uses JAXP and you compile it after replacing the 7.0 `weblogic.jar` with the 8.1`weblogic.jar`, build your classes using the JDK 1.4.

Other WebLogic Server 8.1 dependencies on JDK 1.4 include the JAAS package and the Principal Authenticator object.

## JMS Configuration Checking Is Stricter

JMS configuration checking is tighter in WebLogic Server 8.1 than it was in release 7.0, particularly in regards to naming JMS destinations and connection factories. In release 7.0, administrators could configure:

- Multiple JMS destinations within a cluster with the same replicated JNDI name (not including distributed destination members).
- A connection factory with the same JNDI name as the default connection factory.

In release 8.1, however, you cannot assign identical JNDI names in these cases. Therefore, a release 7.0 configuration that has either of these replicated JNDI name scenarios may fail to boot after it is upgraded to release 8.1.

## Upgrading Your JVM to JRockit

When you upgrade a domain to WebLogic Server 8.1, consider upgrading your JVM to JRockit. WebLogic JRockit is a JVM designed for running server-side applications in Windows and Linux running on Intel architectures. For server-side applications, JRockit has these advantages over other virtual machines:

- It employs adaptive optimization, which detects and removes bottlenecks in the deployed application.
- It is designed specifically for the special requirements of server-side applications, which tend to be parallel and thread-intensive, to run for longer periods of time, and not to use graphical interfaces.
- You can monitor JRockit using the WebLogic Server Administration Console.

For JRockit platform and user information, see the appropriate version of the JRockit User Guide.

To upgrade a WebLogic Server domain to the JRockit JVM:

1. In the server start scripts, set `JAVA_HOME` (or equivalent) shell variables to point to the JRockit root directory. For example, change:

>     @rem Set user-defined variables.

>     set JAVA_HOME=WL_HOME\jdk131

where `WL_HOME` is the WebLogic Server 7.0 installation directory, to

>     @rem Set user-defined variables.

>     set JAVA_HOME=WL_HOME\jrockit81_141_02

where `WL_HOME` is the WebLogic Server 8.1 installation directory.

2. Change the domain's `config.xml` to use the JRockit `javac.exe`. For example, change

>     JavaCompiler="WL_HOME\jdk131\bin\javac"

where `WL_HOME` is the WebLogic Server 7.0 installation directory, to

>     JavaCompiler=WL_HOME\jrockit81_141_02\bin\javac"

where `WL_HOME` is the WebLogic Server 8.1 installation directory.

3. Remove from server start scripts any switches specific to the Sun JVM. For example, from the start command:

>     echo on "%JAVA_HOME%\bin\java" -hotspot .... weblogic.Server

delete "`-hotspot`".

4. Start and configure JRockit. See the Starting and Configuring the WebLogic JRockit JVM section for the appropriate version of the JRockit documentation.

## Load Order Behavior for Startup Classes

The behavior of the load order methods in `StartupClassMbean` has changed between versions 7.0 Service Pack 1 and version 8.1.

In 7.0 Service Pack 1, setting `LoadBeforeAppDeployments` to true caused startup classes to be invoked after the datasources were created and before the applications were activated. In version 8.1, achieve the same load order by setting `LoadBeforeAppActivation` to true.

`LoadBeforeAppDeployments` still exists in version 8.1 but its behavior has changed since 7.0 Service Pack 1. Beginning with 7.0 Service Pack 2, `LoadBeforeAppDeployments` has determined whether a startup class is loaded and run before the server activates JMS and JDBC services or deploys applications and EJBs.

See details about these methods in WebLogic Server 8.1 at ../javadocs/weblogic/management/configuration/StartupClassMBean.html.

## Network Channels Include Network Access Point Features

In WebLogic 8.1, network channels encompass the features that, in WebLogic Server 7.0, required both network channels and network access points. If you receive a network channel error message on starting up an upgraded 7.0 domain in WebLogic Server 8.1, reconfigure your network channels as described in Configuring a Channel in Configuring and Managing WebLogic Server.

Network access points are deprecated.

The use of `NetworkChannelMbean` is deprecated in favor of `NetworkAccessPointMBean`.

## Changes to Timeouts for Pool, JTS/JTA, and RMI Connections

In past releases, pool connections waited for 5 seconds before timing out. JTS/JTA connections waited 10 seconds before timing out. RMI Datasource connections were non-blocking.In the WebLogic Server 8.1 release, all connections block for up to 10 seconds before timing out.

In cases where you invoke an application by using RMI/T3 or RMI/IIOP, WebLogic Server 7.0 and 8.1 are interoperable. Within a domain, however, all servers must be of the same version.

## Prepared Statement Cache Algorithm

A new prepared statement cache algorithm has been introduced. It removes the least recently used statements from the cache. The old algorithm kept a fixed number of statements in the cache (the first n, where n is the configured size of the cache). If you want to get the old cache algorithm behavior, the connection pool can be configured to use the "FIXED" algorithm for the pool.

## Default Names for Execute Queues Have Changed

Default names for execute queues have changed in WebLogic Server 8.1. If you upgrade a configuration that specifies execute queues, the default queue names will automatically alias the new queue names.

####

Table 2-1 Default Queue Names

Pre-8.1Default Queue Names | WebLogic Server 8.1 Default Queue Names
--- | ---
`default` | `weblogic.kernel.Default`
`__weblogic_admin_html_queue` | `weblogic.admin.HTTP`
`__weblogic_admin_rmi_queue` | `weblogic.admin.RMI`

## Security

The following sections discuss general changes to security in WebLogic Server 8.1.

### Troubleshooting Problems with Certificates

In versions preceding 7.0 Service Pack 2, WebLogic Server did not ensure each certificate in a certificate chain was issued by a certificate authority. This problem was resolved in Service Pack 2.

If SSL communications worked properly before upgrading to 8.1 but fail unexpectedly after the upgrade, the problem is most likely because the certificate chain is failing validation.

To troubleshoot problems with certificates, try the following methods:

- If you know where the certificate chains for the processes using SSL communication are located, use the `ValidateCertChain` command-line utility to check whether the certificate chains will be accepted. For information about `ValidateCertChain`, see ValidateCertChain in Using the WebLogic Server Java Utilities.
- Turn on SSL debug tracing for the processes using SSL communication. The syntax for SSL debug tracing is:

`-Dssl.debug=true -Dweblogic.StdoutDebugEnabled=true`

The following message indicates the SSL failure is due to problems in the certificate chain:

`CA certificate rejected. The basic constraints for a CA certificate were not marked for being a CA, or were not marked as critical.`

When using one-way SSL, look for this error in the client log. When using two-way SSL, look for this error in the client and server logs.

- Determine where the certificate chain is being rejected, and decide whether to update the certificate chain with one that will be accepted, or make the enforcement of constraints less severe using the `-Dweblogic.security.SSL.enforceConstraints` command-line argument.

### Security Data Is Now Written to the config.xml File

The persistence model for the COMMO MBeans changed in this release of WebLogic Server. All security configuration data is now stored in the `config.xml` file. Existing security configuration data is written to the `config.xml` file when the WebLogic Server 8.1 server is initially booted. The `config.xml` file must be writable for this upgrade to occur.

### Web Resource Is Replaced by URL Resource

The Web resource available in previous releases of WebLogic Server has been replaced by the URL resource. If you wrote a custom Authorization provider that uses the Web resource (instead of the URL resource), enable the Use Deprecated Web Resource attribute. This attribute changes the runtime behavior of the Servlet container to use a Web resource rather than a URL resource when performing authorization.

To use an existing Web resource:

1. Expand the Security Realms node.

All the security realms available for the WebLogic domain are listed in the Realms table.

2. In the Realms table, click the name of the desired security realm.
3. Select the General tab.
4. Check the Use Deprecated Web Resource attribute.
5. Reboot WebLogic Server.

### Keystores Are Supported

A new keystore implementation is available in WebLogic Server 8.1. The keystore retrieves trusted CAs, private keys, and server certificates from JDK keystores. The keystore implementation in WebLogic Server 8.1 offers several improvements:

- All JDK keystore types are supported. In WebLogic Server 7.x, only JKS keystores were supported.
- The keystore retrieves the server's certificate from a JDK keystore. In WebLogic Server 7.0, a server's certificate could only be retrieved from a file.
- Each server has its own keystore configuration.
- The keystore can be protected with a password to add another a layer of security to the WebLogic Server deployment.

By default, WebLogic Server has SSL enabled and the server's identity and trust is established with a demonstration certificate and demonstration and standard (JDK) certificate authorities.

### Custom Keystore Providers Are No Longer Supported

Custom Keystore providers cannot be used with this release of WebLogic Server. Private keys and trusted CAs should be stored in keystores associated with a particular instance of WebLogic Server. For more information about configuring a keystore for a server and loading private keys and trusted CAs into the keystore, see "Configuring Keystores and SSL" in the Security section of the Administration Console online help.

### The WebLogic Keystore Provider Is Deprecated

The WebLogic Keystore provider is deprecated in this release of WebLogic Server. If you are using the WebLogic Keystore provider to store private keys and trusted CAs, the server, when first booted with this release of WebLogic Server, will update the SSL MBean in the `config.xml` file to include the following attribute:

`IdentityAndTrustLocations=FilesorKeystoreProviders`

This attribute tells the server to use the 7.x SSL configuration rules instead of the new SSL rules. BEA recommends using this configuration only until you can upgrade to the keystores available in this release of WebLogic Server.

### Upgrading to WebLogic Server 8.1 Keystores

Storing identity (private keys and certificates) and trust (certificate authorities) in files is no longer supported. To upgrade to the keystores available in WebLogic Server 8.1:

1. Create a trust keystore. See Configuring Keystores in Managing WebLogic Security.
2. Load the trusted CAs into the keystore. Use the JDK `keytool` utility to perform this step.
3. Create an identity keystore. See Configuring Keystores in Managing WebLogic Security.
4. Load the private key and certificate into the keystore. Use the WebLogic Server `ImportPrivateKey` utility to perform this step. See ImportPrivateKey in the WebLogic Server Command Reference.
5. In the Administration Console, reconfigure SSL to use these trust and identity keystores. See Configuring Keystores and SSl in the Administration Console help.

### Upgrading to the WebLogic Server 8.1 Trust Mechanism for Java Clients

In WebLogic Server 7.0, Java clients (fat clients) retrieved trusted CAs from a jks keystore. The following command-line argument specified the pathname to the keystore:

`-Dweblogic.security.SSL.trustCAkeystore`

If the command-line argument was not specified, WebLogic Server defaulted to the trusted CAs in the JDK `jre/lib/security/cacerts` keystore.

The way Java clients retrieve trusted CAs has been improved in the following ways:

- All JDK keystore types are now supported. In WebLogic Server 7.x, only JKS keystores were supported.
- Keystore passwords can be specified.
- Clients can trust more types of certificate authorities. Command-line arguments specify whether to use standard trust (that is, cacerts in the JDK), demo trust (that is, cacerts in the JDK and the demo trusted CA provided by WebLogic Server), or custom trust.

This release of WebLogic Server still supports the trust command-line argument in WebLogic Server 7.0. As in WebLogic Server 7.0, WebLogic Server 8.1 defaults to the trusted CAs in the JDK `jre/lib/security/cacerts` keystore.

To upgrade to the new trust mechanism in this release of WebLogic Server, specify one of the following command-line arguments.

To trust the JDK standard trusted CAs, use:

`-Dweblogic.security.TrustKeystore=JavaStandardTrust`

To trust the JDK standard trusted CAs and the demo trusted CAs provided by WebLogic Server, use:

-`Dweblogic.security.TrustKeystore=DemoTrust`

To use a custom keystore, use:

`-Dweblogic.security.TrustKeystore=CustomTrust`

`-Dweblogic.security.CustomTrustKeystorePathname=``keystorepathname`

## URIs

Previous versions of WebLogic Server resolved URIs that contained extra spaces. WebLogic Server 8.1 no longer resolves extra spaces, and a URI request that contains extra spaces will result in a 404.

For example, `http://server:port/mywebapp/foo%20%20` formerly resolved to the resource `foo` in the Web application "mywebapp," but beginning with 8.1 it no longer does.

## Web Ap plications

- 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.
- It is no longer possible to use the Administration Console to define the default Web application. Define the default Web application by setting the `context-root` element in the application's `application.xml` file, if the application is part of an enterprise application, or the `weblogic.xml` file if it is a standalone Web application, to "/".
- Servlet Request and Response objects have a new API. Some serializable, lightweight implementations of these objects may no longer compile without implementing the new API. It is strongly recommended that you use the new Servlet 2.3 model and substitute your implementations of Servlet Request and Response objects.
- HTML Kona, marked deprecated in previous releases, has been removed.
- Five WebLogic-specific context parameters supported by the Web application container have been deprecated:

- `weblogic.httpd.servlet.reloadCheckSecs` (has been replaced with the `weblogic.xml` `servlet-reload-check-secs`).
- `weblogic.httpd.servlet.classpath` (instead use the manifest classpath, or WEB-INF/lib or WEB-INF/classes, or virtual directories).
- `weblogic.httpd.clientCertProxy` (not yet replaced in `weblogic.xml`).
- `weblogic.httpd.defaultServlet` (instead define a `servlet-mapping` with pattern=/ in `weblogic.xml`).
- `weblogic.httpd.inputCharset` (instead use `weblogic.xml` `charset-params`).

For more information about `weblogic.xml`, see weblogic.xml Deployment Descriptor Elements in Developing Web Applications for WebLogic Server.

## Web Services

When upgrading Web Services from WebLogic Server 7.0 to WebLogic Server 8.1, you will need to re-run `servicegen` to regenerate the Web Service deployment units.

For detailed information on upgrading a 7.0 WebLogic Web Service to 8.1, see Upgrading 7.0 WebLogic Web Services to 8.1 in Programming WebLogic Web Services.

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

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

## EJB 2.0

To see a complete listing of the specification changes, you can view and download the EJB 2.0 final specification at `http://java.sun.com/products/ejb/2.0.html`.

### Run DDConverter Before Using New Features

Before using any new EJB features in WebLogic Server 8.1, be sure to run the `DDConverter` tool to convert existing EJB deployment descriptors to 8.1 descriptors. For more information, see the discussion of the DDConverter tool.

### New Default Values for EJB Deployment Descriptor Elements

In WebLogic Server 8.1, there are new default values for the following EJB deployment descriptor elements:

The new default values are only in effect for deployment descriptors newly created or generated in WebLogic Server 8.1. Existing beans that use pre-8.1 versions of the deployment descriptors can be deployed on the 8.1 release with no change in behavior.

####

Table 2-2 Element Default Values

Element | Deployment Descriptor | New Default Value
--- | --- | ---
`enable-call-by-reference` | `weblogic-ejb-jar.xml` | `False`
`include-updates` | `weblogic-cmp-rdbms-jar.xml` | The default value is `False` for beans that use optimistic concurrency. The default value is `True` for beans that use other concurrency types, such as database.
`check-exists-on-method` | `weblogic-cmp-rdbms-jar.xml` | `True`

For more information on EJB deployment descriptors, see The weblogic-ejb-jar.xml Deployment Descriptor and The weblogic-cmp-rdbms-jar.xml Deployment Descriptor in Programming WebLogic Enterprise Java Beans.

### Inserting a New CMP Bean at Commit Time

In WebLogic Server 7.0, to have the EJB container perform bulk inserts, you set the `weblogic-cmp-rdbms-jar.xml` element `delay-database-insert-until` to `commit`.

As of the current release, the `commit` value is no longer supported for `delay-database-until-insert`. To permit bulk inserts, set the new `weblogic-cmp-rdbms-jar.xml` element `enable-batch-operations` to `true`.

`enable-batch-operations` takes effect on the jar level, so you need only set this tag once per jar. By contrast, `delay-database-insert-until` had to be set for every bean.

For more information on entity batch operations see Entity Batch Operations in Programming WebLogic Enterprise Java Beans.

## Writable config.xml File

WebLogic Server 8.1 automatically updates configuration information read from the 7.0 `config.xml` file to include WebLogic Server 8.1 information. In order for these changes to be retained between invocations of the 8.1 server, the `config.xml` file must be writable. If you have made your `config.xml` read-only, access its file properties and change the attribute so that it is writable. For example, in Windows, right-click the file in Windows Explorer, select Properties, and make sure that the Read-Only attribute is unchecked.