3 Migrating Java Servlets

This chapter provides the information you need to migrate Java servlets from WebLogic Server to Oracle Application Server. It covers the migration of simple servlets, WAR files, and exploded Web applications.

This chapter contains these topics:

• Section 3.1, "Introduction"

• Section 3.2, "Migration Approach for Servlets"

• Section 3.3, "Migrating a Simple Servlet"

• Section 3.4, "Migrating a WAR File"

• Section 3.5, "Migrating an Exploded Web Application"

• Section 3.6, "Migrating Configuration and Deployment Descriptors"

• Section 3.7, "Migrating Cluster Aware Applications"

3.1 Introduction

Migrating Java servlets from WebLogic Server to Oracle Application Server is straightforward, requiring little or no code changes to the servlets migrated.

Oracle Application Server 10g Release 3 (10.1.3) is fully compliant with Sun Microsystem's J2EE Servlet specification, version 2.4. WebLogic Server 8.1 is compatible with version 2.3. However, Oracle Application Server 10g Release 3 (10.1.3) is backward compatible to Servlet 2.3. Hence, servlets written to the standard 2.3 specification should work correctly in Oracle Application Server and require minimal migration effort.

The primary tasks involved in migrating servlets to a new environment are configuration and deployment. The use of proprietary extensions, such as htmlKona, will require additional tasks and complicate the migration effort.

The tasks involved in migrating servlets also depend on how the servlets have been packaged and deployed. Servlets can be deployed as a simple servlet, as a Web application packaged with other resources in a standard directory structure, or as a Web archive (WAR) file.

3.2 Migration Approach for Servlets

Migrating servlets to OC4J is a straightforward process using the following overall steps:

1. Configuration - Create or modify the Oracle Application Server deployment descriptors for the servlets.

2. Packaging:

   • Simple servlets can be deployed individually (see Section 3.3).

   • Servlets can be packaged as part of a Web application in a WAR file (see Section 3.4).

3. Deployment - Application Server Control Console can be used to deploy servlets in a WAR file. Individual servlets and servlets in exploded Web applications can be deployed automatically by copying them to the appropriate directories.

Note: Oracle JDeveloper provides tools and wizards to automate all the above.

Servlet Migration Issues

The following are possible issues you may face during servlet migration:

• Earlier versions of WebLogic Server (6.0) Servlet 2.3 implementation is based on non-finalized Servlet 2.3 specification, which may require some code upgrade to use the finalized Servlet 2.3 API, which is the highest level specification supported by WebLogic Server 8.1. Oracle Application Server 10g Release 3 (10.1.3) supports Servlet 2.4 and is backward compatible to Servlet 2.3. Hence, WebLogic Server 6.0 and earlier servlets should be upgraded to the Servlet 2.3 API before being deployed in Oracle Application Server.

• Setting up HttpSession persistence varies between both Weblogic and OC4J.

• Proprietary server extensions (WebLogic htmlKona) need to be rewritten.

• If a servlet in WebLogic Server performs JNDI lookups to resources in applications other than its own, it may cause a NameNotFoundException when performing the same lookup after it is migrated to OC4J. This exception occurs if OC4J is not configured for global JNDI lookup. Refer to Section 5.1.2.1, "Global JNDI Lookups and Oracle Application Server" for a resolution.

3.3 Migrating a Simple Servlet

Simple servlets are easily configured and deployed in OC4J. The manual process used to deploy a servlet is the same in both WebLogic Server and OC4J.

Note: The recommended and preferred way to deploy a servlet is by packaging it in a WAR or EAR file and using Oracle Enterprise Manager 10g Application Server Control Console or the dcmctl command line utility. . The manual processes described in this chapter of editing XML files and starting OC4J at the command line using the java command should preferably be used in a development environment.

A servlet must be registered and configured as part of a Web application. To register and configure a servlet, several entries must be added to the Web application deployment descriptor.

The overall steps to deploy a simple servlet are as follows (detailed steps are in Table 3-1):

1. Update the Web application deployment descriptor (web.xml) with the name of the servlet class and the URL pattern used to resolve requests for the servlet.

2. Copy the servlet class file to the WEB-INF/classes/ directory. If the servlet class file contains a package statement, create additional subdirectories for each level of the package statement. The servlet class file must then be placed in the lowest subdirectory created for that package.

3. Copy other supporting files required by the servlet to the appropriate directory in the Oracle Application Server installation.

4. Invoke the servlet from your browser by entering its URL.

To determine the effort involved in migrating servlets, we selected and migrated example servlets provided with WebLogic Server. We chose examples that did not use proprietary extensions.

Table 3-1 presents the manual process for migrating a simple servlet, HelloWorld, from WebLogic Server to Oracle Application Server OC4J.

Table 3-1 Migrating a Simple Servlet

Step	Description	Process
1	Modify the Web application deployment descriptor	Add the descriptor information below to the web.xml file located in the following directory in your Oracle Application Server installation: For UNIX, web.xml can be found in: <ORACLE_HOME>/j2ee/home/default-web-app/WEB-INF/ For Windows, web.xml can be found in: <ORACLE_HOME>\j2ee\home\default-web-app\WEB-INF\ The descriptor information to be entered is: <servlet>   <servlet-name>    HelloWorldServlet   </servlet-name>   <servlet-class>    examples.servlets.HelloWorldServlet   </servlet-class> </servlet> <servlet-mapping>   <servlet-name>    HelloWorldServlet   </servlet-name>   <url-pattern>    /HelloWorldMigrate/*   </url-pattern> </servlet-mapping>
2	Copy the servlet class file to the appropriate directory	After building and running successfully the samples that came with WebLogic Server, copy HelloWorldServlet.class from a directory in your WebLogic Server installation to the appropriate directory in Oracle Application Server as follows: In UNIX, from: <BEA_HOME>/weblogic81/samples/server/examples/build/ examplesWebApp/WEB-INF/classes/examples/servlets/ to: <ORACLE_HOME>/j2ee/home/default-web-app/WEB-INF/ classes/examples/servlets/ In Windows, from: <BEA_HOME>\weblogic81\samples\server\examples\build\ examplesWebApp\WEB-INF\classes\examples\servlets\ to: <ORACLE_HOME>\j2ee\home\default-web-app\WEB-INF\ classes\examples\servlets\ NOTE: This servlet provided with the WebLogic Server installation belongs to a package called examples.servlets. When copying its class file to Oracle Application Server, you need to create the corresponding package subdirectories (examples/servlets/).
3	Extract and copy the supporting utility class file required by the servlet.	HelloWorldServlet.class imports a utility class, ExampleUtils.class, found in the JAR file, utils_common.jar, in the WebLogic Server installation. This utility class needs to be copied to your Oracle Application Server installation. ExampleUtils.class can be found in the following location: (UNIX) <BEA_HOME>/weblogic81/samples/server/examples/build/ examplesWebApp/WEB-INF/lib/utils_common.jar (Windows) <BEA_HOME>\weblogic81\samples\server\examples\build\ examplesWebApp\WEB-INF\lib\utils_common.jar Extract ExampleUtils.class to: (UNIX): <ORACLE_HOME>/j2ee/home/default-web-app/WEB-INF/classes/ (Windows): <ORACLE_HOME>\j2ee\home\default-web-app\WEB-INF\classes\ Note: The examples/utils/common directory is created from the extraction.
4	Restart the home OC4J "home" instance, or start it if it is not currently running	Use the Oracle Enterprise Manager 10g Application Server Control Console administration Web pages or the following opmnctl command (executed locally): opmnctl @instance restartproc ias-component=OC4J
5	Run the servlet from your Web browser	Access the servlet from your Web browser using the URL http://localhost:7777/j2ee/HelloWorldMigrate (Substitute "localhost" with your OC4J instance's host name if using the browser from another machine.)

See Also: Oracle Application Server Containers for J2EE Servlet Developer's Guide for detailed information on configuring and deploying servlets.

3.4 Migrating a WAR File

A Web application can be configured and deployed as a WAR file. This is easily accomplished in OC4J by using the Application Server Control Console administration GUI or manually copying the WAR file to the appropriate directory. This is also true for WebLogic Server. We will illustrate the process using Application Server Control Console to deploy an example WAR file from WebLogic Server.

Note: Manually copying a WAR file to the appropriate directory to deploy it should only be done in a development environment where OC4J is in standalone mode (not a component of an Oracle Application Server instance).

Production Web applications are typically deployed using WAR or EAR files through Application Server Control Console or the utility. During the development of a Web application, it may be faster to deploy and test edited code using an exploded directory format (see Section 3.5).

Table 3-2 presents the typical process for migrating a WAR file from WebLogic Server to OC4J.

Table 3-2 Migrating a WAR File

Step	Description	Process
1	Create the WAR file for the sample application.	If you have not run all the WebLogic Server samples that came with that product, build the cookie sample Web application in the following WebLogic Server directory (UNIX is shown but Windows has equivalent directory structure): <BEA_HOME>/weblogic81/samples/server/examples/src/ examples/webapp/cookie In this directory, build the application by typing <BEA_HOME>/ant/weblogic81/server/bin/ant When built, a WAR file for this application, cookie.war, is created in the following directory: <BEA_HOME>/weblogic81/samples/domains/examples/ applications/
2	Deploy the sample application to Oracle Application Server.	On the machine where the cookie.war file is located, open a browser and go to the Application Server Control Console URL of your Oracle Application Server installation. For example: http://<hostname>:7777/em where <hostname> is the qualified name of the host where Oracle Application Server is installed. Enter your administrator username (oc4jadmin) and password if prompted. Click the "+" icon of the Oracle Application Server instance you want to deploy the WAR file to. Click the home OC4J component, which brings up its settings page. Click "Applications" and then the "Deploy" button. The "Deploy: Select Archive" page appears. Select "Archive is present on local host." Click the "Browse" button and enter the location of the cookie.war file. For deployment plan, leave the selection to automatically create a deployment plan. Click Next. The "Deploy: Application Attributes" page appears. In the "Application Name" and "Context Root" text boxes, enter "cookie" and "/cookie" respectively. Click Next. The "Deploy: Deployment Settings" page appears. Click Deploy. A page showing the deployment progress appears. A success message appears if the deployment is successful. If an error occurs, view the progress messages and attempt to troubleshoot the problems logged. Click Return. The home settings page appears, and the cookie application should appear in the list of deployed applications.
3	Test the deployed application.	In a browser, enter the following URL: http://<hostname>:7777/cookie where <hostname> is the Oracle Application Server host where you deployed the cookie WAR file.

See Also: Oracle Application Server Containers for J2EE Servlet Developer's Guide and Oracle Application Server Containers for J2EE User's Guide for more detailed information on deploying WAR and EAR files.

3.5 Migrating an Exploded Web Application

Web applications can also be configured and deployed as a collection of files stored in a standard directory structure or exploded directory format. This can be accomplished in OC4J by manually copying the contents of the standard directory structure to the appropriate directory in the OC4J installation. The same method can also be used for WebLogic Server. In this section, we will describe the manual process for deploying an exploded Web application.

See Also: Oracle Application Server Administrator's Guide for detailed information on using the Application Server Control Console GUI.

Deploying a Web application in exploded directory format is used primarily during the development of a Web application. It provides a fast and easy way to deploy and test changes. When deploying a production Web application, package the Web application in a WAR file and deploy the WAR file using Application Server Control Console.

WebLogic Server

To manually deploy an exploded Web application in WebLogic Server (development mode), copy the top-level directory containing the exploded Web application files into the following directories of your WebLogic Server installation:

(UNIX) <BEA_HOME>/user_projects/domains/<domain_name>/applications (Windows) <BEA_HOME>\user_projects\domains\<domain_name>\applications

For WebLogic Server 7.0 - Once the top-level directory is copied to the appropriate directory, create an empty file with the name "REDEPLOY" within the top-level directory. WebLogic Server detects this file and deploys the Web application. (WebLogic Server reads the timestamp of this file every few minutes to determine if the application needs redeploying. Hence, whenever an application file is updated, the REDEPLOY file's timestamp has to be updated to redeploy the file. In UNIX, this can be done by using the touch command.)

For WebLogic Server 8.1 - When WebLogic Server is running in development mode, any exploded directory files placed in the abovementioned directory is automatically deployed. There is no need to create the "REDEPLOY" file as for version 7.0.

Oracle Application Server

Manually deploying an exploded Web application in OC4J varies slightly. Copy the top-level directory containing the exploded Web application into the following directory of your OC4J installation:

(UNIX) <ORACLE_HOME>/j2ee/home/applications (Windows) <ORACLE_HOME>\j2ee\home\applications

Then, modify the following application deployment descriptor to include the Web application:

(UNIX) <ORACLE_HOME>/config/application.xml (Windows) <ORACLE_HOME>\config\application.xml

Bind the Web application to your Web site by adding an entry in the following descriptor file:

(UNIX) <ORACLE_HOME>/config/default-web-site.xml (Windows) <ORACLE_HOME>\config\default-web-site.xml

Finally, register the new application by adding a new <application> tag entry in the following files:

(UNIX) <ORACLE_HOME>/config/server.xml (Windows) <ORACLE_HOME>\config\server.xml

When you modify server.xml and save it, OC4J detects the timestamp change of this file and deploys the application automatically. OC4J need not be restarted.

3.6 Migrating Configuration and Deployment Descriptors

Since WebLogic Server and Oracle Application Server fully support J2EE 1.4, there is a standard set of XML configuration files supported by both application servers. These are:

• web.xml (found in the WEB-INF directory of a Web application's WAR file)

• application.xml (found in the META-INF directory of a Web application's WAR file)

• ejb-jar.xml (found in the META-INF directory of an EJB module's exploded directory hierarchy)

In addition to the standard files, each application server has specific files used only by their respective environments. These are:

3.6.1 Oracle Application Server

• server.xml Found in

  (UNIX) <ORACLE_HOME>/j2ee/home/config/(Windows) <ORACLE_HOME>\j2ee\home\config\

  This is the overall OC4J runtime configuration file. It defines attributes such as the deployed applications directory, the server log file path and name, path and names of other XML files, names of applications and their EAR files, paths to runtime libraries, and so on.

• application.xml Found in

  (UNIX) <ORACLE_HOME>/j2ee/home/config\(Windows) <ORACLE_HOME>\j2ee\home\config\

  This is the global configuration file common settings for all applications deployed on a particular OC4J installation. Note that this is different from the application.xml in a J2EE WAR file.

• <website_name>-web-site.xml Found in

  (UNIX) <ORACLE_HOME>/j2ee/home/config\(Windows) <ORACLE_HOME>\j2ee\home\config\

  This file defines a Web site and specifies attributes such as host name, HTTP listener port number, Web applications it services and their URL contexts, and HTTP access log file and path. Note that the name and path of each *-web-site.xml file has to be specified in the server.xml file for OC4J to configure the defined Web site at runtime.

• data-sources.xml Found in

  (UNIX) <ORACLE_HOME>/j2ee/home/config/(Windows) <ORACLE_HOME>\j2ee\home\config\

  This file contains configuration information for data sources used by the OC4J runtime. Information in this file include: JDBC drivers used, JNDI binding for each data source, username and password for each data source, database schemas to use, maximum connections to each database, and time out values.

• principals.xml Found in

  (UNIX) <ORACLE_HOME>/j2ee/home/config/(Windows) <ORACLE_HOME>\j2ee\home\config\

  This file contains the user repository for the default XMLUserManager class. Groups, users belonging to them, and group permissions are defined in this file. The mapping of groups to roles is defined in the global application.xml file.

• orion-application.xml Found in

  UNIX: <ORACLE_HOME>/j2ee/home/application-deployments/<app_name>

  or

  Windows: <ORACLE_HOME>\j2ee\home\application-deployments\<app_name>

  This file contains OC4J-specific information for an application (<app_name>) deployed on an OC4J installation. Web and EJB module names and security information for the application are included in the file. This file is generated by OC4J at deploy time.

• global-web-application.xml Found in

  (UNIX) <ORACLE_HOME>/j2ee/home/config/(Windows) <ORACLE_HOME>\j2ee\home\config\

  This file contains servlet configuration information used internally by the OC4J runtime. An example is the JSP translator servlet.

• orion-web.xml Found in

  UNIX: <ORACLE_HOME>/j2ee/home/application-deployments/<app_name>/<web_app_name>/

  or

  Windows: <ORACLE_HOME>\j2ee\home\application-deployments\<app_name>\<web_app_name>\

  OC4J internal JSP and servlet information for <web_app_name> is specified in this file. This file is generated by OC4J at deploy time.

• orion-ejb-jar.xml Found in

  UNIX: <ORACLE_HOME>/j2ee/home/application-deployments/<app_name>/<ejb_jarfile_name>/

  or

  Windows: <ORACLE_HOME>\j2ee\home\application-deployments\<app_name>\<ejb_jarfile_name>\

  This file contains OC4J internal deployment information for EJBs in the JAR file specified by <ejb_jarfile_name> belonging to the application <app_name>. This file is generated by OC4J at deploy time.

• oc4j-connectors.xml Found in

  (UNIX) <ORACLE_HOME>/j2ee/home/config/(Windows) <ORACLE_HOME>\j2ee\home\config\

  This file contains connector information for the OC4J installation.

3.6.2 WebLogic Server

• config.xml Found in

  (UNIX) <BEA_HOME>/config/<domain_name>/(Windows) <BEA_HOME>\config\<domain_name>\

  This file contains configuration information for an entire WebLogic Server domain. Information specified in this file include the domain administration server's host name and admin port number, JNDI mappings to data sources, JDBC connection pool information, applications deployed to all nodes in the domain, SSL certificate information,

• weblogic.xml Found in

  UNIX: <BEA_HOME>/config/<domain_name>/applications/<web_app_name>/WEB_INF/

  or

  Windows: <BEA_HOME>\config\<domain_name>\applications\<web_app_name>\WEB_INF\

  This file defines JSP properties, JNDI mappings, resource references, security role mappings, and HTTP session and cookie parameters for a Web application. This file is WebLogic Server-specific but is created manually.

• weblogic-ejb-jar.xml Found in an EJB module's META-INF subdirectory. This file maps WebLogic Server resources to EJBs. These resources include security role names, data sources, JMS connections, and other EJBs. This file also has performance attributes for caching and clustering for the EJBs defined in the corresponding ejb-jar.xml file.

  
  

  Note: The files mentioned above are not an exhaustive list of all XML configuration file used by each application server. They are files which are relevant to the configuration and deployment of servlet applications. Other XML files also exist to configure components such as HTTP listeners, RMI, security.

  
  

3.7 Migrating Cluster Aware Applications

Oracle Application Server provides more comprehensive clustering features than WebLogic Server.

WebLogic Server provides two primary cluster services, HTTP session state clustering and object clustering. The focus of this section is on HTTP session state clustering or Web application clustering.

WebLogic Server supports clustering for servlets and JSP pages by replicating the HTTP session state of clients accessing clustered servlets and JSP pages. To benefit from HTTP session state clustering, you must ensure that the HTTP session state is persistent by configuring either in-memory replication, file system persistence, or JDBC persistence.

Oracle Application Server provides clustering support similar to that of WebLogic Server. In addition, Oracle Application Server provides:

• Servlet Clustering—OC4J provides facilities to cluster servlets without requiring any changes to the Web application. The changes necessary are deployment configuration modifications that are transparent to the Web application and allows session fail over to multiple OC4J processes.

• Clustering Architecture and Simplicity—An important differentiator for Oracle Application Server is the ease with which different instances can be clustered and the robustness of the architecture used for clustering.

• Clustering Simplicity—Oracle Enterprise Manager 10g Application Server Control Console provides a GUI to configure various OracleAS instances to belong to a single cluster, whether they are multiple servers with load balancing on a single machine or on different machines. Alternatively, you can also edit a single XML file. In contrast, it is more complex to configure WebLogic Server clusters with load balancing either with multiple instances on one machine or on multiple machines.

• Superior Clustering Architecture—OC4J uses dynamic IP addresses to register instances as part of a cluster. Any standard load balancer such as Cisco Local Director or BigIP has the ability to use a variety of load balancing mechanisms to route requests to different Oracle Application Server instances. Additionally, mod_oc4j intelligently routes requests from Oracle HTTP Server to OC4J processes using one of several load balancing algorithms. In contrast, WebLogic Server uses static IP addresses to configure clustering. Static IP addresses preclude the use of a load balancer to distribute requests across instances. As a result, you get either clustering or load balancing with WebLogic Server but not both.

  
  

  See Also: Oracle Application Server High Availability Guide and Oracle Application Server Containers for J2EE Configuration and Administration Guide