2 Servlet Development

OC4J Web Application Redeployment and Class Reloading Features

In OC4J, any of the following circumstances, depending on OC4J polling, results in redeployment of a Web application and, upon request, reloading of servlet classes and any dependency classes.

• If a servlet .class file under /WEB-INF/classes changes, such as by recompilation, then when the servlet is next requested, the associated Web application is redeployed and the servlet class and any dependency classes are reloaded. This action does not depend on OC4J polling. Note that nothing happens until the servlet is next requested. Also note that if only non-servlet .class files under /WEB-INF/classes change, nothing is reloaded.

  
  

  Note: Changing a servlet class file in a directory location specified in a <classpath> element in global-web-application.xml or orion-web.xml has the same effect as changing a servlet class file in /WEB-INF/classes. However, changing a JAR file or dependency class file (such as for a JavaBean) in a <classpath> location has no effect.

  
  

• If the web.xml file changes, or a library JAR file in /WEB-INF/lib changes, and OC4J polling is enabled, then the associated Web application is redeployed the next time the OC4J task manager runs, which by default is once each second. Any servlet class in the Web application and any dependency classes are reloaded upon the next request for the servlet. Alternatively, if polling is not enabled, you can trigger one-time polling and the resulting redeployment and reloading by using the admin.jar -updateConfig option.

Be aware of the following important considerations:

• In the preceding scenarios, a servlet and its dependency classes are reloaded immediately, instead of upon next request, if the servlet is set to be preloaded. This is according to load-on-startup settings. See "Servlet Preloading".

• OC4J servlet reloading functionality does not extend to JSP page implementation classes. Changing a JSP page implementation .class file does not result in any reloading. JSP recompilation and reloading behavior is determined by the JSP main_mode flag, as described in the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide.

• Classes in Web modules of a parent application are not visible to child applications, although other classes of the parent application (such as EJBs, for example) are visible.

• You can use <library> elements in the global application.xml file or server.xml file to specify directories or JAR or ZIP files for shared code. Upon startup, OC4J loads all classes in any JAR or ZIP file specified in any <library> element, and all classes in any JAR or ZIP file in any directory specified in any <library> element.

  To avoid unnecessary overhead, you should use <library> elements somewhat sparingly, specify particular JAR or ZIP files instead of entire directories wherever possible, and, where directories are specified, minimize the number of JAR or ZIP files in those directories.

  By default, application.xml includes a <library> element for the j2ee/home/applib directory.

  
  

  Note: Changing a JAR or ZIP file specified in a <library> element, or a JAR or ZIP file in a directory specified in a <library> element, does not by itself result in redeployment of any Web applications or reloading of classes. The OC4J task manager does not poll these shared library locations.

  
  

Loading WAR File Classes Before System Classes in OC4J

The servlet specification recommends, but does not require, loading local classes, which are classes in the WAR file, before system classes, which are any other classes in the environment. Note that "classes in the WAR file" may include classes from the WAR file manifest classpath. By default, the OC4J servlet container does not load local classes first, but you can configure this through the <web-app-class-loader> element in global-web-application.xml or orion-web.xml. This element has two attributes:

• search-local-classes-first: Set this to "true" to search and load WAR file classes before system classes. The default setting is "false".

• include-war-manifest-class-path: Set this to "false" to not include the classpath specified in the WAR file manifest Class-Path attribute when searching and loading classes from the WAR file, regardless of the search-local-classes-first setting. The default setting is "true".

  
  

  Notes: If both attributes are set to "true", the overall classpath is constructed so that classes physically residing in the WAR file are loaded prior to any classes from the WAR file manifest classpath. So you can assume that in the event of any conflict, classes physically residing in the WAR file will take precedence. For compliance with the servlet specification, you cannot use search-local-classes-first functionality in loading classes in java.* or javax.* packages.

  
  

Also see "Element Descriptions for global-web-application.xml and orion-web.xml".

Sharing Cached Java Objects Across OC4J Servlets in Oracle Application Server

To take advantage of the distributed functionality of the Oracle Application Server Java Object Cache, or to share a cached object between servlets, some minor modification to an application deployment is necessary. Any user-defined objects that will be shared between servlets or distributed between JVMs must be loaded by the system classloader; however, by default, objects loaded by a servlet are loaded by the context classloader. Objects loaded by the context classloader are visible only to the servlets within the servlet context corresponding to that classloader. The object definition will not be available to other servlets or to the cache in another JVM. If an object is loaded by the system classloader, however, the object definition will be available to other servlets and to the cache on other JVMs.

With OC4J, the system classpath is derived from the manifest of the oc4j.jar file and any associated .jar files, including cache.jar. The classpath in the environment is ignored. To include a cached object in the classpath for OC4J, do one of the following with the .class file, assuming an Oracle Application Server environment:

• Copy it to the ORACLE_HOME/javacache/cachedobjects/classes directory.

• Add it to the ORACLE_HOME/javacache/cachedobjects/share.jar file.

Both the classes directory and the share.jar file are included in the manifest for cache.jar, and are therefore included in the system classpath.

For information about the Oracle Application Server Java Object Cache, see the Oracle Application Server Containers for J2EE Services Guide.

General Performance Considerations

This section summarizes issues, mostly documented elsewhere in this manual, that may impact performance:

• Consider the optimal expiration setting for Web pages in your application. You can set the expiration for pages that match a given URL pattern, using the <expiration-setting> subelement of <orion-web-app> in global-web-application.xml or orion-web.xml. (See "Element Descriptions for global-web-application.xml and orion-web.xml".) A more appropriate setting decreases load on the application and improves performance.

• Be aware of performance implications relating to how multiple concurrent requests are synchronized or coordinated, and also be aware of related considerations regarding thread models. See "Servlet Thread Models and Related Considerations".

• There are performance implications related to how session state is replicated in a distributable environment. Replication is triggered each time there is a setAttribute() call on the session object, so large numbers of such calls in a servlet may impact performance. In addition, be aware that for performance reasons, OC4J does not wait to confirm successful replication of session state. See "Session Replication in a Distributable Application".

• Servlet configuration parameters can significantly affect performance. For information about the file-modification-check-interval attribute of the <orion-web-app> element, see "Element Descriptions for global-web-application.xml and orion-web.xml". For information about the use-keep-alives attribute of the <web-site> element, see "Element Descriptions for Web Site XML Files".

• Additional JSP-related configuration parameters can significantly affect performance. See "Element Descriptions for global-web-application.xml and orion-web.xml" for information about the simple-jsp-mapping and enable-jsp-dispatcher-shortcut attributes of the <orion-web-app> element.

• OC4J standalone supports a mode of "shared" operation for a single application through multiple Web sites, where a site is defined as a particular host and port. This feature is particularly intended for secure applications in which some but not all communications require HTTPS. Running the noncritical communications through an HTTP port improves performance. See "Element Descriptions for Web Site XML Files" for information about the shared attribute of the <web-app> element.

• If you ever use OC4J standalone as a production environment (although this is not typical), remember to disable the server.xml check-for-updates flag. See "Key OC4J Flags for Development".

Oracle Application Server Dynamic Monitoring Service

In an Oracle Application Server environment, DMS adds performance-monitoring features to several components, including OC4J. The goal of DMS is to provide information about runtime behavior through built-in performance measurements so that users can diagnose, analyze, and debug any performance problems. DMS provides this information in a package that can be used at any time, including during live deployment. Data are published through HTTP and can be viewed with a browser.

Standard configuration for the DMS servlets, such as the spy servlet and monitoring agent, is in the global application.xml file and the default-web-site.xml file.

In the OC4J application.xml file, the Web modules dms and dms0 and the paths to their WAR files are specified. The default-web-site.xml file specifies that these Web modules are deployed to the OC4J default application and binds them to their context paths. Do not directly alter any of these DMS configurations.

Use the Oracle Enterprise Manager 10g to access DMS, display DMS information, and, if appropriate, alter DMS configuration.

OC4J Logs

Several logs are available in OC4J. Because they are not specific to servlets, they are documented elsewhere, but this section provides a summary list and appropriate cross-references. For each log, you have the option of using text-based logging or ODL logging. (See the next section, "Oracle Diagnostic Logging Versus Text-Based Logging".) Note that for ODL, log file names always take the form logN.xml, where N is an integer. For text-based logging, you must specify the log file names.

For each log there is a configuration element in the appropriate OC4J configuration file to enable text-based logging, and a separate element to enable ODL logging. The presence of a logging configuration element enables the associated type of logging.

OC4J supports the following logs:

• Application log

  There is a log for each application deployed, as configured in orion-application.xml. For text-based logging, a typical name is application.log.

• Global application log

  There is a log for global logging for all applications, including the default application, as configured in the OC4J global application.xml file. For text-based logging, a typical name is global-application.log.

• JMS log

  There is a log for Java Message Service (JMS) functionality, as configured in jms.xml. For text-based logging, a typical name is jms.log.

• RMI log

  There is a log for remote method invocation functionality, as configured in rmi.xml. For text-based logging, a typical name is rmi.log.

• Server log

  There is a server-wide log, as configured in server.xml. For text-based logging, a typical name is server.log.

• Web site access log

  There is a Web site access log (one log file for each Web site to log all accesses of the site), as configured in the Web site XML file. For text-based logging, a typical name is http-access.log.

  
  

  Note: For Web site access logging, you can use only one type of logging, not both.

  
  

Configuration of the Web access log is covered in this manual. Under "Element Descriptions for Web Site XML Files", see the information about the <access-log> and <odl-access-log> subelements of the <web-site> element.

The Oracle Application Server Containers for J2EE User's Guide has information about how to enable logging to the other OC4J files.

Oracle Diagnostic Logging Versus Text-Based Logging

For each of the logs listed in the preceding section, "OC4J Logs", you have the option of using Oracle Diagnostic Logging (ODL), which offers some advantages over text-based logging.

ODL provides standardized logging across all components of OC4J, creating the log files in an XML format that can be loaded to a repository for reporting and viewing. You can view ODL logs from Oracle Enterprise Manager 10g, for example.

With ODL, it is also easier to manage the size and number of your log files. In many situations, text-based logging results in the need to periodically shut down the OC4J server and manually clean up the files.

To enable and configure ODL logging for the Web site access log file, use the <odl-access-log> subelement of the <web-site> element in the Web site XML file. To enable and configure text-based logging, use the <access-log> subelement of the <web-site> element instead. (Note, however, that either element can be overridden for any particular Web application by a setting of access-log="false" in the <web-app> element of the Web application in the Web site XML file.)

For each of the other OC4J logs, use the <odl> subelement of the <log> element in the appropriate XML configuration file if you want to use ODL logging. To use text-based logging, use the <file> subelement of the <log> element instead.

See the Oracle Application Server Containers for J2EE User's Guide for additional information about ODL.

Additional Oracle Application Server Log Files

In addition to the OC4J log files discussed previously, Oracle Application Server supports the following log files:

• OPMN log file (one log file for each OC4J instance, for Oracle Process Management and Notification functionality)

• ons.log (OPMN notification system log, configured in opmn.xml)

• ipm.log (OPMN process management log, configured in opmn.xml)

OPMN manages Oracle HTTP Server and OC4J processes within an application server instance.

For information about Oracle Application Server log file management, refer to Oracle Application Server Administrator's Guide.

OC4J Debugging Flags

OC4J supports several flags to enable debugging output for its subsystems.

Here are the HTTP debugging flags:

• http.error.debug for all HTTP errors; otherwise some are consumed without being reported

• http.cluster.debug for debugging statements regarding HTTP clustering and session persistence

• http.session.debug for HTTP session errors and lifecycle statements

• http.request.debug for information from HTTP request stream

• http.redirect.debug for information about HTTP redirects

• debug.http.contentLength to print explicit content-length calls as well as extra sendError information

• http.virtualdirectory.debug to print the enforced virtual directory mappings upon startup

• http.method.trace.allow to enable the traceHTTP() method

Here are the AJP debugging flags (for Oracle Application Server with Oracle HTTP Server only):

• ajp.debug to print the incoming AJP stream

• ajp.io.debug to print the AJP response from the server

The AJP flags do not produce user-friendly output, but are necessary for debugging some AJP issues.

Here are the JDBC debugging flags:

• datasource.verbose for information about the creation of data sources and database connections

• jdbc.debug for detailed information about JDBC calls

Here is the EJB debugging flag:

• ejb.cluster.debug for information about EJB clustering

Here are the RMI debugging flags:

• rmi.debug for information about remote method invocations

• rmi.verbose for detailed information about RMI calls

Here is the Web services debugging flag:

• ws.debug for information about Web services

Setting OC4J Debugging Flags

The debugging flags are enabled through Java option settings such as the following:

-Dhttp.session.debug=true

If you are using OC4J standalone, specify option settings in the Java command line when you start OC4J. In an Oracle Application Server environment, use Oracle Enterprise Manager 10g. Specify option settings in the Java Options field under Command Line Options in the Application Server Control Console Server Properties Page for the OC4J instance. To get to this page, select Server Properties under Instance Properties in the Administration Page for the OC4J instance. See "Application Server Control Console OC4J Administration Page". See the Oracle Application Server Containers for J2EE User's Guide for further information.

Timing Considerations for Debugging in Oracle Application Server

Because of the way OPMN functions, there are timing issues to consider when debugging in an Oracle Application Server environment. Specifically, whenever debugging results in the halting of a process, OPMN terminates that process after the halt goes beyond the timeout period.

To remedy this situation, you must set an appropriate timeout value, using the <timeout> element in the opmn.xml file.

For information about opmn.xml, particularly for starting and stopping Oracle Application Server, refer to the Oracle Application Server Administrator's Guide.

Debugging Through JDeveloper and Other IDEs

If you use Oracle JDeveloper as your development environment, you can take advantage of its debugging features.

For debugging, JDeveloper offers local and remote debugging of JSP pages, servlets, and other Java source files. You can start by setting breakpoints in the source files within JDeveloper and running a debugging session with the source selected. While debugging an application such as a servlet in JDeveloper, you have complete control over the execution flow and can view and modify variable values, as well as perform advanced application performance monitoring, such as viewing class instance counts and memory usage. JDeveloper will follow calls from your application into other source files or offer to generate stub classes for class sources that are not available. Remote debugging, after the code to be debugged is launched and the JDeveloper debugger is attached to it, is similar to local debugging.

See "Oracle JDeveloper Support for Servlet Development" for a general summary of JDeveloper features for servlet development.

http://www.oracle.com/technology/products/ias/oracleas_partners.html

Key Features for Invocation in Oracle Application Server

In an Oracle Application Server production environment, OC4J should always be accessed through the Oracle HTTP Server. Oracle HTTP Server uses AJP (Apache JServ protocol) to communicate to OC4J, but this is invisible to the end user.

When a servlet is requested, the OC4J servlet container interprets the URL, as "Summary of URL Components" describes.

Whatever port number you use is mapped to AJP protocol through a <web-site> element in the default-web-site.xml file. (This is the typical name, but Web site XML file names are defined according to settings in the server.xml file and can be changed as desired.) The port mapping is defined through the port and protocol attributes of the <web-site> element, with port set as desired and protocol set to "ajp13". By default, port 7777 is for access through the Oracle HTTP Server with Oracle Application Server Web Cache enabled.

Whenever you use Enterprise Manager to deploy an application, you are prompted for a URL mapping. The mapping you specify results in a new OC4J mount point in mod_oc4j.conf. If you specify a URL mapping of "/mypath", for example, this is the context path of your Web application and is defined as a new OC4J mount point. Then you invoke a servlet with a URL such as the following:

http://www.example.com:7777/mypath/MyServlet

See "Application Server Control Console Deploy Application (EAR) Page" and "Application Server Control Console Deploy Web Application (WAR) Page" for information about the Enterprise Manager EAR and WAR deployment pages.

For an overview of deployment to Oracle Application Server, see "OC4J Deployment in Oracle Application Server". For further information, see the Oracle Application Server Containers for J2EE User's Guide. For general information about Enterprise Manager, see Oracle Enterprise Manager Concepts.

See the Oracle HTTP Server Administrator's Guide for information about Oracle HTTP Server configuration, mount points, and the mod_oc4j.conf file.

Use of Perceived Front-End Hosts by OC4J

An additional element in the default-web-site.xml file (or other Web site XML file) is relevant in servlet invocation. The <frontend> subelement of the <web-site> element can specify a perceived front-end host and port of the Web site as seen by HTTP clients. When the site is behind a load balancer or firewall, the <frontend> specification is necessary to provide appropriate information to the Web application for functionality such as URL rewriting. Attributes are host, for the name of the front-end server (such as "www.example.com"), and port, for the port number of the front-end server (such as "8080"). Using this front-end information, the back-end server that is actually running the application knows to refer to www.example.com, instead of to itself, in any URL rewriting. This way, subsequent requests properly come in through the front-end again, instead of trying to access the back-end directly.

The specified front-end host and port settings are also reflected back to the servlet and are the values you receive if you call the getServerName() or getServerPort() method of the HTTP request object.

Overview of Session Tracking

The HTTP protocol is stateless by design. This is fine for stateless servlets that simply take a request, perform a few computations, output some results, and then in effect go away. But most server-side applications must keep some state information and maintain a dialogue with the client. The most common example of this is a shopping cart application. A client accesses the server several times from the same browser and visits several Web pages. The client decides to buy some of the items offered for sale at the Web site and clicks the BUY ITEM buttons. If each transaction were being served by a stateless server-side object, and the client provided no identification on each request, it would be impossible to maintain a filled shopping cart over several HTTP requests from the client. In this case, there would be no way to relate a client to a server session, so even writing stateless transaction data to persistent storage would not be a solution.

Session tracking involves identifying user sessions by ID numbers and tying requests to their session through use of the ID number. This process is typically performed using cookies or URL rewriting.

The OC4J servlet container, to comply with the servlet specification, implements session tracking through HTTP session objects, which are instances of a class that implements the javax.servlet.http.HttpSession interface.

When a servlet creates an HTTP session object (through the request object getSession() method), the client interaction is considered to be stateful.

An HTTP session object has scope over the Web application only. You cannot use session objects to share data between applications. Nor can you use session objects to share data between different clients of the same application. There is one HTTP session object for each client in each application.

Cookies

Several approaches have been used to add a measure of statefulness to the HTTP protocol. The most widely accepted is the use of cookies, used to transmit an identifier between server and client, in conjunction with stateful servlets that can maintain session objects. Session objects are simply dictionaries that store values (Java objects) together with their associated keys (Java strings).

Cookie usage is as follows:

1. With the first response from a stateful servlet after a session is created, the server (container) sends a cookie with a session identifier back to the client, often along with a small amount of other useful information (all less than 4 KB). The container sends the cookie, named JSESSIONID, in the HTTP response header.

2. Upon each subsequent request from the same Web client session (assuming the client supports cookies), the client sends the cookie back to the server as part of the request, and the server uses the cookie value to look up session state information to pass to the servlet.

3. With subsequent responses, the container sends the updated cookie back to the client.

The servlet code is not required to do anything to send a cookie; the container handles this. Sending cookies back to the server is handled automatically by the Web browser, unless the user disables cookies.

The container uses the cookie for session maintenance. A servlet can retrieve cookies using the getCookies() method of the HttpServletRequest object and can examine cookie attributes using the accessor methods of the javax.servlet.http.Cookie objects.

URL Rewriting

An alternative to using cookies is URL rewriting, through the encodeURL() method of the response object. In this mechanism, the session ID is encoded into the URL path of a request. See "Session Servlet Example" for an example of URL rewriting.

The name of the path parameter is jsessionid, as in the following example:

http://host:port/myapp/index.html?jsessionid=6789

The value of the rewritten URL is used by the server to look up session state information to pass to the servlet, which is similar to the functionality of cookies.

Although cookies are typically enabled, the only way for you to ensure session tracking is to use encodeURL() in your servlets, or encodeRedirectURL() for redirects.

Other Session Tracking Methods

Other techniques have been used in the past to relate client and server sessions, including server hidden form fields and user authentication mechanisms to store additional information. Oracle does not recommend these techniques in OC4J applications. They have many drawbacks, including performance penalties and loss of confidentiality.

Session Tracking in OC4J

For session-tracking in OC4J, the servlet container first attempts to accomplish tracking through cookies. If cookies are disabled, the server can maintain session tracking only by using the encodeURL() method of the response object, or the encodeRedirectURL() method for redirects. You must include the encodeURL() or encodeRedirectURL() calls in your servlet if cookies may be disabled.

You can use the following setting in the global-web-application.xml or orion-web.xml file to disable the use of session cookies:

<session-tracking cookies="disabled" ... >
   ...
</session-tracking>

Cookies are enabled by default.

Cancellation Through a Timeout

The default session timeout for the OC4J server is 20 minutes. You can change this for a specific application by setting the <session-timeout> subelement under the <session-config> element of web.xml. Specify the timeout in minutes, as an integer. For example, to reduce the session timeout to five minutes, add the following lines to the application web.xml file:

<session-config>
  <session-timeout>5</session-timeout>
</session-config>

According to the servlet specification, a negative value specifies the default behavior that a session never times out. For example:

<session-config>
  <session-timeout>-1</session-timeout>
</session-config>

A value of 0 results in an immediate timeout.

Cancellation by the Servlet

A servlet explicitly cancels a session by invoking the invalidate() method on the session object. You must obtain a new session object by invoking the getSession() method of the HttpServletRequest object.

Overview of Session Replication and Requirements

To enable replication of the session state of an application between OC4J servers, you must mark the Web application as distributable, by use of the standard <distributable> element in the web.xml file. The presence of this subelement of the <web-app> element, as follows, specifies that the application is distributable:

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

Objects that are stored by a servlet in the HttpSession object are replicated. For replication to work properly, objects must be serializable (directly or indirectly implementing the java.io.Serializable interface) or remoteable (directly or indirectly implementing the java.rmi.Remote interface). Furthermore, any objects that are referenced by objects in the session object must themselves be serializable or remoteable.

Possible Clustering Error Conditions and Related Environment Flags

Replicated data is sent asynchronously to the other OC4J servers in the cluster island. For performance reasons, OC4J does not wait to confirm successful replication. Therefore, either of the following scenarios is possible, though highly unlikely:

• Broadcast latency, where session replication messages are not received and processed by the other OC4J servers before a client is rerouted:

  1. A client sends a request and receives a response from the OC4J server.

  2. The server broadcasts a replication message to the other OC4J servers in the cluster island with the updated state for the client.

  3. The client sends another request before the broadcast of the updated state has been received and processed by all OC4J servers.

  4. The original server fails, and the client is rerouted to one of the OC4J servers that does not yet have the new state information, resulting in the client receiving old data.

• Failure before response to client, where a server fails after it has broadcast its replication message to other servers, but before it has completed its response to the client:

  1. A client sends a request to the OC4J server.

  2. The server broadcasts a replication message to the other OC4J servers in the cluster island with the updated state for the client.

  3. The server fails, however, before completing its response to the client. This results in the client being unaware of the processing completed by the server, even though other OC4J servers are aware.

Because of the possible error scenarios, OC4J and Oracle HTTP Server maintain session affinity, meaning they make every effort to always route requests and responses through the same OC4J JVM. The session cookie, JSESSIONID, maintains the required, detailed routing information across HTTP requests to ensure that subsequent requests through Oracle HTTP Server are dispatched to the originating JVM wherever possible.

In addition, the OC4J 10.1.2 implementation supports two environment flags that you can use to reduce the risk of either error scenario occurring:

• cluster.thread.priority: By default, OC4J clustering threads run with the same priority as the other main OC4J threads. You can, however, set this flag to any integer value from 6 through 10 to give clustering threads higher priority, with 10 being the highest priority.

• cluster.failover.delay: In the event that an OC4J server fails, this flag results in a delay of the specified number of milliseconds before a client is rerouted to an alternate server. The default is no delay. A setting between 7000 and 9000 is probably sufficient to avoid the first of the error scenarios described above.

Session Replication Details and Logistics

For a distributable application, session replication is triggered each time there is a setAttribute() call on the session object. The name and value specified in the call are serialized and replicated, with the serialized value being stored using the specified name as the key. The value is deserialized only upon first access by a failed-over servlet.

Note that you must explicitly call setAttribute() whenever you update a data item belonging to the session object. For example, if you call getAttribute() on the session object to retrieve a bean and then call a method on the bean to change its state, you must then call setAttribute() on the session object to update the bean in the session. This is in contrast to the situation in a nondistributable environment, in which the bean is passed to you by reference and updated directly within the session object as soon as you call the method on the bean.

Also note the performance implications of this functionality. A servlet with a large number of setAttribute() calls may have lower performance because of the small overhead introduced when performing state replication.

SessionServlet Code

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
import java.util.Date;

public class SessionServlet extends HttpServlet { 

  public void doGet (HttpServletRequest req, HttpServletResponse res)
        throws ServletException, IOException {

    // Get the session object. Create a new one if it doesn't exist.
    HttpSession session = req.getSession(true);

    res.setContentType("text/html");
    PrintWriter out = res.getWriter();

    out.println("<head><title> " + "SessionServlet Output " +
                "</title></head><body>");
    out.println("<h1> SessionServlet Output </h1>");

    // Set up a session hit counter. "sessionservlet.counter" is just the
    // conventional way to create a key for the value to be stored in the
    // session object "dictionary".
    Integer ival = 
      (Integer) session.getAttribute("sessionservlet.counter");
    if (ival == null) {
      ival = new Integer(1);
    }
    else {
      ival = new Integer(ival.intValue() + 1);
    }

    // Save the counter value.
    session.setAttribute("sessionservlet.counter", ival);

    // Report the counter value. 
    out.println(" You have hit this page <b>" + 
                ival + "</b> times.<p>");

    // This statement provides a target that the user can click
    // to activate URL rewriting. It is not done by default.
    out.println("Click <a href=" + 
                res.encodeURL(HttpUtils.getRequestURL(req).toString()) + 
                ">here</a>");
    out.println(" to ensure that session tracking is working even " +
                "if cookies aren't supported.<br>");
    out.println("Note that by default URL rewriting is not enabled" +
                " due to its large overhead.");

    // Report data from request.
    out.println("<h3>Request and Session Data</h3>");
    out.println("Session ID in Request: " +
                req.getRequestedSessionId());
    out.println("<br>Session ID in Request is from a Cookie: " +
                req.isRequestedSessionIdFromCookie());
    out.println("<br>Session ID in Request is from the URL: " +
                req.isRequestedSessionIdFromURL());
    out.println("<br>Valid Session ID: " +
                req.isRequestedSessionIdValid());

    // Report data from the session object.
    out.println("<h3>Session Data</h3>");
    out.println("New Session: " + session.isNew());
    out.println("<br> Session ID: " + session.getId());
    out.println("<br> Creation Time: " + new Date(session.getCreationTime()));
    out.println("<br>Last Accessed Time: " +
                new Date(session.getLastAccessedTime()));
    out.println("</body>");
    out.close();
  }

  public String getServletInfo() {
    return "A simple session servlet";
  }
}

Deploying and Testing

In OC4J standalone, save the preceding code into a file SessionServlet.java in the OC4J default Web application /WEB-INF/classes directory. By default, the default Web application root directory is j2ee/home/default-web-app. (See "OC4J Default Application and Default Web Application" for more information.)

For convenience, use the development="true" setting in the <orion-web-app> element of the global-web-application.xml file. See "Element Descriptions for global-web-application.xml and orion-web.xml" for more information about the development flag.

Figure 2-1 shows the output of this servlet when a Web browser that has cookies enabled invokes it the second time in a session. Experiment with different Web browser settings—for example, by disabling cookies—then select the HREF that causes URL rewriting.

Figure 2-1 Session Servlet Display

Description of "Figure 2-1 Session Servlet Display"

Using Certificates with OC4J and Oracle HTTP Server

The steps below are for using keys and certificates for SSL communication in OC4J. These are server-level steps, typically executed prior to deployment of an application that will require secure communication, perhaps when you first set up an Oracle Application Server instance.

Note that a keystore stores certificates, including the certificates of all trusted parties, for use by a program. Through its keystore, an entity such as OC4J (for example) can authenticate other parties, as well as authenticate itself to other parties. Oracle HTTP Server uses what is called a wallet for the same purpose.

In Java, a keystore is a java.security.KeyStore instance that you can create and manipulate using the keytool utility that is provided with the Sun Microsystems JDK. The underlying physical manifestation of this object is a file. Go to the following Web site for information about keytool:

http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html

The Oracle Wallet Manager has functionality for Oracle wallets that is equivalent to the functionality of keytool for keystores.

Here are the steps in using certificates between OC4J and Oracle HTTP Server:

1. Use keytool to generate a private key, public key, and unsigned certificate.You can place this information into either a new keystore or an existing keystore.

2. Obtain a signature for the certificate, using either of the following two approaches.

   Generate your own signature:

   1. Use keytool to "self-sign" the certificate. This is appropriate if your clients trust you as, in effect, your own certificate authority.

   Alternatively, obtain a signature from a recognized certificate authority:

   1. Using the certificate from Step 1, use keytool to generate a certificate request, which is a request to have the certificate signed by a certificate authority.

   2. Submit the certificate request to a certificate authority.

   3. Receive the signature from the certificate authority, and import it into the keystore, again using keytool. In the keystore, the signature is matched with the associated certificate.

      
      

      Note: Oracle Application Server includes Oracle Application Server Certificate Authority (OCA). OCA allows customers to create and issue certificates for themselves and their users, although these certificates would probably be unrecognized outside a customer's organization without prior arrangements. See the Oracle Application Server Certificate Authority Administrator's Guide for information about OCA.

      
      

The process for requesting and receiving signatures is up to the particular certificate authority you use. Because that is outside the scope and control of Oracle Application Server, the documentation does not cover it. You can go to the Web site of any certificate authority for information. (Any browser should have a list of trusted certificate authorities.) Here are the Web addresses for VeriSign, Inc. and Thawte, Inc., for example:

http://www.verisign.com/

http://www.thawte.com/

For SSL communication between OC4J and Oracle HTTP Server, execute the preceding steps for Oracle HTTP Server, but use a wallet and Oracle Wallet Manager instead of a keystore and the keytool utility. See the Oracle Application Server Security Guide for information about wallets and the Oracle Wallet Manager.

In addition to steps 1 and 2 above, execute the following steps as necessary:

1. If the OC4J certificate is signed by an entity that Oracle HTTP Server does not yet trust, obtain the certificate of the entity and import it into Oracle HTTP Server. The specifics depend on whether the OC4J certificate in question is self-signed, as follows.

   If OC4J has a self-signed certificate (essentially, Oracle HTTP Server does not yet trust OC4J):

   1. From OC4J, use keytool to export the OC4J certificate. This step places the certificate into a file that is accessible to Oracle HTTP Server.

   2. From Oracle HTTP Server, use Oracle Wallet Manager to import the OC4J certificate.

   Alternatively, if OC4J has a certificate that is signed by another entity (that Oracle HTTP Server does not yet trust):

   1. Obtain the certificate of the entity in any appropriate way, such as by exporting it from the entity. The exact steps vary widely, depending on the entity.

   2. From Oracle HTTP Server, use Oracle Wallet Manager to import the certificate of the entity.

2. If the Oracle HTTP Server certificate is signed by an entity that OC4J does not yet trust, and OC4J is in a mode of operation that requires client authentication (as "Requesting Client Authentication" discusses):

   1. Obtain the certificate of the entity in any appropriate way, such as by exporting it from the entity. The exact steps vary widely, depending on the entity.

   2. From OC4J, use keytool to import the certificate of the entity.

      
      

      Note: During communications over SSL between Oracle HTTP Server and OC4J, all data on the communications channel between the two is encrypted. The following steps are executed: 1) The OC4J certificate chain is authenticated to Oracle HTTP Server during establishment of the encrypted channel. 2) Optionally, if OC4J is in client-authentication mode, Oracle HTTP Server is authenticated to OC4J. This process also occurs during establishment of the encrypted channel. 3) Any further communication after this initial exchange will be encrypted.

      
      

Example: Creating an SSL Certificate and Generating Your Own Signature This example corresponds to Step 2 above, in the mode where you generate your own signature by using keytool to self-sign the certificate.

First, create a keystore with an RSA private/public keypair, using the keytool command. The following example (in which % is the system prompt) uses the RSA keypair algorithm to generate a keystore to reside in a file named mykeystore, which has a password of 123456 and is valid for 21 days:

% keytool -genkey -keyalg "RSA" -keystore mykeystore -storepass 123456 -validity 21

Note the following:

• The keystore option specifies the name of the file in which the keys are stored.

• The storepass option sets the password for protecting the keystore.

• The validity option sets the number of days for which the certificate is valid.

The keytool prompts you for more information, as follows:

What is your first and last name?
  [Unknown]:  Test User
What is the name of your organizational unit?
  [Unknown]:  Support
What is the name of your organization?
  [Unknown]:  Oracle
What is the name of your City or Locality?
  [Unknown]:  Redwood Shores
What is the name of your State or Province?
  [Unknown]:  CA
What is the two-letter country code for this unit?
  [Unknown]:  US
Is <CN=Test User, OU=Support, O=Oracle, L=Reading, ST=Berkshire, C=GB> correct?
  [no]:  yes

Enter key password for <mykey>
        (RETURN if same as keystore password):

http://www.bcpl.net/~j1m5path/isocodes.html

The mykeystore file is created in the current directory. The default alias of the key is mykey.

Requesting Client Authentication

OC4J supports a client authentication mode in which the server explicitly requests authentication from the client before the server communicates with the client. In an Oracle Application Server environment, Oracle HTTP Server acts as the client to OC4J.

For client authentication, Oracle HTTP Server must have its own certificate and authenticates itself by sending a certificate and a certificate chain that ends with a root certificate. You can configure OC4J to accept only root certificates from a specified list in establishing a chain of trust back to a client.

A certificate that OC4J trusts is called a trust point. In the certificate chain from Oracle HTTP Server, the trust point is the first certificate OC4J encounters that matches one in its own keystore. There are three ways to establish trust:

• The client certificate is in the keystore.

• One of the intermediate CA certificates in the certificate chain from Oracle HTTP Server is in the keystore.

• The root CA certificate in the certificate chain from Oracle HTTP Server is in the keystore.

OC4J verifies that the entire certificate chain, up to and including the trust point, is valid to prevent any forged certificates.

If you request client authentication with the needs-client-auth attribute, perform the following steps. See "OC4J Configuration Steps for SSL" for how to configure this attribute.

1. Decide which of the certificates in the chain from Oracle HTTP Server is to be your trust point. Ensure that you either have control over the issuance of certificates using this trust point or that you trust the certificate authority as an issuer.

2. Import the intermediate or root certificate in the server keystore as a trust point for authentication of the client certificate.

   
   

   Note: If you do not want OC4J to accept certain trust points, make sure these trust points are not in the keystore.

   
   

3. Execute the steps to create the client certificate (documented in "Using Certificates with OC4J and Oracle HTTP Server"). The client certificate includes the intermediate or root certificate that is installed in the server. If you wish to trust another certificate authority, obtain a certificate from that authority.

4. Save the certificate in a file on Oracle HTTP Server.

5. Provide the certificate for the Oracle HTTP Server initiation of the secure AJP connection.

Oracle HTTP Server Configuration Steps for SSL

In Oracle HTTP Server, verify proper SSL settings in mod_oc4j.conf for secure communication. SSL must be enabled, with a wallet file and password specified, as follows:

Oc4jEnableSSL on
Oc4jSSLWalletFile wallet_path
Oc4jSSLWalletPassword pwd

The wallet_path value is a directory path to the wallet file, without a file name. (The wallet file name is already known.) The pwd value is the wallet password.

For more information about the mod_oc4j.conf file, see the Oracle HTTP Server Administrator's Guide.

OC4J Configuration Steps for SSL

In the default-web-site.xml file (or other Web site XML file, as appropriate), you must specify appropriate SSL settings under the <web-site> element.

1. Turn on the secure flag to specify secure communication, as follows:

   <web-site ... secure="true" ... >
      ...
   </web-site>
   
   

   Setting secure="true" specifies that the AJP protocol should use an SSL socket.

2. Use the <ssl-config> subelement and its keystore and keystore-password attributes to specify the path and password for the keystore, as follows:

   <web-site ... secure="true" ... >
      ...
      <ssl-config keystore="path_and_file" keystore-password="pwd" />
   </web-site>
   
   

   The <ssl-config> element is required whenever the secure flag is set to "true".

   The path_and_file value can indicate either an absolute or relative directory path and includes the file name. A relative path is relative to the location of the Web site XML file.

3. Optionally, to specify that client authentication is required, turn on the needs-client-auth flag. This is an attribute of the <ssl-config> element.

   <web-site ... secure="true" ... >
      ...
      <ssl-config keystore="path_and_file" keystore-password="pwd" 
                  needs-client-auth="true" />
   </web-site>
   
   

   This step sets up a mode in which OC4J accepts or rejects a client entity, such as Oracle HTTP Server, for secure communication, depending on its identity. The needs-client-auth flag instructs OC4J to request the client certificate chain upon connection. If OC4J recognizes the root certificate of the client, then the client is accepted.

   The keystore that is specified in the <ssl-config> element must contain the certificates of any clients that are authorized to connect to OC4J through secure AJP and SSL.

Here is an example that sets up secure communication with client authentication:

<web-site display-name="OC4J Web Site" protocol="ajp13" secure="true" >
   <default-web-app application="default" name="defaultWebApp" root="/j2ee" />
   <access-log path="../log/default-web-access.log" />
   <ssl-config keystore="../keystore" keystore-password="welcome" 
              needs-client-auth="true" />
</web-site>

Only the portions in bold are specific to security. The protocol value is always "ajp13" for communication through Oracle HTTP Server, whether or not you use secure communication. A protocol value of ajp13 with secure="false" indicates AJP protocol; ajp13 with secure="true" indicates secure AJP protocol.

For more information about elements and attributes of the <web-site> and <ssl-config> elements, see "Element Descriptions for Web Site XML Files".

Also see "Requesting Client Authentication" for related information.

SSL Common Errors

The following errors may occur when using SSL certificates:

General SSL Debugging

While you are developing in OC4J standalone, you can display verbose debug information from the Java Secure Socket Extension (JSSE) implementation. To get a list of options, start OC4J as follows:

java -Djavax.net.debug=help -jar oc4j.jar 

Start it as follows to enable full verbosity:

java -Djavax.net.debug=all -jar oc4j.jar

This will display the browser request header, server HTTP header, server HTTP body, content length (before and after encryption), and SSL version.