2
Migrating JWeb Applications to Apache JServ

This chapter discusses migration of JWEB applications from Oracle Application Server (OAS) to Apache JServ in the Oracle Internet Application Server. It includes a discusssion of functional differences between JWEB and JServ, and provides code examples for migrating.

Contents

• What is Apache JServ?

• JWEB and Apache JServ 1.1 Differences

• Code Modifications for JWEB Applications

What is Apache JServ?

Oracle Internet Application Server uses the Apache web server to service HTTP requests from clients. Apache JServ 1.1, a Servlet 2.0 compliant servlet engine, is bundled with Oracle Internet Application Server. If you have JWEB applications deployed on OAS 4.x and wish to migrate to Oracle Internet Application Server, you need to migrate your JWEB applications to Apache JServ 1.1.

Migrating OAS JServlets to Apache

Apache JServ 1.1 is compatible with Apache 1.3.x, JDK 1.1 or later, and JSDK 2.0. OAS 4.0.8.x JServlets are compliant with Servlet 2.1 specifications. If you are migrating OAS JServlets to Apache, we recommend that you plan the migration to Oracle8i JVM servlets. See http://java.apache.org for more information on Apache JServ.

JWEB and Apache JServ 1.1 Differences

This section describes the differences between JWEB and Apache JServ 1.1 applications.

Architecture

JWEB applications execute within the OAS cartridge infrastructure, while Apache JServ 1.1 servlets run with the Apache web server and in JVM(s).

JWEB Architecture

In OAS, the HTTP listener receives a request for a JWEB cartridge. The listener passes the request to the dispatcher, which communicates with the Web Request Broker (WRB). The WRB uses 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 OAS application paradigm). Figure 2-1 depicts these components graphically.

Figure 2-1 OAS Cartridge Infrastructure

Apache JServ Architecture

Apache JServ consists of two functional components: mod_jserv and a servlet engine, as shown in Figure 2-2.

Figure 2-2 Apache JServ Architecture (one-to-many example)

mod_jserv, which is implemented in C, is an Apache module that runs in the same process as the Apache web server. It functions like a dispatcher in that it receives a request from the Apache HTTP listener and routes it to a servlet engine. It does not execute any servlet business logic.

A servlet engine provides the runtime environment to execute servlets implementing the Servlet 2.0 API. It runs in a JVM process, in the same or different node as the Apache web server. Each JVM has one servlet engine, and the number of servlet engines is not proportional to the number of web servers (mod_jserv modules). One mod_jserv can work with more than one servlet engine and vice versa. Or, multiple mod_jserv modules can work with multiple servlet engines.

Apache JServ Protocol

Because Apache JServ servlet engines do not run in-process with mod_jserv (or possibly not even on the same physical machine as the module), a protocol is required for the two components to communicate. A proprietary protocol called Apache JServ Protocol (AJP) 1.1, is used. AJP 1.1 communicates using sockets, and implements an authentication algorithm using MD5 hashing without strong cryptography. See http://java.apache.org/jserv/protocol/AJPv11.html for more information.

Single Node Configuration

When a servlet engine is located on the same machine as the web server, the mod_jserv module can be set up to start or stop the servlet engine 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_jserv can also perform failover by checking JVM status regularly and starting another JVM if the first crashes.

Multi-Node Configuration

Automatic lifecycle control is not available when mod_jserv and a servlet engine exist on different machines. The engine and JVM must be started manually with a customizable script (each servlet engine requires its own script to start). This means that each engine can be started with a custom start-up environment.

The separation of the servlet engine from the web server makes Apache JServ scalable. The default limit on the number of servlet engines mod_jserv can address is 25. If you change this value, you need to recompile mod_jserv. You must consider hardware limitations when configuring the number of servlet engines to use in a site; each website has its own requirements for optimal configuration.

mod_jserv and servlet engine instances can have one-to-one, one-to-many, many-to-one, and many-to-many relationships. Multiple servlet engines can also reside on one node (in which case the JVMs must be assigned different port numbers so that mod_jserv can differentiate them).

Servlet Zones

Apache JServ implements a servlet virtualization paradigm called servlet zones. Servlet zones can be equated with virtual hosts of web servers. Each zone provides a logical demarcation from the physical relationships (locations) of servlet classes. Hence, each servlet zone can be assigned a common context, including a common URI, regardless of where its member servlets are located (for example, on different hosts). However, the current implementation of Apache JServ does not provide sandbox security for each zone.

Life cycle

JWEB classes and Apache JServ servlets 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 http://java.sun.com/docs/books/vmspec/index.html for more details related to life cycle.

Apache JServ Life Cycle

In Apache JServ, servlet life cycle is compliant with Servlet 2.0 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 business logic.

Figure 2-3 depicts the servlet life cycle.

Figure 2-3 JServlet life cycle

Threading

The JWEB cartridge and Apache JServ servlet engine support single or multiple threads of execution, but the threading implementations are different.

JWEB Threading

Threading for the JWeb cartridge is defined in the OAS cartridge configuration by toggling the Stateless parameter (true or false). If true, a cartridge instance is shared by more than one client. If false, it is not shared, and only one client can access it at any one time. Also, if OAS 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.

Apache JServ Threading

The Apache JServ servlet engine is multi-threaded by default. The servlet container in the engine 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 Apache JServ, in accordance with Servlet 2.0 specifications, only programmable sessions are available. Consequently, if you are migrating a JWEB application that was session-enabled by a means other than code, you need to 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 Apache JServ. If you would like to embed dynamic information in HTML pages (scripting), consider using Java Server Pages in Oracle Internet Application Server.

Code Modifications for JWEB Applications

To migrate JWEB applications to Apache JServ, you will have to 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 the Servlet 1.0 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 Apache JServ, there is no configurable sessions support, so you have to 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 then be stored and retrieved by the putValue() and getValue() methods, respectively, of javax.servlet.http.HttpSession.

session.putValue("List", new Vector()); 
Vector list = (Vector) session.getValue("List"); 

Note: Do not use static data members to maintain session state in Apache JServ (although this is common practice in JWEB). Instead, use the servlet session API. The latter allows the servlet engine to use memory more efficiently.

JServ Session Time-out

You can specify the time-out value for a session in the session.timeout parameter in the jserv.properties file. You can also expire a session by invoking invalidate() in the servlet session API.

The JWEB session time-out callback is not available in Apache JServ.

Application Threads

In JWeb, an application can manage threads using the class:

oracle.owas.wrb.WRBRunnable

This class allows application threads to access request and response information. For Apache JServ, only standard Java thread management is needed to manage application threads (the java.lang.Runnable interface is used). For both JWeb and Apache JServ, using application threads is not recommended.

Logging

JWEB applications log messages using the OAS 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 class:

oracle.owas.wrb.services.logger.OutputLogStream

interfaces with the logger service.

In Apache JServ, messages are written to two log files. Messages generated by
mod_jserv are recorded in the file specified by the "ApJServLogFile" directive in the Apache web server's http.conf configuration file. The default value for this directive is <ServerRoot>/logs/mod_jserv.log. Messages generated by the servlet engine are recorded in the file specified by the log.file parameter in jserv.properties file (the default is <ServerRoot>/logs/jserv.log).

The messages generated by servlet applications, like exception stack traces, are recorded into jserv.log. In code, you can write to this log file using the javax.servlet.ServletContext.log or javax.servlet.GenericServlet.log methods.

The jserv.properties file allows you to select specific functional parts of the servlet engine to log. In jserv.log, these parts are referred to as channels.

Table 2-1 Channels in jserv.log

Channel	Type of Message
log.channel.authentication	Authentication messages from the AJP protocol.
log.channel.exceptionTracing	Exception stack traces caught by the servlet engine.
log.channel.init	Initialization messages from servlet engine.
log.channel.requestData	Data obtained from HTTP requests. For example, parameters from GET or POST HTTP methods.
log.channel.responseHeaders	Header information from HTTP responses.
log.channel.serviceRequest	Request processing messages.
log.channel.servletLog	Messages from the javax.servlet.ServletContext.log and javax.servlet.GenericServlet.log methods.
log.channel.servletManager	Messages from the servlet manager. These include messages for loading/unloading servlet zones and automatic class reloading.
log.channel.signal	System signal messages.
log.channel.terminate	Messages generated when servlet engine terminates.

JWEB Toolkit Packages (JWEB API)

The JWEB cartridge in OAS includes a JWEB toolkit of Oracle proprietary Java packages. If you used any of those packages in JWEB applications that will migrate to Oracle Internet Application Server, you must modify the code to use Servlet 2.0 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 OAS 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.

The following tables list JWEB methods and their functional equivalents for the following servlet API classes:

• Table 2-2 javax.servlet.http.HttpServletRequest

• Table 2-3 javax.servlet.ServletRequest

• Table 2-4 javax.servlet.ServletResponse

• Table 2-5 javax.servlet.ServletContext

• Table 2-6 javax.servlet.http.HttpUtils

  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(name)
  oracle.owas.wrb.services.http.getCGIEnvironment("AUTH_TYPE")	getAuthType()
  oracle.owas.wrb.services.http.HTTP.getHeaders()1	getHeaderNames()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 A hashtable of header names and values is returned. 2 An enumeration of header names is returned.

  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.getURLParameter(name)	getCharacterEncoding() getParameter(name)
  oracle.owas.wrb.services.http.HTTP.getURLParameters	getParameterNames() getParameterValues(name)1

  1 where there are multiple values for "name"

  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
  Use oracle.owas.wrb.services.http.HTTP.getCGIEnvironment to obtain the desired return value from this servlet method, if this value is available in the CGI environment.	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)
  oracle.html.HtmlStream.print	javax.servlet.ServletOutputStream.print
  oracle.html.HtmlStream.println	avax.servlet.ServletOutputStream.println
  oracle.owas.wrb.services.http.MultipartElement	javax.servlet.ServletInputStream.readLine