Upgrading WebLogic Server 6.x to Version 7.0

e-docs > WebLogic Server > WebLogic Server 7.0 Upgrade Guide > Upgrading WebLogic Server 6.x to Version 7.0

WebLogic Server 7.0 Upgrade Guide

Upgrading WebLogic Server 6.x to Version 7.0

Upgrading WebLogic Server 6.x to version 7.0, under the simplest circumstances, involves changing your WebLogic Server start command scripts and environment settings. In some cases, it is necessary to move your domain directory. Sometimes, upgrading requires 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 7.0:

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

For information on upgrading to WebLogic Platform 7.0 (7.0.0.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 7.0:

Make a backup copy of your 6.x domain before you begin the upgrade procedure. After you start the server using WebLogic Server 7.0 classes, you cannot downgrade to 6.x.
Install WebLogic Server 7.0. 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.
Modify your 6.x startup scripts to work with WebLogic Server 7.0. See Modifying Startup Scripts.
Ensure that you have considered differences in the WebLogic Server 7.0 directory structure that may require you to make file location changes before startup. See Understanding the WebLogic Server 7.0 Directory Structure.
Port your applications to WebLogic Server 7.0. See Porting an Application from WebLogic Server 6.x to WebLogic Server 7.0.
If necessary, perform other upgrade procedures as described in Upgrading Security, Upgrading WebLogic Tuxedo Connector, and 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 7.0 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 Previous WebLogic Server Releases 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 7.0.

Modify the startup scripts as described here. For another example of how to modify the startup scripts, see Upgrading the Pet Store Application and the Examples Server.

Modify the startup scripts as described here.

Modify bea.home property

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

-Dbea.home=C:\bea700
Modify WL_HOME

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

WL_HOME=c:\bea700\weblogic700
Modify PATH

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

PATH=%WL_HOME%\bin;%PATH%
Modify CLASSPATH

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

CLASSPATH=%WL_HOME%\lib\weblogic_sp.jar;%WL_HOME%\lib\weblogic.jar
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 7.0 installs the JVM, JDK 1.3.1_02, 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 7.0 Directory Structure

The directory structure in WebLogic Server 7.0 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 7.0 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.

Porting an Application from WebLogic Server 6.x to WebLogic Server 7.0

Note: Throughout this document, the directory of the new WebLogic Server 7.0 domain that is created is referred to as domain.

Use the following steps to port WebLogic 6.x applications on WebLogic Server 7.0:

If you have not already installed WebLogic Server 7.0, do so now. See the Installation Guide for more information.
Note: Installing the new version in the exact location of the old version is explicitly prohibited by the installer.
Each 6.x and 7.0 domain must have its own separate directory. It is not possible to have multiple config.xml files in the same directory.
1. For each 6.x configuration domain that you wish to port to WebLogic Server 7.0, copy the /config/domain directory to a directory location of your choice. Exclude any directories that begin with a dot ("."), which are files or directories that WebLogic Server has created for internal use.
  
  This directory is the location of your new domain and will contain all of your configuration information for that domain. If your 6.x config directory is not located in the WebLogic Server 6.x distribution, you may re-use your WebLogic 6.x configuration in WebLogic Server 7.0.
2. Identify deployment descriptor files (web.xml and weblogic.xml), because those files may contain file paths to items such as the Java compiler or external files. 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 reamainder 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 7.0 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 6.x Administration Console to configure the appropriate attribute to use the new file or utility before proceeding to the next step.
If you have not already edited the server start scripts, do so now. See Modifying Startup Scripts for instructions.
When you deploy applications to WebLogic Server 7.0, use the Administration Console or weblogic.Deployer utility to deploy using the new two-phase deployment protocol. The older, WebLogic Server 6.x deployment protocol, utilities, and API are deprecated in WebLogic Server 7.0

Note: WebLogic Server 7.0 will not deploy an application that has errors in its deployment descriptor. Previous versions of WebLogic Server would deploy an application that had errors in its deployment descriptor.

Upgrading Security

WebLogic Server 7.0 has a new security architecture. For specific questions and answers, see the security section of the Introduction to WebLogic Security.

WebLogic Server 7.0 detects whether you are upgrading from an earlier WebLogic Server version or whether you are a new customer starting with 7.0. If you are upgrading from WebLogic Server 6.x, WebLogic Server 7.0 runs in Compatibility security, meaning that it allows you to keep your 6.x configuration of users and groups.

However, because some key 6.x security functionality is being deprecated - and because WebLogic Server 7.0 offers improved and expanded security features - users are encouraged to upgrade their security configuration. See the following list of issues and procedures:

Note: The WebLogic Server 7.0 examples and PetStore are configured to use the default security configuration. It is not possible to run the WebLogic Server 7.0 examples and PetStore in Compatibility security.

Booting WebLogic Server in Compatibility Security

In previous releases of WebLogic Server, the File realm was configured by default. Therefore, WebLogic Server could use the File Realm to boot even if there was no security realm defined in the config.xml file. However, in order to run WebLogic Server in Compatibility security, you need to have either a File realm or an alternative security realm defined in your config.xml file. Otherwise, your server may not boot.

If you are unable to boot WebLogic Server in Compatibility security, copy SerializedSystemini.dat to your new domain folder and then do one of the following:

Boot your configuration under WebLogic Server 6.x, letting the server save the config.xml file, and then port the saved config.xml file to WebLogic Server 7.0.

Edit your 6.x config.xml file to include the following definitions:

<Security Name=mydomain Realm=mysecurity/>
<Realm Name=mysecurity FileRealm=myrealm/>
<FileRealm Name=myrealm/>

ACLs on MBeans

ACLs on MBeans are not supported in WebLogic Server 7.0. For information on protecting MBeans in WebLogic Server 7.0, see Protecting System Administration Operations in the Administration Guide.

Upgrading from Compatibility Security to WebLogic Server 7.0 Security

If you want to leverage the new security features in WebLogic Server 7.0, you need to upgrade your existing security realm to a WebLogic Server 7.0 security realm. You upgrade by populating the security providers in WebLogic Server 7.0 with your existing user and group information and defining security policies on resources that reflect the ACLs.

During successful booting of your WebLogic Server 6.x configuration, the Compatibility realm is created as the default security realm. The Compatibility realm contains all your 6.x security data. In addition, a default WebLogic Server 7.0 security realm called myrealm is also created. To upgrade, you need to replace the Compatibility realm with myrealm. From within the WebLogic Server Administration Console:

Click on the Realms node.

The Realms table appears with two security realms configured. The two security realms are the CompatibilityRealm and myrealm. The CompatibilityRealm will have the default attribute set to true.
Click on the myrealm node.
Click on the Providers tab to see the security providers configured for myrealm. By default, the WebLogic security providers are configured in myrealm.
Add a user that can boot WebLogic Server to the Administrators group. This user replaces the system user. To add a user to the Administrators group:
1. Click on the Security node.
2. Click on the Realms node.
3. Click on the name of the realm you are configuring (for example, myrealm).
4. Click on Groups.
  
  The Groups tab appears. This tab displays the names of all groups defined in the default Authentication provider.
5. Click on the Administrators group on the Groups tab.
6. Click the Membership tab to add the user who can boot WebLogic Server to the Administrators group.
7. Click the Apply button to save your changes.
Add the users and groups that you had configured in the 6.x security realm to an Authentication provider.
Optionally, define roles for your 6.x users and groups. See Securing WebLogic Resources.
Express 6.x ACLs as security policies. See Securing WebLogic Resources.
Set myrealm as the default security realm. See Setting the Default Security Realm in Managing WebLogic Security.
Reboot WebLogic Server.

Each time WebLogic Server is booted and the server is deployed, the roles and security policies are applied. Subsequent access to the server and its methods are constrained by these roles and security policies until they are changed.

Security Realms

The scope of security realms changed in WebLogic Server 7.0. In WebLogic Server 6.x, security realms provided authentication and authorization services. You chose from the File realm or a set of alternative security realms including the Lightweight Data Access Protocol (LDAP), Windows NT, UNIX or RDBMS realms. In addition, you could write a custom security realm.

In WebLogic Server 7.0, security realms act as a scoping mechanism. Each realm consists of a set of configured security providers, users, groups, roles, and security policies. Authentication and Authorization providers within a security realm offer authentication and authorization services.

You have the following choices when upgrading a 6.x security realm to WebLogic Server 7.0:

Use Compatibility security to access the users, groups, and ACLs configured in an LDAP, Windows NT, UNIX, RDBMS, or custom security realm. The Realm Adapter Authentication provider in the Compatibility realm can access users, groups, and ACLs stored in a 6.x security realm.

For information about using Compatibility security, see Booting WebLogic Server in Compatibility Security.
Use the Realm Adapter Authentication provider with the WebLogic Server 7.0 security providers. This option allows you to use the roles and security policies available in WebLogic Server 7.0 while accessing users and groups stored in an LDAP, Windows NT, UNIX or RDBMS security realm. You also have the option of configuring multiple Authentication providers so you can use your existing 6.x security realm while upgrading users and groups to an Authentication provider in WebLogic Server 7.0.

Note: You will not be able to access ACLs stored in the RDBMS realm, if you configure the Realm Adapter Authentication provider as an authentication provider in a 7.0 security realm. You will have to protect your application resources with roles and security policies.

To use the Realm Adapter Authentication provider in a WebLogic 7.0 security realm:

Boot Compatibility security.
Ensure that the Realm Adapter Authentication provider in the Compatibility realm is populated with users and groups from your 6.x security realm (check that existing users and groups appear in the Users and Groups table). The user and group information is copied into a filerealm.properties file.
Click on security realm in which you want to use the Realm Adapter Authentication provider (for example, myrealm).
Click Providers-->Authentication providers.
Configure a Realm Adapter Authentication provider in the security realm. Give the Realm Adapter Authentication provider the same name it had in the Compatibility realm.
Set the Control Flag attribute on the Realm Adapter Authentication provider to OPTIONAL.
Set the Control Flag attribute on the WebLogic Authentication provider (referred to as the Default Authenticator in the Administration Console) to SUFFICIENT.
Add a user that can boot WebLogic Server to the Administrators group. This user replaces the system user. For more information, see Upgrading from Compatibility Security to WebLogic Server 7.0 Security.
Reboot WebLogic Server.
Expand the Domains-->Security nodes.
Select the General tab.
Set the security realm in which you configured the Realm Adapter Authentication provider as the default security realm.
Click Apply.

Note: ACLs cannot be upgraded to WebLogic Server 7.0.

Guest User

The guest user is no longer supplied by default in WebLogic Server 7.0. To use the guest user, you must run in Compatibility security or define the guest user as a user in the default Authentication provider for your security realm. For information about defining users, see "Creating Users" in Securing WebLogic Resources.

In WebLogic Server 6.x, the guest user identified any unauthenticated user (anonymous user) as a guest user and allowed the guest user access to WebLogic Server resources. In 7.0, WebLogic Server distinguishes between the guest user and an anonymous user. To use the guest user as you did in WebLogic Server 6.x, add the guest user to the default Authentication provider and set the following property when starting WebLogic Server:

-Dweblogic.security.anonymousUserName=guest

Without this command line property, the anonymous user will have the name of <anonymous>.

password.ini File

Previous releases of WebLogic Server supported the use of a password.ini file for determining the administrative identity of a WebLogic Server deployment. The password.ini file is no longer supported in WebLogic Server 7.0. It is replaced by the boot.properties file, which contains your username and password in an encrypted format. For more information about using the boot.properties file, see Creating a Boot Identity File in the Administration Guide. There is no direct upgrade of the old password.ini file because it contained a clear text password and no username.

Upgrading the SSL Protocol

This section contains information on how to upgrade the SSL protocol including instructions for creating a trusted CA Keystore, creating a private key Keystore, and using a CertAuthenticator in Compatibility security.

Creating a Trusted CA Keystore

By default in WebLogic Server 7.0, clients check the server's trusted certificate authority. This check is done whenever a client and server connect using SSL, including when WebLogic Server is acting an a client. For example, when a client is using the SSL protocol to connect to an Apache HTTP Server, the client checks the trusted certificate authorities presented by the server. The client rejects the server's trusted certificate authority if the certificate authority is not trusted by the client. Previous versions of WebLogic Server did not perform this trust validation.

Make the following changes to allow an existing 6.x WebLogic client to use SSL protocol to communicate with a server:

Specify the following command-line argument for the client:

-Dweblogic.security.SSL.trustedCAKeyStore=absoluteFilename

where absoluteFilename is the name of the keystore that contains the trusted certificate authority

Note: The file format is a keystore NOT a certificate file. The trusted certificate authority must be loaded into the keystore.

Load the server's trusted certificate authority into the client keystore. To list trusted certificate authorites in the keystore or to load new trusted certificate authorities into the keystore, use the JDK keytool utility.
To add a trusted certificate authority to a keystore, enter the following at a command prompt:
```
keytool -import -trustcacerts -alias <some alias name> -file <the
file that contains the trusted CA> -keystore <the trusted CA keystore>
-storepass <your trusted CA Keystore password>
```
The trusted certificate authority shipped with WebLogic Server is located in WL_HOME/server/lib/cacerts. Use the following command to add the trusted certificate authority that is shipped with WebLogic Server to a keystore:
```
keytool -import -trustcacerts -alias <some alias name> -file <the
file that contains the trusted CA> -keystore WL_HOME/server/lib/cacerts
-storepass changeit
```

For more information about keytool, see SUN's website at http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/keytool.html.

The trustedCAKeyStore command-line argument defaults to the JDK's jre/lib/security/cacerts keystore for clients. You can add your CAs to the JDK's trusted CA keystore and not specify the command-line argument, or you can create your own trusted CA keystore and point to it with the argument.

For two-way SSL or mutual authentication, in addition to performing the previous two steps on the client side, do either of the following steps on the server side:

Add -Dweblogic.security.SSL.trustedCAKeyStore=absoluteFilename to the server command line.

where absoluteFilename is the name of the trusted CA Keystore

OR
Set the RootCAKeyStoreLocation attribute when configuring a Keystore provider.

If you do not load the trusted CA certificate into the trusted CA Keystore, you may have problems using the secure port.

Using CertAuthenticator in Compatibility Security

In WebLogic Server 7.0, the CertAuthenticator is called first, before any username/password authentication. Because this is a change in behavior from WebLogic Server 6.x, a CertAuthenticator written for WebLogic Server 6.x may need to change if clients used both two-way SSL and they supplied a username and password for security credentials.

Using a CertAuthenticator that needs to be changed may result in access being denied in WebLogic Server 7.0, but allowed in WebLogic Server 6.x. To change the CertAuthenticator, have it return NULL for unrecognized certs, or for all certs, if certs are only being used to make an SSL connection.

In WebLogic Server 7.0, X.509 Identity Assertion is turned off by default. If your WebLogic Server 6.x config.xml file used a CertAuthenticator you need to manually configure the X.509 identity assertion when using Compatibility security. You enable X.509 identity assertion by configuring options on the Realm Adapter Authentication provider. In the WebLogic Server Administration Console while running in Compatibility security:

Click on the Security node.
Click on the Realms node.
Click on the CompatibilityRealm node.
Click on the Providers node.
Click on the Authentication Providers node.
Click on the RealmAdapterAuthenticator node.

The General tab appears.
Enter X.509 in the Active Types box.
Click Apply to save your change.
Reboot the WebLogic Server.

Cipher Suites

If you have trouble with your Certicom cipher suite, see the information about issue 073360 in the Release Notes.

Upgrading WebLogic Tuxedo Connector

You must make the following application and configuration changes to use WebLogic Tuxedo Connector in WebLogic Server 7.0:

Start the WebLogic Tuxedo Connector

Note: For more information on how to configure WebLogic Tuxedo Connector, see Configuring WebLogic Tuxedo Connector Using the Administration Console.

Previous releases of the connector used a WebLogic Server Startup class to start a WebLogic Tuxedo Connector session and a WebLogic Server Shutdown class to end a session. In WebLogic Server 7.0, WebLogic Tuxedo Connector does not use a Startup or a Shutdown class. WebLogic Tuxedo Connector sessions are managed using a WTCServer MBean.

You start a WebLogic Tuxedo Connector session when you assign a configured WTCServer MBean to a selected server.
You end a WebLogic Tuxedo Connector session by removing a WTCServer MBean from WebLogic Server or when you shut down WebLogic Server.

For more information on starting and ending a WebLogic Tuxedo Connector session, see Assign a WTCServer to a Server.

Convert WebLogic Tuxedo Connector XML Configuration Files

WebLogic Tuxedo Connector is implemented as a service and no longer utilizes a separate XML configuration file. The WTCMigrateCF tool migrates XML configuration file information into the config.xml file of an active Administration server. Use the following steps to convert your WebLogic Tuxedo Connector XML configuration file:

Set up a WebLogic Server development shell as described in Setting Up your environment.
Start an instance of WebLogic Server.
Open a new shell window.

Start the WTCMigrateCF tool. Enter the following command:

java -Dweblogic.wtc.migrateDebug weblogic.wtc.gwt.WTCMigrateCF
-url URL -username USERNAME -password PASSWORD -infile CONFIGWTC
[-server SERVERNAME] [-domain DOMAIN] [-protocol PROTOCOL]
[-deploy]

The arguments for this command are defined as follows:

Argument	Description
-Dweblogic.wtc.migrateDebug	WebLogic property used to turn on wtc.migrateDebug mode.
URL	URL passed to your server. Example: \\myServer:7001
USERNAME	User Name passed to your server. Example: system
PASSWORD	Password passed to your server. Example: mypasswd
CONFIGWTC	Fully qualified path and name of the WebLogic Tuxedo Connector XML configuration file to migrate to the config.xml file. Example: d:\bea\weblogic700\server\samples\examples\wtc\atmi\simpapp\bdmconfig.xml
SERVERNAME	Optional. The name of the administration or managed server that you want the new WTCServer MBean assigned to. Default: the current active administration server.
DOMAIN	Optional. The name of the WebLogic Server domain that you want the new WTCServer MBean assigned to. Default: the current active domain.
PROTOCOL	Optional. The protocol to use with URL. Default: t3:
-deploy	Optional. Use to target the WTCServer MBean to a selected server. If this flag is set, a WebLogic Tuxedo Connector session is immediately started to provide the services specified by the WTCServer MBean is immediately started.

When the migration is complete, the migration utility displays:

The WTC configuration file migration is done!
No error found!!!

The information from the specified XML configuration file is migrated to a WTCServer Mbean and placed in the config.xml file of the server specified in step 2.

Update Inbound RMI-IIOP Applications

For more information on how to use inbound RMI-IIOP with the WebLogic Tuxedo Connector, see Using WebLogic Tuxedo Connector for RMI-IIOP.

If you use inbound RMI-IIOP, you must modify the reference object that connects WebLogic Tuxedo Connector instances to Tuxedo CORBA applications. Tuxedo CORBA objects now use the server name to reference remote WebLogic Tuxedo Connector objects. Earlier releases used the DOMAINID.

Modify the corbaloc:tgiop or corbaname:tgiop object reference in your ior.txt file.
Example: corbaloc:tgiop:servername/NameService

where servername is your server name
Register the WebLogic Server (WLS) Naming Service by entering the following command:
cnsbind -o ior.txt your_bind_name

where your_bind_name is the object name from your Tuxedo application.
Modify the *DM_REMOTE_SERVICES section of your Tuxedo domain configuration file. Replace your WebLogic Server service name, formerly the DOMAINID, with the name of your WebLogic Server.

Listing 1-1 Domain Configuration File

*DM_RESOURCES
     VERSION=U22

*DM_LOCAL_DOMAINS
     TDOM1 	GWGRP=SYS_GRP
     TYPE=TDOMAIN
     DOMAINID="TDOM1"
     BLOCKTIME=20 
     MAXDATALEN=56 
     MAXRDOM=89 

*DM_REMOTE_DOMAINS
     TDOM2 TYPE=TDOMAIN
     DOMAINID="TDOM2"

*DM_TDOMAIN
     TDOM1 NWADDR="<network address of Tuxedo domain:port>"
     TDOM2 NWADDR="<network address of WTC domain:port>"

*DM_REMOTE_SERVICES
"//servername"

where servername is the name of your WebLogic Server.

Load your modified domain configuration file using dmloadcf.

You are now ready to start your applications.

Authenticate Remote Users

For more information, see User Authentication.

WebLogic Tuxedo Connector uses Access Control Lists (ACLs) limit the access to local services within a local domain by restricting the remote domains that can execute these services. The valid values for this parameter are:

LOCAL
GLOBAL

ACL Policy is LOCAL

If the WebLogic Tuxedo Connector ACL Policy is set to Local, the Tuxedo remote domain DOMAINID must be authenticated as a local user. To allow WebLogic Tuxedo Connector to authenticate a DOMAINID as a local user, use the WebLogic Server Console to complete the following steps:

Click on the Security node.
Click on Realms.
Select your default security Realm.
Click on Users.
Click the Configure a new User text link.
Click DefaultAuthenticator
In the General tab, do the following:
1. Add the Tuxedo DOMAINID in the Name field.
2. Enter and validate a password.
3. Click Apply.

ACL Policy is Global

If the WebLogic Tuxedo Connector ACL Policy is GLOBAL, the user's security token is passed. No administration changes are required.

Set WebLogic Tuxedo Connector Properties

Note: For more information on how to set WebLogic Tuxedo Connector properties, see How to Set WebLogic Tuxedo Connector Properties.

TraceLevel and PasswordKey are now WebLogic Server properties.

To monitor the WebLogic Tuxedo Connector using the WebLogic Server log file, you must set the tracing level using the WebLogic Server TraceLevel property. For more information, see Monitoring the WebLogic Tuxedo Connector .

-Dweblogic.wtc.TraceLevel=tracelevel
where tracelevel is a number between 10,000 and 100,000 that specifies the level of WebLogic Tuxedo Connector tracing.

To generate passwords using the weblogic.wtc.gwt.genpasswd utility, you must set a password key using the WebLogic Server PasswordKey property. For more information on how to generate passwords, see Configuring a WTCPassword MBean .

-Dweblogic.wtc.PasswordKey=mykey
where mykey is the key value.

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 7.0.

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

ant.jar

If you are going to develop new ant tasks, you must manually add the server/lib/ant.jar file to your classpath.

Apache Xalan XML Transformer

The built-in transformer in WebLogic Server 7.0 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 7.0 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 7.0 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.

Applications Directory

In WebLogic Server 6.1 and 7.0 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. Note that in WebLogic Server 6.1 and 7.0 the default domain (mydomain) and Pet Store configurations are shipped in production mode. The examples configuration is shipped in development mode.

Deployment

WebLogic Server 7.0 provides a new two-phase deployment model. For more information on this deployment model and other 7.0 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 7.0 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 7.0 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 7.0, 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 are deprecated in 7.0.

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 7.0, and somewhat between WebLogic Server 6.1 and WebLogic Server 7.0.

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 7.0, 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 7.0 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 7.0, 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 7.0:
- In 7.0, 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 7.0, 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 7.0, 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 7.0, 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 7.0.

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.
Remote relationships do not exist in 6.1 and 7.0.
The new implementation of read-only beans in WebLogic 7.0 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 WebLogic 7.0 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 7.0, 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 port from WebLogic Server 6.0 to 7.0.

max-beans-in-cache Parameter

In WebLogic Server 7.0 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 7.0, 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 7.0 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 7.0 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
```

jCO M

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

JDBC

The minimum capacity increment for a JDBC connection pool has changed from 0, in WebLogic Server 6.1, to 1, in version 7.0. See JDBCConnectionPool in the WebLogic Server Configuration Reference.

The default value for PreparedStatementCacheSize and XAPreparedStatementCacheSize in the JDBC Connection Pool MBean has increased from 0 in WebLogic Server 6.1 to 5 in WebLogic Server 7.0SP2 and later releases. For more information about the Prepared Statement Cache and its limitations, see "Increasing Performance with the Prepared Statement Cache" in the Administration Guide.

JMS

WebLogic Server 7.0 supports the JavaSoft JMS specification version 1.0.2.

All WebLogic JMS 6.x applications are supported in WebLogic JMS 7.0. 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 7.0. 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 7.0. 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 a change in the JSP specification, null request attributes now return the string "null" instead of an empty string. WebLogic Server versions since 6.1 contain a new flag in weblogic.xml called printNulls which is true by default, meaning that "null" will be the default. Setting this to false ensures that expressions with "null" results are printed as an empty string, not the string "null."

An example of configuring the printNulls element in weblogic.xml :

<weblogic-web-app>

<jsp-param>

<param-name>printNulls</param-name>

<param-value>false</param-value>

</jsp-param>

</weblogic-web-app>

Load Order for Startup Classes

The behavior of LoadBeforeAppDeployments in StartupClassMbean has changed between versions 6.x and 7.0 Service Pack 2.

LoadBeforeAppDeployments still exists in version 7.0 Service Pack 2, but its behavior has changed. In 6.x, setting LoadBeforeAppDeployments to true caused startup classes to be invoked after the datasources were created and before the applications were activated. In 7.0 Service Pack 2, it determines whether a startup class is loaded and run before the server activates JMS and JDBC services or deploys applications and EJBs.

Managed Servers

A Managed Server running WebLogic Server 6.x cannot obtain its configuration and boot using an Administration Server running WebLogic Server 7.0. 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 7.0 installation directory.

MBean API Change

Previous versions of this document and various other sample documents erroneously described using weblogic.management.Admin.getInstance().getAdminMBeanHome() as a way to look up the MBeanHome interface on the Administration Server.

However, the weblogic.management.Admin class is not public. Instead of using this non-public class, use JNDI to retrieve MBeanHome. See Determining the Active Domain and Servers in Programming WebLogic Server JMX Services.

Security

Guest and <Anonymous> Users

In WebLogic Server 6.x, any unauthenticated user (anonymous user) was identified as a user called guest. WebLogic Server allowed the guest user access to WebLogic resources. However, this functionality presented a potential security risk so the functionality was modified.

In this version of WebLogic Server, the guest user is no longer supplied by default. WebLogic Server now distinguishes between the guest user and an anonymous user, by assigning an anonymous user the name <anonymous>.

If you want to use the guest user as you did in WebLogic Server 6.x, do one of the following:

Use Compatibility security. (For more information, see "Using Compatibility Security" in Managing WebLogic Security.)
Define the guest user as a user in the WebLogic Authentication provider. (The WebLogic Authentication provider is already configured in the default security realm.) You do this by setting the following argument when starting a WebLogic Server instance:
```
-Dweblogic.security.anonymousUserName=guest
```

Caution: This argument was added to assist existing WebLogic Server customers to upgrade their security functionality. You should take great caution when using the guest user in a production environment. For more information about upgrading, see "Upgrading Security"in the Upgrade Guide for BEA WebLogic Server 7.0.

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 7.0 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 Ap plications

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. 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 new 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 7.0 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 7.0 of WebLogic Server, you must upgrade Web services created in version 6.1 to run on version 7.0.

The WebLogic Web services client API included in WebLogic Server 6.1 of has been deprecated and you cannot use it to invoke 7.0 Web services. WebLogic Server 7.0 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 7.0, see Upgrading 6.1 WebLogic Web Services to 7.0.

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 7.0 Web services, see Overview of WebLogic Web Services.

Writable config.xml File

WebLogic Server 7.0 automatically updates configuration information read from the 6.x config.xml file to include WebLogic Server 7.0 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 7.0. It is replaced by JavaWebStart.
WebLogic Enterprise Connectivity (WLEC) is deprecated in this release of WebLogic Server 7.0. 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 7.0 and has been replaced by weblogic.Deployer. For more information, see Deployment Tools and Procedures in WebLogic Server Deployment.
This version of WebLogic Server deprecates deploying multiple J2EE modules without an application.xml file. If you select a directory for deployment, the directory must contain either one standalone J2EE module (an EJB, Web Application, or Resource Adapter), or multiple modules with an associated application.xml file (an Enterprise Application).
This release provides a standard method for resource adapter deployers to plug in their specified authorization/authentication mechanism through secure password credential storage. This WebLogic Server storage mechanism has replaced the Security Principal Mapping mechanism provided with the weblogic-ra.xml deployment descriptor within the resource adapter archive. As a result, the element has been deprecated.
The Password Converter Tool provided with the previous release of WebLogic Server has been deprecated.
The <connection-cleanup-frequency> and <connection-duration-time> elements in the weblogic-ra.xml deployment descriptor have been deprecated in favor of a new connection leak detection mechanism.
WebLogic Server 7.0 deprecates the single-phase deployment model used in WebLogic Server 6.x. All WebLogic 6.x deployment protocol APIs and tools are now deprecated and should not be used for deploying production applications. Instead, use the new two-phase deployment protocol APIs and tools described in the WebLogic Server 7.0 documentation.
The WebLogic jDriver for Microsoft SQL Server is deprecated and will be removed from a future release of WebLogic Server. BEA recommends that you use the JDBC driver available from Microsoft to connect to a Microsoft SQL Server database. See "Installing and Using the SQL Server 2000 Driver for JDBC from Microsoft" in Programming WebLogic JDBC.
The WebLogic Keystore provider is deprecated in WebLogic Server 7.0 SP1.
weblogic.management.tools.WebAppComponentRefreshTool and weblogic.refresh are both deprecated in this release of WebLogic Server 7.0. They have been replaced by weblogic.Deployer.
WebLogic JDBC t3 Driver. See Deprecation of WebLogic File Services.
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 7.0 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.