3 Upgrading the Middle Tier

3.6.1.1 Source Oracle Home Not Provided by OracleAS Upgrade Assistant

If the source Oracle home does not appear as expected in the drop-down list of the Oracle Homes screen when you execute the OracleAS Upgrade Assistant, suspect one of these conditions: wrong installation type, Oracle homes are on different computers, or the Oracle home is not identified in the default inventory. The solution for each of these is detailed below.

The source Oracle home will not appear if the source middle tier instance is not of the same installation type as the destination middle tier instance. If this is the case, you must do one of the following:

• Expand the installation type, as described in "Expanding the Middle Tier Installation Type".

• Reinstall the destination middle tier with the same installation type as the source middle tier.

Another case in which the source middle tier will not appear as a selection is that the source middle tier instance is installed on a different computer from the destination middle tier instance. If this is the case, you must install the destination middle tier instance on the same computer as the source instance to be upgraded.

The OracleAS Upgrade Assistant uses the default inventory location to populate the drop-down list in the Oracle Homes screen. If the source Oracle home is not listed in the default Oracle Universal Installer inventory, then you need to provide the inventory file location to the OracleAS Upgrade Assistant. Start the OracleAS Upgrade Assistant with the -invptrloc option, described in Section 3.5.3, "Starting the OracleAS Upgrade Assistant To Use Multiple Oracle Universal Installer Inventory Locations" to specify the inventory location.

3.6.1.2 Upgrade Fails During OPMN, OC4J, or Oracle HTTP Server Upgrade

If the upgrade fails during the OPMN, OC4J or Oracle HTTP Server upgrade, it is probably because OPMN is still running in one or both instances (source and destination). You must stop OPMN before starting the OracleAS Upgrade Assistant. Follow the instructions in Section 3.1.2, "Stopping Oracle Application Server Instances".

3.6.1.3 Upgrade Fails During OC4J Examination or Other Phase

If the upgrade fails during the OC4J examination phase, or another phase, it is probably because the Infrastructure is unavailable. The OracleAS Upgrade Assistant needs the Infrastructure services for certain operations, so the Infrastructure must be started before you start the OracleAS Upgrade Assistant. Follow the instructions in Section 3.5.2, "Starting the Infrastructure".

3.6.1.4 Upgrade Fails During Extensive OC4J Upgrade

If the upgrade fails while attempting to upgrade many OC4J applications, or large OC4J applications, suspect a memory shortage. You can configure a memory increase for the upgrade operation. Follow the instructions in Section 3.2.2, "Optional: Increasing JVM Memory for Large OC4J Upgrades".

3.6.2.1 Recovering From Examination Failures

To determine the cause of an examination failure:

1. Note the name of the failed component in the OracleAS Upgrade Assistant dialog or command-line output.

2. Open <destination_MT_OH>/upgrade/log/iasua.log.

3. Search for the message Starting to examine component_name.

4. Investigate the messages between the Starting... message and the message Finished examining component_name with status: Failure.

3.6.2.2 Recovering From Upgrade Failures

To determine the cause of an upgrade failure:

1. Note the name of the failed component in the OracleAS Upgrade Assistant dialog or command-line output.

2. Open <destination_MT_OH>/upgrade/log/iasua.log.

3. Search for the message Starting to upgrade component_name.

4. Investigate the messages between the Starting... message and the message Finished upgrading component_name with status: Failure.

3.6.3.1 Configuration Change Requirements

If a configuration does not perform as expected after an upgrade, it might be because configuration changes were made to OC4J application files by means other than the Oracle Enterprise Manager Application Server Control. Only the changes made by the Oracle Enterprise Manager Application Server Control will be included in the OC4J upgrade performed by the OracleAS Upgrade Assistant. Manually edited files may not be in the scope of the managed configuration, and the edits may not be preserved in an upgrade.

If you use Distributed Configuration Management’s dcmctl utility to perform configuration changes, see the Distributed Configuration Management Reference Guide for instructions and a complete discussion on the correct usage of the commands.

3.6.3.2 Application Deployment and J2EE Compliance Requirements

OC4J deployment enforces J2EE compliance rules, so the OracleAS Upgrade Assistant may not upgrade applications that are not fully J2EE compliant. The OracleAS Upgrade Assistant simply reads the files in the source Oracle home and attempts to deploy them to the destination Oracle home; if deployment fails, it could be because an application is not J2EE compliant. If the OracleAS Upgrade Assistant cannot deploy an application for any reason, it logs the exception in the <destination_MT_OH>/upgrade/log/iasua.log. The exception may not be explicitly described as a J2EE compliance issue, but that may be the reason for the failure. Knowledge of the J2EE and EJB specifications, and the EJB features used in applications will be helpful in preventing and troubleshooting deployment failures (10g (9.0.4) supports a higher version of the EJB specification than Release 2 (9.0.2)).

While the development of J2EE applications is standardized and portable, the XML configuration files are not. Multiple XML files may need to be configured for an OC4J application to be deployed, and the required configuration varies according to the services the application uses. For example, if the application uses a database, the DataSource object in the data-sources.xml file must be configured.

dcmctl validateEarFile -v -f simple.ear
No J2EE XML/DTD validation errors were found

dcmctl validateEarFile -v -f petstore.ear
Warning: J2EE/DTD validation errors were found
ADMN-906001   {0}   Base Exception:   oracle.ias.sysmgmt.deployment.j2ee.exception.J2eeDeploymentException:Cannot get xml   document by parsing /var/tmp/jar50152.tmp: Invalid element 'servlet' in content of 'web-app',   expected elements '[servlet-mapping, session-config, mime-mapping, welcome-file-list,   error-page, taglib, resource-ref, security-constraint, login-config, security-role, env-entry,   ejb-ref]'.

3.8.1.1 Manual Upgrade Tasks You May Need to Perform

The OracleAS Upgrade Assistant upgrades the standard settings for the Oracle HTTP Server. If you have configuration files or documents that are in non-standard locations or referenced in non-standard ways, you must upgrade these manually. These, and other specific cases for manual upgrade, are detailed below.

• If you want the Oracle HTTP Server to listen on a port numbered lower than 1024: The HTTP server executable apachectl must have root user privileges to bind to ports numbered lower than 1024. Follow these steps to grant root privileges to the executable:

  1. Log in to the root account.

  2. Navigate to <destination_MT_OH>/Apache/Apache/bin and issue these commands:

     chown root .apachectl

     chmod 6750 .apachectl

  3. Exit the root account.

• If mod_osso was configured: If mod_osso was configured, after upgrade, the osso.conf file continues to use the Release 2 (9.0.2) partner entry in the Single Sign-On server. The 10g (9.0.4) partner entry in the Single Sign-On server is not being used, and will cause a broken link (invalid URL) when the application logs out. You should remove the 10g (9.0.4) partner entry. In addition, if the name of the entry in use is obsolete (in that it refers in some way to the source Oracle home), you may wish to rename it.

• If there are configuration files in non-default locations: If httpd.conf, mod_oc4j.conf, mod_osso.conf and moddav.conf files are not in the default location, you must upgrade them manually by applying the customizations in the files in the source Oracle home to the files in the destination Oracle home.

• If there are custom files and directories referenced by Oracle HTTP Server configuration files: Because the OracleAS Upgrade Assistant only upgrades the items listed in Section A.1.4.1, "OHS Upgrade Items", there could be files or directories referred to by directives such as Alias, mod_rewrite, and log directives, such as ErrorLog, that are not present after the upgrade. Ensure that all such items are upgraded manually and exist in the locations expected by the directives. If these files or directives are missing after the upgrade, the Oracle HTTP Server may not start. You can identify errors by starting the Oracle HTTP Server individually after the upgrade, and examining the <destination_MT_OH>/Apache/Apache/logs/error_log for errors associated with these items.

• If there are Dynamic Monitoring Service (DMS) configuration elements in the httpd.conf and mod_oc4j.conf files: You must relocate these configuration elements into the dms.conf file.

• If Oracle Application Server Web Cache is the first listener: If OracleAS Web Cache is configured as the first listener, ensure that the Oracle HTTP Server directives listed in Table 3-5 have the same values as the corresponding OracleAS Web Cache elements. In particular, note that the Oracle HTTP Server Port directive specifies the port number of a front-end load balancer or reverse proxy. Thus, if Oracle Application Server Web Cache is used, then the Oracle HTTP Server Port directive should have the value of the port on which OracleAS Web Cache is listening.

  Table 3-5 Oracle HTTP Server and Oracle Application Server Web Cache Port Settings

  Oracle HTTP Server Directive	Oracle Application Server Web Cache Element
  VirtualHost	Site definitions
  Listen	Origin server ports
  VirtualHost, Listen	Site-to-server mappings
  Port	Listen

  
  

• If you have static documents in the default DocumentRoot directory that you want to upgrade: The OracleAS Upgrade Assistant locates static document files and directories for upgrade in the location specified in the DocumentRoot directive. The DocumentRoot directive defines the location for static documents and related directories. The base server has a document root location, and each virtual host has one. The OracleAS Upgrade Assistant copies files under these directories to the destination Oracle home. The default DocumentRoot directory <source_MT_OH>/Apache/Apache/htdocs contains demonstration programs and release notes placed there by the installer, so the OracleAS Upgrade Assistant does not upgrade this directory. You must upgrade this directory manually.

3.8.2.1 Upgrading Oracle Application Server Java Authentication and Authorization Service (JAZN) LDAP Security Settings

The OracleAS Upgrade Assistant does not upgrade the JAZN settings (the orion-application.xml file). Therefore, if you upgraded OC4J applications that use the JAZN LDAP User Manager for security, to complete the upgrade, you must perform the following steps:

1. Using the Oracle Enterprise Manager Application Server Control, in the General Properties section of the OC4J application, under User Manager, select the JAZN LDAP User Manager.

2. In the Security Settings section of the OC4J application, under Security Roles, map Users/Groups to the same role defined in the source Oracle home.

3.8.2.2 Upgrading JAZN Library Path Entries

In Oracle Application Server 10g (9.0.4), the jazn.jar file has been split into two JAR files: jazn.jar and jazncore.jar. For this reason, after upgrading OC4J applications that use JAZN, both JAR file names must have library path entries in the application.xml file.

Ensure that the application.xml file contains both of the entries below:

<library path="904 J2EE HOME/jazn.jar"/>

<library path="904 J2EE HOME/jazncore.jar"/>

where

<904 J2EE HOME> = <destination_MT_OH>/j2ee/home

3.8.2.3 Upgrading OC4J Instances Created by the Installer

Customizations that were made to OC4J instances in the opmn.xml file must be upgraded manually. This includes the instances created by the installer (home, OC4J_WIRELESS, OC4J_DEMOS, OC4J_PORTAL OC4J_BI_FORMS). The OracleAS Upgrade Assistant upgrades customizations to OC4J instances that were created by the user.

3.8.2.4 Upgrading application.xml Entries

If you have customized entries in the application.xml file, such as library paths, Java options, and OC4J options, you must upgrade them manually.

3.8.2.5 Upgrading the jms.xml File

The jms.xml file is not automatically upgraded from earlier versions. All queues, topics, and connection factories defined in the jms.xml file in the source Oracle home must be added to the jms.xml file in the destination Oracle home.

3.8.2.6 Using the Compatibility Test Suite (CTS) Compatibility Flag for Backward Compatibility

In Oracle Application Server 10g (9.0.4), OC4J by default complies with the J2EE 1.3 specification. In some cases, this results in behavior that differs from that seen with previous OC4J implementations. To allow for backward compatibility, OC4J supports a CTS compliance flag that you can set to false to revert to previous OC4J behavior in the following components:

• Oracle JMS

• Oracle JDBC

• Oracle XML parser for JAXP/XDK

The compliance behavior of OC4J is determined by the flag oracle.cts.useCtsFlags, with a default value of true. If any of the upgrade issues are critical in a particular application, you can disable CTS compliance and revert to old behavior for an OC4J instance by setting the flag value to false in an OC4J properties file, and providing the location of the properties file to OC4J.

For example, the file <destination_MT_OH>/j2ee/home/config/oc4j.properties might contain the flag:

oracle.cts.useCtsFlags=false

Supply the name and location of a properties file to OC4J through an <oc4j-option> element in the <destination_MT_OH>/opmn/conf/opmn.xml file, as in the following example:

<oc4j>
...
 <oc4j-option value="-p <destination_MT_OH>/j2ee/home/config/oc4j.properties"/>
...
</oc4j>

This is equivalent to starting OC4J as follows in standalone mode (where % is a system prompt):

% java -jar oc4j.jar -p <destination_MT_OH>/j2ee/home/config/oc4j.properties 

3.8.2.7 Upgrade Considerations for Enterprise Java Beans

Beginning with Oracle9iAS Release 2 (9.0.3), Oracle Application Server Containers for J2EE complies with the J2EE 1.3 specification and implements the Enterprise Java Beans (EJB) 2.0 specification in entirety. Therefore, if you are upgrading from Release 2 (9.0.2) to 10g (9.0.4), applications using EJB features in the areas of container-managed persistence and container-managed relationships will require modification.

3.8.2.8 Upgrade Considerations for the OC4J Java Server Pages (JSP) Container

This section describes JSP settings that are affected by the upgrade.

<servlet>
   <servlet-name>jsp</servlet-name>
   <servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class>
   <init-param>
      <param-name>check_page_scope</param-name>
      <param-value>true</param-value>
   </init-param>
   ...
</servlet>

3.8.2.9 Considering JDK 1.4 Issues: Cannot Invoke Classes Not in Packages

Among the migration considerations in moving to a Sun Microsystems JDK 1.4 environment, which is the environment that is shipped with Oracle Application Server 10g (9.0.4), there is one of particular importance to servlet and JSP developers.

As stated by Sun Microsystems, "The compiler now rejects import statements that import a type from the unnamed namespace." (This was to address security concerns and ambiguities with previous JDK versions.) Essentially, this means that you cannot invoke a class (a method of a class) that is not within a package. Any attempt to do so will result in a fatal error at compilation time.

This especially affects JSP developers who invoke JavaBeans from their JSP pages, as such beans are often outside of any package (although the JSP 2.0 specification now requires beans to be within packages, in order to satisfy the new compiler requirements). Where JavaBeans outside of packages are invoked, JSP applications that were built and executed in an OC4J 9.0.3 / JDK 1.3.1 or prior environment will no longer work in an OC4J 9.0.4 / JDK 1.4 environment.

Until you update your application so that all JavaBeans and other invoked classes are within packages, you have the alternative of reverting back to a JDK 1.3.1 environment to avoid this issue.

For more information about the "classes not in packages" issue and other JDK 1.4 compatibility issues, refer to the following Web site:

http://java.sun.com/j2se/1.4/compatibility.html

In particular, click the link "Incompatibilities Between Java 2 Platform, Standard Edition, v1.4.0 and v1.3".

3.8.2.10 Considering Modified Servlet APIs and Behavior

When upgrading to Oracle Application Server 10g (9.0.4) and using servlets, consider the following changes in servlet APIs and behavior:

• Changes relating to getRequestURI()

• Changes regarding filtering of servlets that are forward or include targets

3.8.3.1 Enabling the webcached Executable to Run as The Root User

OracleAS Web Cache will not start after upgrade if the port settings of 80 and 443 were upgraded from the Oracle9iAS Release 2 (9.0.2) Web Cache to the Oracle Application Server 10g (9.0.4) Web Cache.

Because port numbers under 1024 are reserved for privileged processes in UNIX, the webcached executable in 10g (9.0.4) must run as root in order to start the cache server process and bind to these ports.

A script is provided that enables the webcached executable to run as the root user:

<destination_MT_OH>/webcache/bin/webcache_setuser.sh

Log in to the system as the root user and run the script.

3.8.3.2 Upgrading an OracleAS Web Cache Cluster

If you have a OracleAS Web Cache cluster, you can upgrade one cache cluster member at a time. The caches will continue to function, but because the other cluster members have a different version of the configuration, the caches will not forward requests to cache cluster members operating with a different version.

For example, if you upgrade Cache_A to the current version, but have not yet upgraded Cache_B and Cache_C, Cache_A will not forward requests to the cache cluster members Cache_B and Cache_C.

In this situation, the Operations page in Web Cache Manager indicates that the Operation Needed is Incompatible software version.

After you upgrade the cache cluster members, you must perform the following additional steps to synchronize the configuration for the members of the cluster:

1. If the caches have not been started, for each upgraded cache, start OracleAS Web Cache and OracleAS Web Cache Manager. On the command line, enter:

   opmnctl startproc ias-component=WebCache

   This command starts the OracleAS Web Cache cache server process and admin server process.

2. In a browser, enter the URL for the OracleAS Web Cache Manager for one of the upgraded caches, and, when prompted, enter the username and password for the ias_admin or administrator user.

3. In the navigator frame, select Administration > Operations.

   The Operations page appears.

4. In the Operations page, click Retrieve.

   Web Cache retrieves the cache-specific configuration information from the remote cache cluster members. Then, Web Cache Manager indicates that the Operation Needed is Propagate Configuration.

5. To propagate the configuration to all cache cluster members, select All caches and an Interval of Immediate. Then, click Propagate.

6. Restart the caches by selecting All caches and an Interval. Then, click Restart. (Note that you can perform this operation as you upgrade each cache, or you can perform this operation after all of the cache cluster members have been upgraded.)

3.8.3.3 Upgrading a Web Cache Cluster from Release 2 (9.0.2.x) to 10g (9.0.4)

A Release 2 (9.0.2.x) cache cannot accept invalidation messages from a 10g (9.0.4) cache. In a configuration that uses a OracleAS Web Cache cluster with a mixture of Release 2 (9.0.2.x) and 10g (9.0.4) cluster members, you must configure the Load Balancer to send invalidation messages only to the Release 2 (9.0.2.x) members.

When upgrading a cache cluster from Release 2 (9.0.2.x) to 10g (9.0.4), remove cluster members one at a time from the invalidation pool for the Load Balancer prior and upgrade them. Once all the cluster members are upgraded, add them back to the invalidation pool. As an example, assume a configuration with a Load Balancer in front of a cache cluster that is comprised of four members, webche1-host, webche2-host, webche3-host, and webche4-host, all running Release 2 (9.0.2.x). To upgrade this cache cluster:

1. In the Load Balancer configuration, remove webche1-host from the pool that is responsible for invalidation.

2. Upgrade webche1-host from Release 2 (9.0.2.x) to 10g (9.0.4).

3. In the Load Balancer configuration, remove webche2-host from the pool that is responsible for invalidation.

4. Upgrade webche2-host from Release 2 (9.0.2.x) to 10g (9.0.4).

5. In the Load Balancer configuration, remove webche3-host from the pool that is responsible for invalidation.

6. Upgrade webche3-host from Release 2 (9.0.2.x) to 10g (9.0.4).

7. Upgrade webche4-host from Release 2 (9.0.2.x) to 10g (9.0.4). As this is the last cache member in the Load Balancer configuration, it is not necessary to remove it from the invalidation pool.

8. In the Load Balancer configuration, add webche1-host, webche2-host, and webche3-host back into the pool that is responsible for invalidation.

3.8.4.1 Enabling OracleAS Portal for the Secure Sockets Layer (SSL) Protocol

Enabling OracleAS Portal for SSL is a manual process that involves setting a property in a configuration file, and running a script. Follow these steps to SSL-enable Portal applications:

1. Edit the <destination_MT_OH>/portal/conf/iasconfig.xml file.

2. Modify the SSL property as follows:

   SSLEnabled="true"

3. Change directories to <destination_MT_OH>/portal/conf.

4. Execute the OracleAS Portal configuration by issuing this command:

   ptlconfig -dad <DAD name> -site

   where <DAD name> is the name of the Database Access Descriptor (DAD) that points to the Portal repository in use by the Release 2 (9.0.2) Oracle home. Typically, the name is "portal".

   The script uses the iasconfig.xml file to update the Oracle Application Server Web Cache, Oracle Application Server Single Sign-On, and Oracle Internet Directory settings in OracleAS Portal.

3.8.4.2 Verifying Database Access Descriptor (DAD) Locations After Upgrade

The Release 2 (9.0.2) instance can have a DAD with the same location as a DAD in the destination location. If this is the case, the OracleAS Upgrade Assistant renames the DAD in the destination instance, since it is illegal for two DADs in the same installation to have the same location. For example, if there is a DAD in Release 2 (9.0.2) with the location:

<Location /pls/portal>

and the same name is found in the 10g (9.0.4) installation, the location in 10g (9.0.4) is changed to:

<Location /pls/portal_0>

After upgrade, ensure that all DADs are connecting to the intended resources.

3.8.4.3 Upgrading the Parallel Page Engine

If the Portal Parallel Page Engine in the source Oracle home has customized initialization arguments, you must manually upgrade these after the OracleAS Upgrade Assistant has finished processing.

The Parallel Page Engine initialization arguments are defined in the
<source_MT_OH>/j2ee/OC4J_Portal/applications/portal/portal/WEB-INF/web.xml file.

1. Locate all customized arguments (arguments added to the file and default arguments whose value has been changed) in the source Oracle home web.xml file.

2. Copy the customized arguments from <source_MT_OH>/j2ee/OC4J_Portal/applications/portal/portal/WEB-INF/web.xml to <destination_MT_OH>/j2ee/OC4J_Portal/applications/portal/portal/WEB-INF/web.xml.

3.8.4.4 Upgrading Portal Development Kit Services for Java (JPDK) Web Providers

The steps in this section are required if the source Oracle home has any of the following characteristics:

• Extra user JPDK web provider applications are deployed in the OC4J_Portal instance

• Provider Groups, Providers, and URL Portlets have been built using the OracleAS Portal user interface

• Configuration changes, customizations, or extensions have been made to web provider applications in the OC4J_Portal instance.

The upgrade process for Portal Development Kit Services for Java (JPDK) Web Providers consists of these steps.

1. Deploy user JPDK web provider applications in the destination Oracle home.

   
   

   Note: This step applies only to user applications. Applications such as jpdk and portalTools will already have been deployed in the destination Oracle home.

   
   

2. Identify the customized settings in the source Oracle home.

3. Apply the customizations to the destination Oracle home.

4. Update each OracleAS Portal instance that uses the provider with the new URL of the provider. After starting the instance as described in Section 3.12, perform the steps in Section 3.12.3, "Updating the OracleAS Portal Provider Information".

5. Refresh the Event/Parameter Passing Samples Provider. After starting the instance as described in Section 3.12, perform the steps in Section 3.12.4, "Refresh the Event/Parameter Passing Samples Provider".

The following sections describe the areas in which customizations are made, providing instructions on how to upgrade each area and register the upgraded web provider with its respective portal.

3.8.4.5 Completing the mod_plsql Upgrade

If the mod_plsql configuration has customized settings (properties whose value has been changed from the default) in <source_MT_OH>/Apache/modplsql/conf/plsql.conf, then you must manually upgrade these after the OracleAS Upgrade Assistant has finished processing.

1. Locate all customized property values in <source_MT_OH>/Apache/modplsql/conf/plsql.conf.

2. Copy the customized values to <destination_MT_OH>/Apache/modplsql/conf/plsql.conf.

3.8.4.6 Enabling Monitoring of a Release 2 (9.0.2) Portal Repository by the 10g (9.0.4) Oracle Enterprise Manager Application Server Control

If an Oracle Application Server middle tier uses a Release 2 (9.0.2) Oracle9iAS Portal Repository, you must execute a script to enable the monitoring component in the Application Server Control to access the OracleAS Portal version, and the OracleAS Portal Metadata Repository database version and start time. If the monitoring component cannot get this information, missing package errors (WWC_MONITORING) will occur (these are recorded in the Oracle HTTP Server logs).

Follow the steps below to enable monitoring:

1. Connect to SYS in SQL*Plus.

2. Execute the script:

   <destination_MT_OH>/portal/admin/plsql/wwc/cfgvr902.sql <Oracle9iAS portal schema name>

   If the script was successful, the following text appears:

   If there were no errors, run the following grant in SQL*Plus when connected to the Portal schema:

   grant execute on WWC_MONITORING to PUBLIC

3. Connect to the OracleAS Portal schema in SQL*Plus. If needed, use the Oracle Directory Manager to obtain the randomized Oracle9iAS Portal schema password. Navigate to:

   1. Entry Management

   2. cn=OracleContext

   3. cn=Products

   4. cn=IAS

   5. cn=Infrastructure Databases

   6. OrclReferenceName=Infrastructure Database (for example: iasdb.server.domain.com)

   7. OrclResourceName=PORTAL

   8. Click on the above entry.

   9. Look for the orclpasswordattribute value on the right panel. This is the schema password.

4. Execute the grant with this command:

   grant execute on WWC_MONITORING to PUBLIC;

3.8.4.7 Restoring Portal Tools (OmniPortlet and Web Clipping) Providers

Perform the steps in this section if:

• The Portal Tools application from the Portal Development Kit (PDK) November 2002 (9.0.2.4.0) or PDK July 2003 (9.0.2.6.2) is installed on the Release 2 (9.0.2) middle tier, and

• You now want to migrate the Portal Tools application to the 10g (9.0.4) middle tier.

Since the OracleAS Portal Middle Tier Upgrade process deploys a new Portal Tools application, you must restore the old providers settings into the new providers. This section explains how to restore them. These steps are necessary only for those providers which you were using and had configured before the upgrade process. If the PDK version is not specified, you need to perform the step for all versions. The OracleAS Portal Tools application contains:

• Web Clipping Provider

• OmniPortlet Provider

3.8.5.1 Upgrading the End User Layer

If you are upgrading from Oracle9iAS Discoverer version 9.0.2.52 or earlier, you must upgrade the End User Layer before you can use Oracle Application Server Discoverer 9.0.4 in 10g (9.0.4). See Section 4.6.1, "Upgrading the Oracle Application Server Discoverer End User Layer Schema", for instructions.

3.8.5.2 Upgrading Style Sheets

If you have changed style sheets in the Release 2 (9.0.2) installation, and you want these changes to be in effect in the 10g (9.0.4) installation, then you must re-apply the changes manually to the 10g (9.0.4) installation. Style sheet files that may require manual upgrade are listed below.

The following files in <source_MT_OH>/j2ee/OC4J_BI_Forms/ applications/discoverer/web/common/xsl may require manual upgrade:

• about.xsl

• add_connection_eul.xsl

• add_connection_main.xsl

• add_connection_responsibility.xsl

• blaf.xsl

• change_password.xsl

• delete_connection.xsl

• discoverer.xsl

• edit_connection_eul.xsl

• edit_connection_main.xsl

• edit_connection_responsibility.xsl

• errors.xsl

• functions.xsl

• gui_components.xsl

• list_of_connections.xsl

• render_table.xsl

• scripts.xsl

The following files in <source_MT_OH>/j2ee/OC4J_BI_Forms/applications/discoverer/web/viewer_files/xsl may require manual upgrade:

• page_layouts.xsl

• sorting.xsl

• style.xsl

3.8.5.3 Upgrading the tnsnames.ora File

The <source_MT_OH>/network/admin/tnsnames.ora file defines database instances referenced by Oracle Application Server Discoverer connections created in Oracle9iAS Discoverer Release 2 (9.0.2). The same database instances must appear in the <destination_MT_OH>/network/admin/tnsnames.ora file in order for connections upgraded to Oracle Application Server Discoverer 10g (9.0.4) to function. This file may require upgrade.

3.8.6.1 Upgrading User-Defined OC4J Instances With Oracle Application Server Reports Services Deployments

The OracleAS Upgrade Assistant upgrades the Oracle9iAS Release 2 (9.0.2) Business Intelligence & Forms configuration to the Oracle Application Server 10g (9.0.4) Business Intelligence & Forms configuration. It is not aware of OC4J instances outside of these configurations that may contain deployed reports, or of customizations made to those instances in order to enable the deployed reports to run.

Therefore, if you are using OC4J instances other than the standard Business Intelligence and Forms OC4J instance, you must apply any manual deployment steps that you performed on those instances in Oracle9iAS Release 2 (9.0.2) to the equivalent instances in Oracle Application Server 10g (9.0.4).

You must also add the Java option below to the java-options tag in <destination_MT_OH>/opmn/conf/opmn.xml to these OC4J instances before you can use them for Oracle Application Server Reports Services.

-Xbootclasspath^/p:<destination_MT_OH>/vbroker4/lib/vbjboot.jar

<data id="java-options" value="-Dhttp.proxyHost=www-proxy.us.oracle.com 
-Dhttp.proxyPort=80"/>

<data id="java-options" value="-Dhttp.proxyHost=www-proxy.us.oracle.com 
-Dhttp.proxyPort=80"
-Xbootclasspath^/p:<destination_MT_OH>/vbroker4/lib/vbjboot.jar"/> 

3.8.7.1 Using the Oracle Application Server Wireless Notification Service Upgrade Script

This section explains how to upgrade notifications created by the Oracle Application Server Wireless Notification Engine in the Oracle Application Server Wireless System Manager. The architecture and functionality of the Notification Engine are not described here.

You can upgrade notifications from Release 2 (9.0.2) to 10g (9.0.4) with the migrateNotifications.sh script. To execute the script:

1. Navigate to <destination_MT_OH>/wireless/bin.

2. Set the ORACLE_HOME environment variable to the 10g (9.0.4) Oracle home.

3. Issue one of the commands below:

   • migrateNotifications.sh -name deprecated master alert name(s) -owner owner user name

   • migrateNotifications.sh -oid deprecated master alert oid -owner owner user name

   
   

   Notes: The name parameter enables you to upgrade alerts by name. The oid parameter enables you to upgrade a specific alert by object ID. You can use the % wildcard character to specify deprecated master alert names. All 9.0.4.x notification objects (master alert service, master service, link, and so on) will be owned by the user name specified.

   
   

   The script does the following:

   • Creates a new master alert service named old master alert name_New. (This process involves converting the message template to a valid mobile xml, if necessary.)

   • Creates the folder /master/notifications, if it does not exist.

   • Creates the master service old master alert name_MS.

   • Creates a mapping for the new master alert and the new master service based on the message template for the old master alert.

   • Creates the folder /Users Home/username/notifications, if it does not exist.

   • Discovers all associated 9.0.2.x AlertService objects and converts them to link objects. (The top-level authorization is flattened to link level authorization during this process.)

   • Transforms all subscriptions for alert services converted.

The following command upgrades all 9.0.2.x master alert services whose name starts with StockAlert (e.g., StockAlertNews, StockAlertWarning, etc.). All new objects will be owned by the orcladmin user.

migrateNotifications.sh -name StockAlert% -owner orcladmin

The following command upgrades the 9.0.2.x master alert service with the name StockAlert, and assigns all new objects to the systemadmin user.

migrateNotifications.sh -name StockAlert -owner systemadmin

The following command upgrades the 9.0.2.x master alert service with the object ID 1973, and assigns all new objects to the systemadmin user.

3.8.7.2 Operating Oracle Application Server Wireless Release 2 (9.0.2) and 10g (9.0.4) Middle Tiers Together

You can operate an environment with Oracle9iAS Wireless Release 2 (9.0.2) and Oracle Application Server Wireless 10g (9.0.4) middle tiers using the same Infrastructure services. However, this configuration is subject to some restrictions, as described below.

• J2ME download and XHTML/XForms based applications should not be used in a mixed environment. These features are new in Oracle Application Server Wireless 10g (9.0.4), and would cause errors when attempting to access them from any of the Oracle9iAS Wireless Release 2 (9.0.2) middle tiers. If you wish to use these features, then it is necessary to upgrade all middle tiers to Oracle Application Server Wireless 10g (9.0.4).

• The Notification Engine cannot be used in a mixed environment. Instead, you should use the Alert Engine.

• Service access point (service-level address) should be created through an Oracle Application Server Wireless 10g (9.0.4) middle tier, in order for them to be visible to both the Oracle Application Server Wireless 10g (9.0.4) middle tiers and Oracle9iAS Wireless Release 2 (9.0.2) middle tiers.

• Oracle Application Server Wireless 10g (9.0.4) supports user name case sensitivity. However, this requires that you upgrade the Oracle Internet Directory to Oracle Application Server 10g (9.0.4).

• Changing (adding, deleting, or updating) a 10g (9.0.4) ASK Access point will not be reflected on the Release 2 (9.0.2) Enterprise Manager until the Release 2 (9.0.2) Enterprise Manager is restarted. The Release 2 (9.0.2) OC4J must also be bounced in order for ASK to pick up the changes. A driver account (for example, an e-mail account for an e-mail driver) which is removed from an instance and subsequently added to another instance of different release (for example, from Release 2 (9.0.2) to 10g (9.0.4)) may cause messages to be lost. To resolve this, restart the OC4J for the instance from which the account is removed.

The Notification Engine introduced in Oracle Application Server Wireless 10g (9.0.4) replaces the Alert Engine, which was part of Oracle9iAS Wireless Release 2 (9.0.2). Although the Alert Engine is still available in Oracle Application Server Wireless 10g (9.0.4), Oracle Corporation recommends that after all middle tiers have been upgraded to Oracle Application Server Wireless 10g (9.0.4), you switch to the Notification Engine, as the Alert Engine may not be available in future versions of Oracle Application Server Wireless. Upgrade scripts are available to help you with this task. See the Oracle Application Server Wireless Developer's Guide for details. The Oracle9iAS Wireless Release 2 (9.0.2) Alert APIs have been deprecated, and you must upgrade your applications to use the Oracle Application Server Wireless 10g (9.0.4) APIs instead.

3.8.7.3 Configuring Site-Level Drivers in a Mixed Mode Environment

In a mixed mode environment, Oracle9iAS Wireless Release 2 (9.0.2) and Oracle Application Server Wireless 10g (9.0.4) may have transport drivers configured to receive incoming messages. The two sets of entry points, Oracle9iAS Wireless Release 2 (9.0.2) and Oracle Application Server Wireless 10g (9.0.4), should not be exposed to a device at the same time. A user issuing a request to the Release 2 (9.0.2) instance should not subsequently send another request, within an 3 hour period, to the entry point defined in the transport driver of the Oracle Application Server Wireless 10g (9.0.4) instance. The same user may not receive any response for requests addressed to the latter entry point, if it is violated.

Since the driver configuration is different in Release 2 (9.0.2) and 10g (9.0.4), when a Oracle9iAS Wireless Release 2 (9.0.2) instance is upgraded to Oracle Application Server Wireless 10g (9.0.4), the transport drivers must be managed such that requests are processed as expected.

In 10g (9.0.4), a site level driver can be enabled or disabled. By default, it is enabled. If a driver is disabled, it is not recognized by the routing algorithm, and therefore is not used by the messaging system. However, in Release 2 (9.0.2), all site level drivers are recognized by the routing algorithm.

If a Release 2 (9.0.2) instance has two middle tiers, after one of the middle tiers and the Infrastructure are upgraded to 10g (9.0.4), the upgraded middle tier may enable or disable a site level driver. However, middle tiers that are not yet upgraded recognize all drivers as enabled. For this reason, it is prudent to remove, rather than disable, a driver in this type of environment.

InRelease 2 (9.0.2), the transport mechanism can route a message to only one driver, and it does not matter whether there is an instance configured for it. This means that a message will not be delivered if it is indeed routed to a driver that has no instance configured. For this reason, the best practice is to remove all drivers that do not have an instance configured in any Release 2 (9.0.2) environment, including a Release 2 (9.0.2) and 10g (9.0.4) mixed environment.

3.8.8.1 Upgrading the tnsnames.ora File

Entries may have been added to, or changed in, the tnsnames.ora file between the installation of Oracle9iAS Release 2 (9.0.2) and upgrade to 10g (9.0.4). If so, you must upgrade this file manually so that any added or changed entries are available in 10g (9.0.4).

If an error occurs after upgrade, it may be because the tnsnames.ora file was overwritten by another component upgrade. A missing or incorrect entry yields the following error:

ORA-12154: TNS: Could not resolve service name.

3.8.8.2 Upgrading Forms *.fmx Files

If you have deployed these files within the source Oracle home, you must manually copy them to the same location in the destination Oracle home. If the *.fmx files are not under the Oracle home on the file system, then no action is needed, as the FORMS90_PATH will be upgraded by the OracleAS Upgrade Assistant, and it will be valid after the upgrade.

3.8.8.3 Upgrading User-defined Aliases for Oracle Application Server Forms Services Servlets

If you defined any aliases for the OracleAS Forms Services servlets in:

<source_MT_OH>/j2ee/OC4J_BI_FORMS/applications/forms90app/forms90web/WEB-INF/web.xml, then you must manually copy these entries to:

<destination_MT_OH>/j2ee/OC4J_BI_FORMS/applications/forms90app/forms90web/WEB-INF/web.xml.

3.8.8.4 Upgrading forms90app.ear Deployed in User-defined OC4J Instances

The forms90app.ear file is deployed by default into the OC4J_BI_Forms OC4J instance. Note that the Upgrade Assistant upgrades all user-defined OC4J instances and the applications deployed under these instances to the destination Oracle home.

Thus, if you have deployed the forms90app.ear file into one of the user-defined OC4J instances in the source Oracle home, the Upgrade Assistant will upgrade this deployment into the corresponding OC4J instance in the destination Oracle home.

As a result, the source Oracle home Release 2 (9.0.2) forms90app.ear file is deployed into the destination Oracle home. This causes the configuration of OracleAS Forms Services 10g (9.0.4) to be incorrect, because it requires the 10g (9.0.4) EAR file in order to function properly.

Therefore, you must undeploy the forms90app.ear file from these upgraded OC4J instances in the destination Oracle home, and then deploy forms90app.ear in the destination Oracle home again.

The Oracle Application Server Forms Services 10g (9.0.4) forms90app.ear file is located in: <destination_MT_OH>/forms90/j2ee.

3.8.8.5 Enabling the Oracle Application Server Forms Services Oracle Application Server Single Sign-On and Oracle Internet Directory Configuration

The Oracle Application Server Single Sign-On and Oracle Internet Directory configuration for Oracle Application Server Forms Services is disabled by default. If the configuration was enabled in Release 2 (9.0.2), the OracleAS Upgrade Assistant does not automatically enable it in 10g (9.0.4).

You can enable the configuration by setting the ssoMode entry value to true in the file:

<destination_MT_OH>/forms90/server/formsweb.cfg

In Release 2 (9.0.2), a servlet alias could be set up in the forms90.conf file in order to run Oracle9iAS Forms Services using Single Sign-On. In 10g (9.0.4), Single Sign-On can be configured on a per-application basis in the formsweb.cfg file. You can configure it for all applications as described above, by setting the ssoMode entry value to true in the default section of the file. To configure it for a specific application, set it to true in that application’s configuration section of the file.

3.8.9.1 Append New and Changed Entries to the 10g (9.0.4) tnsnames.ora File

Copy all new and changed entries to the <destination_MT_OH>/network/ admin/tnsnames.ora file.

3.8.9.2 Copy the Oracle9iAS Release 2 (9.0.2) tnsnames.ora File to the 10g (9.0.4) Installation

If you are certain that doing so will not eliminate entries added or changed by other components, you can copy the entire tnsnames.ora file from the source to the destination Oracle home, restoring the EXTPROC_CONNECTION_DATA.US.ORACLE.COM entry (which is introduced in 10g (9.0.4)).

To upgrade by copying the entire file, follow the steps below:

1. Create a backup of <source_MT_OH>/network/admin/tnsnames.ora and <destination_MT_OH>/network/admin/tnsnames.ora.

2. Copy the entire tnsnames.ora file from the source to the destination Oracle home.

3. Copy the EXTPROC_CONNECTION_DATA.US.ORACLE.COM entry (used for executing external procedures in the database) from the 10g (9.0.4) backup file created in step 1 to the Oracle9iAS Release 2 (9.0.2) file.

3.14.1.1 Preserving Application Files and Log Files

If there are application files or log files in the source Oracle home that are being referenced or used by the destination Oracle home, you should move them to another location before you decommission the source Oracle home, and, in the destination Oracle home, change any references to the files to the new location.