3
Migrating Java Servlets

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

This chapter contains these topics:

• Introduction

• Migrating a Simple Servlet

• Migrating Configuration and Deployment Descriptors

• Migrating a WAR File

• Migrating an Exploded Web Application

• Migrating Cluster Aware Applications

Introduction

Migrating Java servlets from WebLogic Server 6.0 to Oracle9iAS is typically straight forward, requiring little or no code changes to the servlets migrated.

Both application servers are fully compliant with Sun Microsystem's Java 2 Servlet Specification, version 2.2. All servlets written to the standard specification will work correctly 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.

Differences Between WebLogic Server and Oracle9iAS Servlet Implementations

Oracle9iAS and WebLogic Server both support the Servlet 2.2 specification. Additionally, Oracle9iAS fully supports the finalized Servlet 2.3 specification. WebLogic Server has Servlet 2.3 support, but its implementation is based on non-finalized Servlet 2.3 specification. Hence, migrating a servlet that uses the WebLogic Server Servlet 2.3 API and features to Oracle9iAS may require some code upgrade to use the finalized Servlet 2.3 API.

OC4J Key Servlet Container Features

One of the key distinguishing features of OC4J is the seamless integration with Single Sign-On (SSO) and Oracle Internet Directory (OID). This is achieved through Oracle's implementation of the Java Authentication and Authorization Service (JAAS) standard - JAAS provider is integrated with OC4J.

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 OEM 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 be used for development purposes and for discussion in this chapter only.

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. 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 6.0. 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 6.0 to OC4J.

Table 3-1 Migrating a Simple Servlet  

Step	Description	Process
1	Modify the web application deployment descriptor	Add the following to the web.xml file located in the j2ee/home/default-web-app/WEB-INF/ directory of your OC4J installation: <servlet>   <servlet-name>    HelloWorldServlet   </servlet-name>   <servlet-class>    examples.servlets.HelloWorldServlet   </servlet-class> </servlet> <servlet-mapping>   <servlet-name>    HelloWorldServlet   </servlet-name>   <url-pattern>    /HelloWorld/*   </url-pattern> </servlet-mapping> Save the changes to the web.xml file
2	Copy the servlet class file to the appropriate directory	Copy HelloWorldServlet.class from the wlserver6.0/config/examples/ applications/examplesWebApp/ WEB-INF/classes/examples/servlets/ directory of your WebLogic Server installation to the j2ee/home/default-web-app/WEB-INF/ classes/examples/servlets/ directory of your OC4J installation NOTE: This servlet provided with the WebLogic Server installation belongs to a package called examples.servlets.
3	Start the OC4J J2EE application server, if not currently running	Use the OEM administration web pages or the following dcmctl command: dcmctl start -i 9ias_instance_name -ct oc4j -co oc4j_instance_name where 9ias_instance_name is the name of your Oracle9iAS instance and oc4j_instance_name is the name of the OC4J instance you want to start
4	Run the servlet from your web browser	Access the servlet from your web browser using the URL http://localhost:7777/HelloWorld (Substitute "localhost" with your OC4J's host name if using the browser from another machine.)

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

Migrating a WAR File

WAR files are also easily migrated to OC4J.

A web application can be configured and deployed as a WAR file. This is easily accomplished in OC4J by using the Oracle Enterprise Manager administration GUI or manually copying the WAR file to the appropriate directory. This is also true for WebLogic Server. We will illustrate here the manual process for deploying WAR files. This manual process should only be used in development environments where OC4J is in standalone mode (not a component of an Oracle9iAS instance).

See Also: Oracle9i Application Server Administrator's Guide and Oracle Enterprise Manager Administrator's Guide for detailed information on using the Oracle Enterprise Manager administration screens.

Production web applications are typically deployed using WAR or EAR files through OEM or the dcmctl utility. Also, during the development of a web application, it may be faster to deploy and test edited code using an exploded directory format.

To deploy a WAR file in WebLogic Server, copy the WAR file into the config/<domain_name>/applications directory of your WebLogic Server installation. Once the WAR file is in this directory, WebLogic Server automatically deploys the web application (auto-deployment must be enabled for the domain and the Administration Server must be running).

Deploying a WAR file in OC4J is slightly different. Copy the WAR file into the <ORACLE_HOME>/j2ee/home/applications directory of your OC4J installation. Then, modify the application deployment descriptor found in <ORACLE_HOME>/config/application.xml to include the WAR file. Bind the web application to your web site by adding an entry in <ORACLE_HOME>/config/default-web-site.xml.

Instead of manually editing these XML files, you can also use the admin.jar utility. Refer to the Oracle9iAS Containers for J2EE User's Guide for more details.

However, when either of these methods are used, the other Oracle9iAS components, Distributed Configuration Manager and Oracle Process Management Notification service, are not aware of the changes. Hence, the best way would be to use Oracle Enterprise Manager or dcmctl utility to deploy the WAR file.

For OC4J to automatically deploy a web application, the web application must be packaged in an EAR file. Create a WAR file for the web application and package the WAR file inside an EAR file. When you modify server.xml (one of the descriptor files you need to modify) and save it, OC4J detects the timestamp change of the EAR file and deploys the application automatically. OC4J need not be restarted.

Note: When you package the WAR file in a EAR file, the J2EE specified manifest file (for the enterprise archive) META-INF/application.xml must be added to the EAR file. This manifest file may have to be created manually. See instructions below for an example of this file.

To determine the effort involved in migrating web applications packaged as WAR files, we selected and migrated example web applications provided with WebLogic Server 6.0. We chose examples that did not use proprietary extensions.

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

Table 3-2 Migrating a WAR File  

Step	Description	Process
1	Modify the appropriate application deployment descriptor and save the changes	Add the following to the application.xml file located in the j2ee/home/config/ directory of your OC4J installation: <web-module id="cookie" path="..home/applications/cookie/ cookie.war" /> Save the changes to the application.xml file
2	Modify the appropriate *-web-site.xml file and save the changes	Add the following to the http-web-site.xml file located in the j2ee/home/config directory of your OC4J installation: <web-app application="cookie" name="cookie" root="/cookie" />
3	Modify server.xml	Add the following to j2ee/home/config/server.xml: <application name="cookie" path="../applications/cookie.ear" /> There is no need to restart OC4J as it should pick up the new timestamp on this file automatically.
4	Prepare application files for archival to EAR file	Create a staging directory to perform the EAR file archival. Assuming you deployed the cookie example in the "examples" domain of WebLogic Server, copy cookie.war from the <WL_HOME>/wlserver6.0/config/examples/ applications/ directory of your WebLogic Server installation into this staging directory. Create a subdirectory META-INF in this staging directory and create a file called application.xml in META-INF. This acts as the manifest file for the EAR and should look like the following: <?xml version="1.0"?> <!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.2//EN" "http://java.sun.com/j2ee/dtds/ application_1_2.dtd"> <application>   <module>    <web>     <web-uri>cookie.war</web-uri>     <context-root>/cookie</context-root>    </web>   </module> </application> In the same directory level as META-INF, run the jar archive utility: jar cvfM cookie.ear *
5	Copy the EAR file to the appropriate directory	Copy cookie.ear from the staging directory to j2ee/home/applications/ directory of your Oracle9iAS installation. If OC4J is running, it will detect the new EAR file and automatically deploy it. If it is not running, use the OEM administration web pages or the following dcmctl command: dcmctl start -i 9ias_instance_name -ct oc4j -co oc4j_instance_name where 9ias_instance_name is the name of your Oracle9iAS instance and oc4j_instance_name is the name of the OC4J instance you want to start.
6	Invoke the web application from your web browser	Invoke the web application from your web browser using the URL http://localhost:7777/cookie (Substitute "localhost" with your OC4J's host name if using the browser from another machine.)

See Also: Oracle9iAS Containers for J2EE Servlet Developer's Guide and Oracle9iAS Containers for J2EE User's Guide for detailed information on deploying WAR files.

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: Oracle9i Application Server Administrator's Guide for detailed information on using the Oracle Enterprise Manager administration 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 OEM.

To manually deploy an exploded web application in WebLogic Server, copy the top-level directory containing the exploded web application files into the <WL_HOME>/config/<domain_name>/applications directory of your WebLogic Server installation. 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.)

Manually deploying an exploded web application in OC4J varies slightly. Copy the top-level directory containing the exploded web application into the <ORACLE_HOME>/j2ee/home/applications directory of your OC4J installation. Then, modify the application deployment descriptor found in <ORACLE_HOME>/config/application.xml to include the web application. Bind the web application to your web site by adding an entry in <ORACLE_HOME>/config/default-web-site.xml (or the appropriate website XML file). Finally, register the new application in <ORACLE_HOME>/config/server.xml by adding a new <application> tag entry. 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.

Migrating Configuration and Deployment Descriptors

Since WebLogic Server and Oracle9iAS fully support J2EE 1.2, 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:

Oracle9iAS

• server.xml
Found in 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, etc.

• application.xml
Found in 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 j2ee/home/config. This file defines a website 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 website at runtime.

• data-sources.xml
Found in 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 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 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 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 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 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 j2ee/home/config/. This file contains connector information for the OC4J installation.

WebLogic Server 6.0

• config.xml
Found in <WL_HOME>/config/<domain_name>/config.xml. 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 <WL_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.

Migrating Cluster Aware Applications

OC4J provides clustering features that are superior to WebLogic Server in both performance and ease of use.

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, filesystem persistence, or JDBC persistence.

Oracle9iAS provides clustering support similar to that of WebLogic Server. In addition, Oracle9iAS 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.

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

• Clustering Simplicity--Oracle Enterprise Manager (OEM) provides a GUI to configure various Oracle9iAS 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. Its built-in load balancer, or any standard load balancer such as Cisco Local Director or BigIP, has the ability to use a variety of load balancing algorithms to route requests to different instances. 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.

Each Oracle9iAS farm consists of multiple OC4J islands and each island can consist of multiple applications. The sharing of session state for failover is within a particular island.

Use the following steps to configure Oracle9iAS clustering:

Note: These steps illustrate the manual method of editing XML files to configure Oracle9iAS. OEM provides a graphical interface to manage Oracle9iAS and provides a better view of the entire system. Refer to the Oracle9i Application Server Administrator's Guide for instructions on how to use OEM.

1. Install the web application on all nodes in the cluster

   Verify that the web application is installed on all nodes in the cluster. To avoid duplication of the web application, place the web application on a drive shared by the appropriate servers. Start all nodes and verify that the web application works correctly on all nodes.

2. Set up the web application to replicate its state

   Edit the OC4J specific deployment descriptor for the web application located at j2ee/home/application-deployments/<application-name>/ <web-app-name>/orion-web.xml. If clustering is to be configured for all web applications on a web site, edit the OC4J-specific deployment descriptor for the global web application located at j2ee/home/config/global-web-application.xml. Edit either file by adding the <cluster-config/> tag after the main body of the <orion-web-app> tag.

   Optionally you may:

   • Specify the multicast host/IP address to transmit and receive cluster data

   • Specify the port to transmit and receive cluster data (default port is 9127)

   • Specify the id (number) of the node to identify itself with in the cluster (default is based on the IP address of the local machine)

   Repeat step 2 for all the nodes in the cluster. As a result, the following will be replicated:

   • The HttpSession data (as long as it is serializable or an EJB reference). Note, however, that if the EJBs are located on a server that goes down, the references might become invalid.

   • The ServletContext data

   It is important to understand that load balancing is providing load balancing for the web component, not the EJB. When using multiple islands, you may want to use different multicast IP addresses to enable "smart" routing of multicast packets in your network and just send traffic on certain IP addresses to certain servers.

3. Configure the OC4J islands

   OC4J islands are connected to a certain web site rather than to a web application. To configure an island, edit the deployment descriptor of the web site that the web application is deployed on. For example, if the web application is deployed on the default web site, edit the deployment descriptor located at j2ee/home/config/default-web-site.xml. Edit the file by adding cluster-island="1" to the <web-site> tag. If the cluster has more than one island, specify different island values for servers that belong to different islands and similar values for those in the same island. Remember, HTTP session state is shared only within an island.

   Obtaining the IP address of the local host is not reliable on all platforms. The back-end needs to tell the front-end about its IP address in some other way. This is accomplished by specifying the host using the host="host/ip" attribute in the <web-site> tag of the same deployment descriptor modified earlier in this step.

4. Tell the back-end about the load balancer

   To specify where the load balancer for the web site is located, edit the same deployment descriptor modified in Step 3 by adding the following tag in the main body of the <web-site> tag:

   <frontend host="balancer-host" port="balancer-port" />
   

   balancer-host is the hostname of the server where the load balancer is running and balancer-port is the port number of the load balancer. As this host and port make up the public hostname for the site, port 80 is suggested.

5. Make the web application distributable

   To indicate that a web application is distributable, edit the web application deployment descriptor located in WEB-INF/web.xml. Add the </distributable> tag to the deployment descriptor. For example:

   <web-app>
   ...
      <distributable/>
   ...
   </web-app>
   
   

6. Test the Oracle9iAS configuration

   Access the load balancer's host and port using a web browser. Notice how the request is sent off to one of the back-end servers. Now, request the same page from the same client. More than likely, you will be sent to the same back-end node, but if the same page is requested from a different client, you will see that this client request gets balanced across to another node.

   To test state replication, request servlet/SessionServlet. Determine which server has become the primary server for the session by looking at the access logs. Shut that server down and request the SessionServlet again. If the Oracle9iAS configuration is correct, you will get to the same session as before but on a different node and the counter will be updated appropriately.

   See Also: "Oracle9iAS Support for Clustering and Load Balancing" of this book and the Oracle9iAS Containers for J2EE User's Guide.