|Oracle® Fusion Middleware Upgrade Guide for Java EE
11g Release 1 (11.1.1)
Part Number E10126-02
This chapter describes how to upgrade a basic Java EE environments. However, you can use these instructions to develop an understanding of the upgrade process and apply this knowledge in your planning of other upgrade scenarios.
Upgrading a basic Java EE environment involves the following key tasks:
To test and verify your upgraded Java EE applications, you must install Oracle WebLogic Server. The following sections describe information about installing and configuring Oracle WebLogic Server:
When you are developing and upgrading your Java EE applications, you will likely want to install a basic Oracle WebLogic Server environment that you can use for testing your applications quickly and efficiently. This will help you frequently deploy and test your applications as you make required code changes.
This environment differs from your test or production environment in the following ways:
A development environment is typically a single-node environment. There is no need for a Web tier or clustering capabilities to provide load-balancing or high availability. However, the development must include the various resources (such as JDBC data sources, JMS providers, and database instances) required to support the application during development.
Use the instructions in this chapter to configure a development environment.
The Oracle WebLogic Server domain you create in your development environment can be configured in development mode, which makes it quicker and easier to configure the resources of the domain and to deploy and redeploy applications to test code changes. You select development mode or production mode when you create your domain using the Oracle WebLogic Server Configuration Wizard.
For more information, see "Examples: Using the Configuration Wizard" in Oracle WebLogic Server Creating WebLogic Domains Using the Configuration Wizard.
Note that the default tuning parameters of Oracle WebLogic Server are different, depending upon whether you are configuring a development or production domain. For more information, see "Development vs. Production Mode Default Tuning Values" in Oracle Fusion Middleware Performance and Tuning for Oracle WebLogic Server.
Oracle WebLogic Server is available as part of Oracle JDeveloper Studio. As a result, if you are using Oracle JDeveloper Studio as your integrated development environment (IDE), you can install Oracle WebLogic Server as part of the Oracle JDeveloper installation.
For complete instructions for installing and configuring Oracle WebLogic Server with Oracle JDeveloper Studio, see "Installing the Oracle JDeveloper Studio Edition" in Oracle Fusion Middleware Installation Guide for Oracle JDeveloper.
If you are not using Oracle JDeveloper for developing your applications, then you can install Oracle WebLogic Server from the Oracle WebLogic Server CD-ROM, which is part of the Oracle Fusion Middleware 11g Media pack, or by downloading Oracle WebLogic Server from the Oracle Technology Network (OTN).
The following is a summary of the steps for installing and configuring the domain:
Use the Oracle WebLogic Server installer to install the Oracle WebLogic Servers software on disk and to create the Middleware home.
For more information, see the Oracle WebLogic Server Installation Guide.
Use the Oracle WebLogic Server configuration wizard to configure the domain.
When you configure your development domain, be sure to select development mode in the Oracle WebLogic Server configuration wizard.
For more information, see the Oracle WebLogic Server Creating WebLogic Domains Using the Configuration Wizard.
Start the domain.
Start Oracle WebLogic Server by running the following command-line script in the Middleware home:
On UNIX systems:
When you configure Oracle WebLogic Server, you configure each domain using domain templates. One of the domain templates available with Oracle Fusion Middleware 11g is the Java Required Files (JRF) template.
The JRF template provides important Oracle libraries and other capabilities that support new versions of APIs that many OC4J applications depend upon.
For information on the types of APIs in the JRF template that are important to upgraded OC4J applications, see Section 4.5.1, "APIs Available With the Java Required Files (JRF) Domain Template".
To create or extend a domain using the JRF template, refer to the following:
To create a new domain using the JRF template:
Install and configure a development domain using the Oracle JDeveloper 11g installer.
The resulting domain is automatically created using the JRF template.
Install and configure an Application Developer, Oracle SOA Suite, WebCenter, Oracle Identity Management, or Oracle Portal, Forms, Reports, and Discoverer domain.
When you configure any Oracle Fusion Middleware software suite, you have the option of selecting the JRF template while running the configuration tool.
For more information, refer to the appropriate Oracle Fusion Middleware installation guide.
To extend an existing domain with the JRF template:
Use the Oracle JDeveloper 11g installer.
In the Oracle JDeveloper installer, select a custom installation and select the ADF Runtime component. This step allows you to install the ADF runtime jar files and domain templates to the server environment.
For more information, see "Creating and Extending WebLogic Domains" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Run the Oracle WebLogic Server configuration wizard from an Application Developer, Oracle SOA Suite, WebCenter, Oracle Identity Management, or Oracle Portal, Forms, Reports, and Discoverer Oracle home.
Select the options to extend the domain and select the JRF template when prompted with the list of available templates.
For more information, refer to the appropriate Oracle Fusion Middleware installation guide.
Use Oracle Enterprise Manager Fusion Middleware Control or the ApplyJRF WebLogic Scripting Tool (WLST) command to apply the JRF template to an existing WebLogic server instance.
For more information, see Section 17.3.1, "Applying Java Required Files to a Managed Server or Cluster," in the Oracle Fusion Middleware Administrator's Guide.
To verify that the new Oracle Fusion Middleware environment is installed and configured and ready to use, do the following:
Log in to the Oracle WebLogic Administration Console, using the following URL and the weblogic administration credentials you provided during the configuration:
In the left pane of the Console, select Environment and then select Servers.
Review the servers that were created as part of your domain and verify that the servers are up and running.
After you have modified your applications, you must then ensure that any services required by the application are configured on the Oracle WebLogic Server domain.
The following sections provide information on the typical Oracle WebLogic Server administration tasks that are required before you deploy an application you are upgrading from Oracle Application Server 10g:
The following sections provide information about upgrading OC4J JDBC data sources to Oracle WebLogic Server:
In general, you can create the equivalent OC4J data source configuration on WebLogic Server, based on the database connection information, pooling requirements and JDBC driver.
When you create a data source for an application deployed on OC4J, you can define the data source in one of two ways:
For a specific OC4J instance or OC4J group where the application will be deployed.
Package the data source definition as part of the application archive in a file named
Both these methods are supported by Oracle WebLogic Server, but you must perform some configuration tasks, either on the Oracle WebLogic Server domain or within the application, depending on the method you use.
Just as in OC4J, a WebLogic Server JDBC data source is an object bound to a JNDI context which provides database connectivity through a pool of JDBC connections. Applications look up a data source in the JNDI context in order to use a database connection from this pool.
Oracle WebLogic Server data sources are typically defined at domain level and applied across the cluster or to specific managed servers within a domain. However, if you have defined your OC4J data sources in the OC4J-supported
data-sources.xml file of your application archive, then you can implement a similar configuration in Oracle WebLogic Server.
For Oracle WebLogic Server, data sources can be packaged as a JDBC module within the application. This provides the equivalent capability of application-level data sources in OC4J.
For more information, see "Configuring JDBC Application Modules for Deployment" in Oracle Fusion Middleware Configuring and Managing JDBC for Oracle WebLogic Server.
If you have defined data sources for your OC4J instance or group, you must define an equivalent set of data sources in your new Oracle WebLogic Server domain.
For each JDBC data source configured within the OC4J environment, create a new Oracle WebLogic Server JDBC data source with the same JNDI name in the target domain.
For more information, see "Create a JDBC Data Source" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help.
Note that Oracle WebLogic Server JDBC data sources can be configured to take advantage of Oracle Real Application Clusters (RAC). For more information, see the Oracle Fusion Middleware High Availability Guide.
There are two important differences between OC4J and Oracle WebLogic Server JDBC data source connection pooling:
Oracle WebLogic Server JDBC data sources have an implicit connection pool associated with them and, therefore, you don not have to create an explicit connection pool in the domain as you do in the OC4J environment.
Oracle WebLogic Server JDBC data sources always behave like managed Oracle data sources; there is no equivalent to OC4J native data sources.
The following sections provide information on upgrading your OC4J JMS resources to Oracle WebLogic Server:
OC4J provided JMS support via a set of services called Oracle Enterprise Messaging Service (OEMS).
OEMS provides a messaging platform for building and integrating distributed applications. It provides the framework for Oracle messaging and message integration solutions, and is based on industry standards, such as the Java Message Service (JMS) and J2EE Connector Architecture (J2CA).
OEMS supports three types of JMS provider persistence models:
Oracle DB Advanced Queuing (AQ)
Oracle WebLogic Server provides direct equivalents for the in-memory and file-based JMS providers.
For more information, see "Overview of JMS and WebLogic Server" in Oracle Fusion Middleware Configuring and Managing JMS for Oracle WebLogic Server.
In OC4J, you configure JMS connection factories and destinations for a JMS server on an individual OC4J instance. The connection factories and destinations are then mapped to resource providers or JMS connectors.
In WebLogic Server, you create JMS resources within an WebLogic JMS module. JMS modules are targeted to a WebLogic JMS Server within a domain. WebLogic JMS servers provide a central point which allows for the configuration of message persistence, durable subscribers, message paging, and quotas for their targeted JMS destinations.
To upgrade the JMS configuration in your OC4J environment to Oracle WebLogic Server:
Create a set of WebLogic JMS servers with configurations that reflect the OC4J environment's JMS resource providers, connectors, connection factories and destination configurations.
Create a WebLogic Server JMS module for each set of JMS connection factories and destinations with common configurations.
Populate the module with JMS connection factories and destinations that have the same JNDI name as their equivalent version in OC4J.
Finally, target the JMS modules to the appropriate WebLogic JMS server within the domain.
For more information, see Oracle Fusion Middleware Configuring and Managing JMS for Oracle WebLogic Server.
In OC4J, you configure remote destinations and connection factories for third-party JMS providers such as WebSphereMQ, Tibco, and SonicMQ as part of a JMS connector configuration.
In Oracle WebLogic Server, you access remote destinations through the WebLogic Server Foreign Server resources, which enable users to integrate external JMS providers with WebLogic Server. The Foreign Server resources provide a mapping between a domain's JNDI tree and external remote JNDI names of JMS destinations and connection factories.
To upgrade an OC4J external JMS provider configuration to an Oracle WebLogic Server domain, create a JMS module that contains a foreign server. Then create a set of foreign connection factories and foreign destinations that can serve as a proxy to the remote destinations that need to be accessed from the domain.
For more information, see "Configuring Foreign Server Resources to Access Third-Party JMS Providers" in the Oracle Fusion Middleware Configuring and Managing JMS for Oracle WebLogic Server.
When upgrading to Oracle WebLogic Server, you can construct an Oracle WebLogic Server target environment that uses a class-loading configuration similar to the one used in the OC4J source environment.
However, due to the differences between the OC4J and Oracle WebLogic Server class loading models, it is important to develop a good understanding of Oracle WebLogic Server application class loading prior to setting up the target Oracle WebLogic Server configuration.
Table 5-1 summarizes the options available in Oracle WebLogic Server for application developers who used the class loading configurations available in the OC4J environment. The table provides a high level mapping of the main OC4J approaches to making a class available to an application to the most comparable way of achieving the same outcome within a WebLogic Server environment.
For more information, see "Creating Shared Java EE Libraries and Optional Packages" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server.
Table 5-1 Comparison of OC4J and Oracle WebLogic Server Class-Loading Models
|OC4J Approach||Comparable Oracle WebLogic Server Approach|
Class is made available to the application's class loader through Oracle-specific
Add the class or JAR file to the application's
For Web applications, add the class or JAR files to the application's
Class is exposed to specific applications as an OC4J shared library.
Deploy the JAR file to the Oracle WebLogic Server instance or cluster as a WebLogic Server shared library.
Note that there are some important differences in the concept of shared libraries between OC4J and WebLogic:
Class is exposed to all applications on all OC4J instances by either referencing the class in the default application's
Place the JAR file in the domain directory's
Class is added to the classpath of the OC4J instance and made available to the entire server instance through the system class loader.
Configure the Oracle WebLogic Server instance so either the
Any startup or shutdown class configured within the source OC4J environment should be converted to a set of Oracle WebLogic Server startup or shutdown classes. Each class must then be configured within the target Oracle WebLogic Server domain and targeted to the Oracle WebLogic Server instances corresponding to the associated OC4J instances in the source environment.Unlike OC4J startup and shutdown classes, an Oracle WebLogic Server startup or shutdown class does not require any specific interface or provide pre-deployment or post-deployment methods. Instead, you implement the custom logic within the standard
main() method of the class.
WebLogic Server allows for pre-deployment and post-deployment execution of this logic by providing configuration parameters, which must be set accordingly when configuring a domain with the startup or shutdown class.
To convert an OC4J startup or shutdown class, it might therefore be necessary to create two WebLogic Server startup and shutdown classes:
One that contains the code from the original class pre(Un)deploy method
One that contains the code from the post(Un)deploy method.
Although pre-configured parameters can be passed to the
main() method of a WebLogic Server startup or shutdown class, Oracle WebLogic Server startup classes have no access to arguments in the way that JNDI context and configuration hash table parameters are passed to an OC4J startup class.
If the custom logic within the startup class makes use of these parameters, then this logic should be modified to obtain the JNDI context from scratch and access the server configuration through the Oracle WebLogic Server JMX interfaces.
For more information, see the following:
"Programming Application Life Cycle Events" in Oracle Fusion Middleware Developing Applications for Oracle WebLogic Server
"Configure startup classes" and "Configure shutdown classes" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help
To support the security requirements of your application, you must map the security features of OC4J to the equivalent security features in Oracle WebLogic Server.
Table 5-2 describes how specific OC4J security configurations can be mapped to a WebLogic Server environment.
Table 5-2 Comparison of OC4J and Oracle WebLogic Server Security Features
|For this OC4J Security Feature...||Perform the following task in Oracle WebLogic Server...||More Information|
Users and groups are stored in the
Move the user and group information contained in the
"Managing the Embedded LDAP Server" in Oracle Fusion Middleware Securing Oracle WebLogic Server
OC4J is configured to use an external LDAP provider.
Configure the Oracle WebLogic Server domain with the same LDAP server as you were using for OC4J.
"Configuring LDAP Authentication Providers" in Oracle Fusion Middleware Securing Oracle WebLogic Server
Users are authenticated against a database.
Configure an RDBMS authentication provider, which can be one of three types:
"Configuring RDBMS Authentication Providers" in Oracle Fusion Middleware Securing Oracle WebLogic Server
OC4J environment is configured with Java single sign-on or subject propagation between multiple OC4J server instances.
WebLogic Server single sign-on and subject propagation are automatic across the server and clusters within a domain and therefore no special configuration is required.
OC4J environment is configured with custom JAAS login modules.
Create an Oracle WebLogic Server authentication provider within the target domain, either out-of-the-box or a custom provider which wraps the JAAS login module functionality.
"Configuring Login Modules" in the Oracle Fusion Middleware Security Guide
"Configuring Authentication Providers" in the Oracle Fusion Middleware Securing Oracle WebLogic Server
OC4J environment is configured with Oracle Access Manager.
Configure the Oracle WebLogic Server domain to use Oracle Access Manager.
"Integrating the Security Provider for WebLogic SSPI" in the Oracle Access Manager Integration Guide in the Oracle Identity Management 10g (10.1.4) Identity Management instancedocumentation library on the Oracle Technology Network (OTN).
OC4J server instances are configured with SSL encryption.
Configure the Oracle WebLogic Server domain to use SSL.
"Configuring SSL" in Oracle Fusion Middleware Securing Oracle WebLogic Server
OC4J environment uses Oracle Wallet to store security keys.
Store your security keys in a JKS key store in the WebLogic Server domain.
"Configuring Identity and Trust" in Oracle Fusion Middleware Securing Oracle WebLogic Server
WebLogic Logging Services provides a comprehensive set of logging features that provide capabilities similar to OC4J. As with OC4J, the Oracle Diagnostics Logging (ODL) framework can be integrated into Oracle WebLogic Server through the Oracle Java Required Files (JRF) domain template.
For more information, see Section 5.1.4, "Using the Java Required Files (JRF) Domain Template".
As a result, if an application is using the ODL framework for logging, it requires no modification when deployed to Oracle WebLogic Server. The JRF ODL integration into Oracle WebLogic Server is as follows:
ODL log messages are sent to a separate log file that is kept in a well-known location on the file system:
Critical messages (errors) are double-logged both in the ODL and WebLogic domain log file.
ODL log queries and configuration JMX MBeans are available in the domain's WebLogic administration server.
For more information, see Oracle Fusion Middleware Configuring Log Files and Filtering Log Messages for Oracle WebLogic Server.
After you have compiled your application successfully, you can then deploy the application on the Oracle WebLogic Server environment you installed and configured earlier.
You can redeploy your Java EE applications using any of the following typical tools:
WLST, the Oracle WebLogic Server scripting tool
The Oracle WebLogic Administration Console
For more information, see Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.
After you have deployed your Java EE applications on Oracle WebLogic Server, you can verify the applications by doing the following:
Log in to the Oracle WebLogic Administration Console and review the deployments on the domain. You can also perform various monitoring tasks and post-deployment tasks from the console.
Navigate in your browser to the application URL and verify that the features of the application are working as they did when you verified them on OC4J earlier in this procedure.
If find any problems with the application, review the domain log files to diagnose the problem. For more information, see "Configuring Log Files and Filtering Log Messages" in the Oracle WebLogic Server documentation library.