3
Migrating Oracle9iAS Containers for J2EE (OC4J)

This chapter explains the functionality of the OC4J migration option. It contains the following topics:

• OC4J Migration Candidates

• The OC4J Configuration File Migration Process

• Backup and Auditing Measures for OC4J Migration

OC4J Migration Candidates

The OC4J migration option recognizes these configuration files and applications as candidates for migration:

• The principals.xml and data-sources.xml files.

• Applications defined in the server.xml file in the source instance, in .ear file format.

  Note: Applications must be in .ear file format and defined in the source server.xml file in order to be migrated. Applications are deployed to the 9.0.3 Oracle9iAS instance using DCM (Distributed Configuration Management). The assumption is that the application being migrated was not installed there previously (the 9.0.3 instance is supposed to be a new, unchanged Oracle9iAS installation), but if an application of the same name exists, it will be overwritten. The Assistant will not migrate applications in any format other than .ear (such as .war, exploded, etc.).

Default JSP Package Imports in OC4J

When migrating applications to Release 2 (9.0.3), be aware that the OC4J JSP container imports the following packages into any JSP page, by default, in accordance with the JSP specification. No page directive import settings are required:

javax.servlet.*

javax.servlet.http.*

javax.servlet.jsp.*

In previous releases, the following packages were also imported by default:

java.io.*

java.util.*

java.lang.reflect.*

java.beans.*

The default list of packages to import was reduced to minimize the chance of a conflict between any unqualified class name you might use and a class by the same name in any of the imported packages.

However, this might result in migration problems for applications you have used with previous versions of Oracle9iAS. Such applications might no longer compile successfully. If you need imports beyond the default list, you have two choices:

• Specify additional package names or fully qualified class names in one or more page directive import settings.

• Specify additional package names or fully qualified class names through the JSP extra_imports configuration parameter, or by using the ojspc -extraImports option for pre-translation. Syntax varies between OC4J configuration parameter settings, JServ configuration parameter settings, and ojspc option settings, so refer to information in the Oracle9iAS Support for JavaServer Pages Developer's Guide.

OC4J Elements Not Migrated

The Migration Assistant does not migrate:

• Files other than those listed in "OC4J Migration Candidates". Any customizations made to files that are not included in the .ear file in the source instance must be migrated manually. For example, files such as orion-web.xml, orion-ejb-jar.xml, and orion-application.xml that are created by OC4J in the /application-deployments directory must be migrated manually.

• OC4J instances in locations other than the ORACLE_HOME_1/j2ee/home/ directory (the "home" instance). There may be other instances of OC4J in use, such as the Portal instance, the demos instance, or instances created elsewhere), but these will not be migrated when you run the Migration Assistant.

• OC4J applications in formats other than .ear file format. Customization not included in the selected .ear file in the "home" instance must be migrated manually. Usually, .ear files are located in:

  ORACLE_HOME_1/j2ee/oc4j instance name/applications/

  For a complete listing of the .ear files, look in:

  ORACLE_HOME_1/j2ee/oc4j instance name/config/server.xml

The OC4J Configuration File Migration Process

The Migration Assistant performs the following steps during OC4J migration:

1. Copies selected principals.xml and data-sources.xml from:

   ORACLE_HOME_1/j2ee to ORACLE_HOME_2/j2ee (UNIX)

   ORACLE_HOME_1\j2ee\home\config to ORACLE_HOME_2\j2ee\home\config (Windows)

2. Reads application information from the server.xml file in ORACLE_HOME_1 and prompts you to select the applications to migrate.

3. Starts a default OC4J instance in ORACLE_HOME_2.

4. Re-deploys the migrated applications in ORACLE_HOME_2.

5. Stops the default OC4J instance.

J2EE Compliance Requirements for OC4J Migration

OC4J deployment enforces J2EE compliance rules. For this reason, the Oracle9iAS Migration Assistant may not migrate applications that are not 100% J2EE compliant. The Assistant simply reads the files and attempts to deploy them to the target Oracle9iAS instance; if deployment fails, it could be because an application is not J2EE compliant.

If the Assistant cannot deploy an application for any reason, it logs the exception, however, the exception may not be explicitly described as a compliance issue.

While the development of J2EE applications is standardized and portable, the XML configuration files are not. You may have to configure multiple XML files before deploying an application to OC4J. The configuration needed depends on the services the application uses. For example, if the application uses a database, you must configure the DataSource object in the data-sources.xml file.

Warning: If any migrated application uses datasource tags, you must select data-sources.xml for migration. If you do not, the migration will fail.

Validating EAR Files for J2EE Compliance

The dcmctl utility (ORACLE_HOME_2/dcm/bin/dcmctl on UNIX, or ORACLE_HOME_2\dcm\bin\dcmctl) provides a J2EE compliance validation command. It takes one input, the name of an EAR file, and lists non-compliant characteristics of that file. The syntax is:

dcmctl validateEarFile -v -f name.ear

where name is the name of the.ear file. -v specifies the verbose option of dcmctl; this provides the most detailed output of commands.

You must configure proxy settings so that the validation routine can access DTDs on the Web, if necessary (for example, on the Sun Microsystems site). To do this, you define an environment variable called ORACLE_DCM_JVM_ARGS, which specifies a hostname and port for the proxy. The commands to set the variable are shown below.

UNIX:

setenv ORACLE_DCM_JVM_ARGS '-Dhttp.proxyHost=host -Dhhtp.proxy.port=port'

Windows:

set ORACLE_DCM_JVM_ARGS="-Dhttp.proxyHost=host -Dhttp.proxyPort=port"

Example 3-1 validateEarFile Command and Output for J2EE-Compliant Application

dcmctl validateEarFile -v -f simple.ear

No J2EE XML/DTD validation errors were found

Example 3-2 validateEarFile Command and Output for non- J2EE-Compliant Application

dcmctl validateEarFile -v -f petstore.ear

Warning: J2EE/DTD validation errors were found

Cannot get xml document by parsing WEB-INF\web.xml in petstore.war:

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]'.

It is a good idea to review all applications for overall J2EE compliance before migrating them, since there are cases in which an application is deployable, but delivers unpredictable or undesirable server behavior. For example, ensure that content is served correctly by defining a unique context root for each application in application.xml.

Using OC4J in Backward-compatibility Mode

The following OC4J components may require backward compatibility:

• Oracle JMS

• Oracle JDBC

• Oracle XML parser for JAXP/XDK

You can revert an OC4J instance to pre-J2EE 1.3 behavior by setting the Master CTS compatibility flag.

See Also: Oracle9iAS Containers for J2EE (OC4J) Release Notes in the Oracle9iAS Documentation Library

Backup and Auditing Measures for OC4J Migration

The Assistant performs the following functions to provide a way to audit the migration process:

• Creates a backup of each configuration file. The copy has the same filename, and the extension .SAVED_COPY.

• Logs all migration activity and errors in

  ORACLE_HOME_2/migration/log/iASMigration.log (UNIX)

  ORACLE_HOME_2\migration\log\iASMigration.log (Windows)