Oracle9i Application Server Migrating from Oracle Application Server Release 1 (v1.0.2.2) Part Number A83709-07 |
|
This chapter discusses migration of JWeb applications from Oracle Application Server to Apache JServ in the Oracle9i Application Server. It includes a discusssion of functional differences between JWeb and Apache JServ, and provides code examples for migrating. The topics include:
Oracle9i Application Server uses the Oracle HTTP Server to service HTTP requests from clients. Apache JServ 1.1, a Servlet 2.0 compliant servlet engine, is bundled with Oracle9i Application Server. If you have JWeb applications deployed on Oracle Application Server 4.x and wish to migrate to Oracle9i Application Server, you need to migrate your JWeb applications to the Servlet 2.0 specification.
Apache JServ 1.1 is compatible with Apache 1.3.x, JDK 1.1 or later, and JSDK 2.0. Oracle Application Server 4.0.8 JServlets are compliant with the Servlet 2.1 specification. If you are migrating JServlets to Apache, we recommend that you plan the migration to Oracle8i JVM servlets because of the differences between 2.0 and 2.1 compliant servlets.
This section describes the differences between JWeb and Apache JServ 1.1 applications.
JWeb applications execute within the Oracle Application Server cartridge infrastructure, while Apache JServ 1.1 servlets run with the Oracle HTTP Server and in JVM(s).
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 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 Oracle Application Server application paradigm). Figure 2-1 depicts these components graphically.
Apache JServ consists of two functional components: mod_jserv and a servlet engine. mod_jserv is an Apache Server module and directs incoming requests for Java Servlets to a servlet engine. The Apache JServ Protocol (AJP) facilitates communication between the two components.
Figure 2-2 illustrates a one-to-many configuration. In a one-to-many configuration, there is one Apache listener and multiple servers. Each server can run one or more servlet engines. In this figure, a single Apache instance is communicating to two servers. Server 1 is running two servlet engines and server 2 is running one servlet engine. Three AJP connections are open between the servlet engines and a single mod_jserv in the Apache instance.
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.
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.
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.
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 environment. There is a limit of 25 servlet engines that can be addressed by a single mod_jserv.
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).
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.
JWeb classes and Apache JServ servlets have different life cycles.
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()
.
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 logic.
Figure 2-3 depicts the servlet life cycle.
The JWeb cartridge and Apache JServ servlet engine support single or multiple threads of execution, but the threading implementations are different.
Threading for the JWeb cartridge is defined in the Oracle Application Server 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 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.
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).
In the JWeb cartridge, you can enable client sessions using the OAS 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".
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 JavaServer Pages with OracleJSP in Oracle9i Application Server.
To migrate JWeb applications to Apache JServ, you will have to modify code in these areas:
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");
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.
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 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 because multi-threaded applications limit the effectiveness of the load balancer.
JWeb applications log messages using the Oracle Application Server 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 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 Oracle HTTP Server http.conf
configuration file. The default value for this directive is <ORACLE_HOME>/Apache/Jserv/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 value for this directive is <ORACLE_HOME>/Apache/Jserv/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.
The JWeb cartridge in Oracle Application Server includes a JWeb toolkit of Oracle proprietary Java packages. If you used any of those packages in JWeb applications that will migrate to Oracle9i 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 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.
The following tables 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
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()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
A hashtable of header names and values is returned. 2 An enumeration of header names is returned. |
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(name) |
oracle.owas.wrb.services.http.HTTP.getURLParameters(name) |
getParameterValues(name)Foot 1 |
1
where there are multiple values for "name" |
JWeb Method | Servlet Method |
---|---|
oracle.owas.wrb.WRBWriter |
getWriter() |
JWeb Method | Servlet Method |
---|---|
oracle.owas.wrb.services.http.HTTP.getCGIEnvironment |
getServerInfo() |
Use oracle.OAS.Services.Logger |
log(String) |
|
Copyright © 2001 Oracle Corporation. All Rights Reserved. |
|