2
Migrating JWeb & JServlet Applications to OC4J

This chapter discusses migration of JWeb and JServlet applications from Oracle Application Server to OC4J in the Oracle9iAS. Topics include:

• JWeb and OC4J Differences

• Migration Strategies

• Code Modifications for JWeb Applications

JWeb and OC4J Differences

This section provides background information on JWeb and OC4J. It also describes the differences between JWeb and OC4J applications.

Architecture

JWeb applications execute within the Oracle Application Server cartridge infrastructure, while OC4J runs on a standard Virtual Machine.

JWeb Architecture

In Oracle Application Server, the HTTP listener receives a request for a JWeb cartridge. The listener passes the request to the dispatcher, which communicates with the Security or Web Request Broker (WRB). The WRB uses a URL mapping to identify the cartridge instance to which the request should be sent. If no cartridge instances exist for the requested cartridge, the cartridge server factory creates a cartridge server process to instantiate the cartridge. In JWeb, the cartridge server process loads a JVM, which runs a JWeb application (of the Oracle Application Server application paradigm). Figure 2-1 depicts these components graphically.

Figure 2-1 Oracle Application Server Cartridge Infrastructure

Text description of the illustration jweba.gif

OC4J Architecture

OC4J consists of a Web container including servlet and JSP engines, EJB container, J2EE services APIs (JNDI, JTA, JMS, and JAAS), and enterprise information systems APIs (JDBC, SQLJ, J2EE connector architecture).

mod_oc4j is a dynamically loaded module of Oracle HTTP Server with the purpose of routing requests through Oracle HTTP Server to OC4J processes. mod_oc4j takes into account OC4J sessions information to route requests back to the original OC4J process and to re-route failed session requests to other members of the same OC4J Island when the original OC4J process is unreachable.

The mod_oc4j interacts with two components, Oracle Process Manager and Notification System (OPMN) and OC4J. The mod_oc4j interacts with OC4J by routing requests to it. OPMN starts Oracle HTTP Server, which starts mod_oc4j, and starts all OC4J processes. OPMN monitors each process that it starts and periodically verifies that each process is reachable. If a process dies, or becomes unreachable, OPMN will restart that process. In addition, OPMN communicates OC4J process status to mod_oc4j so that mod_oc4j knows when OC4J processes are started and stopped. The mod_oc4j uses this information to maintain an internal OC4J process table for rapid request routing.

See Also: Oracle9iAS Containers for J2EE User's Guide in the Oracle9iAS Documentation Library

Figure 2-2 illustrates a one-to-many configuration. A one-to-many configuration, consists of one Oracle HTTP Server listner and multiple OC4J instances. In Figure 2-2, a single OC4J instance is communicating with two OC4J hosts. OC4J Host 1 is running two servlet containers, and OC4J Host 2 is running one servlet container. Three connections are open between the servlet containers and a single mod_oc4j in the OC4J instance.

A servlet container provides the runtime environment to execute servlets implementing the Servlet 2.3 Application Programming Interface (API) specifications. It runs in a JVM process in the same or different host as the OC4J. Each JVM has one servlet container, and the number of servlet containers is not proportional to the number of Web servers (mod_oc4j modules). One mod_oc4j can work with more than one servlet container and vice versa. Or, multiple mod_oc4j modules can work with multiple servlet containers.

Figure 2-2 AOC4J Architecture (one-to-many example)

Text description of the illustration jweb2.gif

Single Host Configuration

When a servlet container is located on the same machine as the Web server, you can set up the mod_oc4j module to start or stop the servlet container and JVM when the Web server starts or stops, respectively. The module performs all the necessary tasks to gracefully shut down the JVM. In this scenario, mod_oc4j can also perform failover by checking JVM status regularly and starting another JVM if the first one becomes unavailable.

Life cycle

JWeb classes and OC4J applications have different life cycles.

JWeb Life Cycle

JWeb classes use the standard main() entry point to start their execution logic. Their life cycle resembles that of a standard Java class in loading, linking, initializing, and invoking main().

See Also: Information on Java Virtual Machines from http://java.sun.com/docs

OC4J Life Cycle

In OC4J, Servlet life cycle is in compliance with Servlet 2.3 specifications. The life cycle is defined by the javax.servlet.Servlet interface, which is implemented directly or indirectly by all servlets. This interface has methods which are called at specific times by the servlet engine in a particular order during a servlet's lifecycle. The init() and destroy() methods are invoked once per servlet lifetime, while the service() method is called multiple times to execute the Servlet's logic.

Figure 2-3 illustrates the servlet life cycle.

Figure 2-3 Servlet Life Cycle

Text description of the illustration jweb3.gif

Threading

The JWeb cartridge and OC4J servlet container support single or multiple threads of execution, but the threading implementations are different.

JWeb Threading

Threading for the JWeb cartridge is defined in the Oracle Application Server cartridge configuration by toggling the Stateless parameter. If the stateless parameter is set to true, then a cartridge instance is shared by more than one client. If the stateless perimeter is set to false, then it is not shared, and only one client can access it at any one time. Also, if Oracle Application Server is in min/max mode, the min/max cartridge servers and min/max threads values can be varied to change the way multi-threading is implemented for the cartridge.

OC4J Threading

The OC4J servlet container is multi-threaded by default. The OC4J servlet container manages the threads that service client requests. Each instance of a servlet class can be given multiple threads of execution. In this case, a servlet instance is shared between more than one client. Alternatively, you can specify a class to execute only one thread at a time by having that class implement the javax.servlet.SingleThread interface. In this case, a pool of instances of this Servlet class is maintained and each instance is assigned to one client only at any one time (instances are not shared).

Sessions

In the JWeb cartridge, you can enable client sessions using the OAS Node Manager. In OC4J, in accordance with Servlet 2.3 specifications, only programmable sessions are available. Consequently, if you are migrating a JWeb application that was session-enabled by means other than code, you must implement the session mechanism programmatically using the servlet session API. See "Session Control".

Dynamic Content Generation in HTML Pages

A JWeb Toolkit feature is available for generating dynamic content in HTML pages. The JWeb Toolkit embeds special placeholders in an HTML page. When this file is imported into a JWeb class as an oracle.html.HtmlFile object, the setItemAt() method places the data generated from the code at the placeholder locations.

Since this is a JWeb specific feature, it is not available in Oracle9iAS. If you would like to embed dynamic information in HTML pages (scripting), consider using JSP in Oracle9iAS.

See Also: Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference in the Oracle9iAS Documentation Library

Migration Strategies

OC4J provides complete support for J2EE 1.2, as well as support for major J2EE 1.3, such as complete Servlet 2.3, partial EJB 2.0 (message-driven beans), complete Jaas and JCA support. If you have JWeb or JServlet applications deployed on Oracle Application Server 4.x and wish to migrate to Oracle9iAS, you must modify your JWeb or JServlet applications to comply with applicable specifications for OC4J.

Comparison of Compliance Standards

Table 2-1 presents the comparison of compliance standards between the JWeb and JServlet cartridges in Oracle Application Server, and OC4J in Oracle9iAS. When migrating JWeb or JServlet from Oracle Application Server to OC4J Servlet in Oracle9iAS, you must modify the code to comply with Servlet 2.3 specifications.

Table 2-1 Comparison of Compliance Standards for JWeb, JServlet, and OC4J

Standard Complied	JWeb	JServlet	OC4J
Servlet Specifications	NA	2.1	2.3
JSP Specifications	NA	NA	1.1*

* JSP 1.2 is being completed when preparing this document. Please consult your product to verify actual specifications conplied.

See Also: http://java.sun.com for more information regarding Servlet specifications

Key JWeb & Servlet Methods

In order to migrate, you must understand and use the following key methods:

JWeb--contains a java class with a main() method, also known as JWeb Cartridge. The infrastructure of JWeb maps a URL to this method.

Servlet--contains a java class that includes a few doGet() and doPut() methods, specified by Sun Microsystems Inc., which map to a URL.

Migration Approach

As a primary migration approach, you can call the main() method of the JWeb Cartridge in the corresponding doGet() Servlet method.

Specifically, you must focus on the following aspects:

• Logging APIs--Oracle9iAS does not support the Oracle Application Server logging APIs. Instead, it uses the Servlet logging APIs. Therefore, you must modify your code in JWeb cartridge to reflect the changes in logging APIs.

• Utility APIs--Use JSP to write your utility APIs. Currently, oracle.html.*. package is not available.

  See Also: http://jakarta.apache.org/ecs/index.html for more information regarding html.*. packages

• WRB Calls--You must use the standard servlet APIs to write your security code since Oracle9iAS does not support most WRB APIs. For example, you can use methods getClientCertificate()and getLogger().

• Session--see "Session Control".

• Application Thread--see "Application Threads".

• Logging--see "Logging".

Code Modifications for JWeb Applications

To migrate JWeb applications to OC4J, you must modify code in these areas:

• Session Control

• Application Threads

• Logging

Session Control

You can session-enable a JWeb application with the cartridge's Client Session parameter in the Node Manager Web Parameters form. This allows the static parameters of an invoked class to contain per client data across calls. In OC4J, as per the Servlet 2.3 API, session state is not kept in static variables of Servlet classes. Instead, a session object is explicitly obtained to store session state using named attributes.

In OC4J, there is no support for configurable sessions. Therefore, you must enable sessions in code using the getSession() method in javax.servlet.http.HttpServletRequest, as shown below:

HttpSession session = request.getSession(true);

State information for a session can be stored subsequently and retrieved, for example, by the setAttribute(name, who) and getAttribute(name) methods of javax.servlet.http.HttpSession, respectively.

session.setAttribute("List", new Vector()); 
Vector list = (Vector) session.getAttribute("List");

Note: Do not use static data members to maintain session state in OC4J (although this is a common practice in JWeb). Instead, use the Servlet session API. The latter allows the Servlet container to use memory more efficiently.

Session Timeout

The default session timeout for an OC4J container can be specified in the session.config element in the XML deployment descriptors. A programmer can use the getMaxInactiveInernal method in the HTTPSession interface. Use setMaxInactiveInternal method to set the time-out value for a container.

The JWeb session time-out callback is not available in OC4J.

Application Threads

In JWeb, an application can manage threads using the oracle.owas.wrb.WRBRunnable class. This class allows application threads to access request and response information. For OC4J, you only need standard Java thread management to manage application threads (the java.lang.Runnable interface is used). For both JWeb and OC4J, using application threads is not recommended because multi-threaded applications limit the effectiveness of the load balancer.

Logging

In Oracle Application Server, JWeb applications log messages using the logger service provided by the WRB. This service allows applications to write messages to a central repository, such as a file system or database. The oracle.owas.wrb.services.logger.OutputLogStream class interfaces with the logger service.

In Oracle9iAS, OC4J generates diagnostic messages associated with Servlet logging APIs. These logging files are located at:

ORACLE_HOME/j2ee/home/log/digit digit_island-name/server.log

Note: OC4J does not have log levels.

JWeb Toolkit Packages (JWeb API)

Oracle Application Server includes a JWeb toolkit containing proprietary Java packages. If you used any of those packages in JWeb applications that you are migrating to Oracle9iAS, you must modify the code to use Servlet 2.3 equivalent classes and methods. If no equivalent functionality is available, you must rewrite the code to implement the functionality provided by the JWeb packages.

Because some of the JWeb toolkit packages were designed specifically to interact with Oracle Application Server components such as the WRB, the functionality in these packages is not reproducible in the standard Servlet API. Consequently, the migration process may also include some redesign of applications.

Table 2-2 through Table 2-8 list JWeb methods and their functional equivalents for the following Servlet API classes:

• Table 2-2, "JWeb Equivalents for javax.servlet.http.HttpServletRequest Class Methods"

• Table 2-3, "JWeb Equivalents for javax.servlet.ServletRequest Class Methods"

• Table 2-4, "JWeb Equivalents for javax.servlet.ServletResponse Class Methods"

• Table 2-5, "JWeb Equivalents for javax.servlet.ServletContext Class Methods"

• Table 2-6, "JWeb Equivalents for javax.servlet.http.HttpUtils Class Methods"

• Table 2-7, "JWeb Equivalents for javax.servlet.ServletOutputStream Class Methods"

• Table 2-8, "JWeb Equivalents for javax.servlet.ServletInputStream Class Methods"

  Table 2-2 JWeb Equivalents for javax.servlet.http.HttpServletRequest Class Methods

  JWeb Method	Servlet Method
  oracle.owas.wrb.services.http.HTTP.getHeader(String)	getHeader(string)
  oracle.owas.wrb.services.http.getCGIEnvironment("AUTH_TYPE")	getAuthType()
  oracle.owas.wrb.services.http.HTTP.getHeaders()Foot 1	getHeaderNames()Foot 2
  oracle.owas.wrb.services.http.HTTP.getCGIEnvironment("PATH_INFO")	getPathInfo()
  oracle.owas.wrb.services.http.HTTP.getCGIEnvironment("PATH_TRANSLATED")	getPathTranslated()
  oracle.owas.wrb.services.http.HTTP.getCGIEnvironment("QUERY_STRING")	getQueryString()
  oracle.owas.wrb.services.http.HTTP.getCGIEnvironment("REQUEST_METHOD")	getMethod()
  oracle.owas.wrb.services.http.HTTP.getCGIEnvironment("REMOTE_USER")	getRemoteUser()
  oracle.owas.wrb.services.http.HTTP.getCGIEnvironment("SCRIPT_NAME")	getServletPath()

  1 return a hashtable of header names and values 2 return an enumeration of header names

  Table 2-3 JWeb Equivalents for javax.servlet.ServletRequest Class Methods

  JWeb Method	Servlet Method
  oracle.owas.wrb.services.http.HTTP.getCGIEnvironment("CONTENT_TYPE")	getContentType()
  oracle.owas.wrb.services.http.HTTP.getCGIEnvironment("CONTENT_LENGTH")	getContentLength()
  oracle.owas.wrb.services.http.HTTP.getCGIEnvironment("SERVER_PROTOCOL")	getProtocol()
  oracle.owas.wrb.services.http.HTTP.getCGIEnvironment("REMOTE_ADDR")	getRemoteAddr()
  oracle.owas.wrb.services.http.HTTP.getCGIEnvironment("REMOTE_HOST")	getRemoteHost()
  oracle.owas.wrb.services.http.HTTP.getCGIEnvironment("SERVER_NAME")	getServerName()
  oracle.owas.wrb.services.http.HTTP.getCGIEnvironment("SERVER_PORT")	getServerPort()
  oracle.owas.wrb.services.http.HTTP.getPreferredAcceptCharset()	getCharacterEncoding()
  oracle.owas.wrb.services.http.HTTP.getURLParameter(name)	getParameter(string)
  oracle.owas.wrb.services.http.HTTP.getURLParameters(name)	getParameterValues(string)

  Table 2-4 JWeb Equivalents for javax.servlet.ServletResponse Class Methods

  JWeb Method	Servlet Method
  oracle.owas.wrb.WRBWriter	getWriter()

  Table 2-5 JWeb Equivalents for javax.servlet.ServletContext Class Methods

  JWeb Method	Servlet Method
  oracle.owas.wrb.services.http.HTTP.getCGIEnvironment	getServerInfo()
  Use oracle.OAS.Services.Logger	log(Exception, String) log(String)

  Table 2-6 JWeb Equivalents for javax.servlet.http.HttpUtils Class Methods

  JWeb Method	Servlet Method
  oracle.owas.wrb.services.http.HTTP.getURLParameters(Hashtable)	parsePostData(int, ServletInputStream)
  oracle.owas.wrb.services.http.HTTP.getURLParameters(Hashtable)	parseQueryString(String)

  Table 2-7 JWeb Equivalents for javax.servlet.ServletOutputStream Class Methods

  JWeb Method	Servlet Method
  oracle.html.HtmlStream.print()	javax.servlet.ServletOutputStream.print()
  oracle.html.HtmlStream.println()	javax.servlet.ServletOutputStream.println()

  Table 2-8 JWeb Equivalents for javax.servlet.ServletInputStream Class Methods

  JWeb Method	Servlet Method
  oracle.owas.wrb.services.http.MultipartElement()	javax.servlet.ServletInputStream.readLine()