OracleJSP Application and Session Support for Servlet 2.0

OracleJSP defines a file, globals.jsa, as a mechanism for implementing the JSP specification in a servlet 2.0 environment. Web applications and servlet contexts were not fully defined in the servlet 2.0 specification.

This section discusses the globals.jsa mechanism and covers the following topics:

• Overview of globals.jsa Functionality

• Overview of globals.jsa Syntax and Semantics

• The globals.jsa Event Handlers

• Global Declarations and Directives

For sample applications, see "Samples Using globals.jsa for Servlet 2.0 Environments".

Important: Use all lowercase for the globals.jsa file name. Mixed case works in a non-case-sensitive environment, but makes it difficult to diagnose resulting problems if you port the pages to a case-sensitive environment.

Overview of globals.jsa Functionality

Within any single Java virtual machine, you can use a globals.jsa file for each application (or, equivalently, for each servlet context). This file supports the concept of Web applications in the following areas:

• application deployment--through its role as an application location marker to define an application root

• distinct applications and sessions--through its use by OracleJSP in providing distinct servlet context and session objects for each application

• application lifecycle management--through start and end events for sessions and applications

The globals.jsa file also provides a vehicle for global Java declarations and JSP directives across all JSP pages of an application.

Application Deployment through globals.jsa

To deploy an OracleJSP application that does not incorporate servlets, copy the directory structure into the Web server and create a file called globals.jsa to place at the application root directory.

The globals.jsa file can be of zero size. The OracleJSP container will locate it, and its presence in a directory defines that directory (as mapped from the URL virtual path) as the root directory of the application.

OracleJSP also defines default locations for JSP application resources. For example, application beans and classes in the application-relative WEB_INF/classes and WEB_INF/lib directories will automatically be loaded by the OracleJSP classloader without the need for specific configuration.

Notes: For an application that does incorporate servlets, especially in a servlet environment preceding the servlet 2.2 specification, manual configuration is required as with any servlet deployment. For servlets in a servlet 2.2 environment, you can include the necessary configuration in the standard web.xml deployment descriptor.

Distinct Applications and Sessions Through globals.jsa

The servlet 2.0 specification does not have a clearly defined concept of a Web application and there is no defined relationship between servlet contexts and applications, as there is in later servlet specifications. In a servlet 2.0 environment, such as Apache/JServ, there is only one servlet context object per JVM. A servlet 2.0 environment also has only one session object.

The globals.jsa file, however, provides support for multiple applications and multiple sessions in a Web server, particularly for use in a servlet 2.0 environment.

Where a distinct servlet context object would not otherwise be available for each application, the presence of a globals.jsa file for an application allows the OracleJSP container to provide the application with a distinct ServletContext object.

Additionally, where there would otherwise be only one session object (with either one servlet context or across multiple servlet contexts), the presence of a globals.jsa file allows the OracleJSP container to provide a proxy HttpSession object to the application. (This prevents the possibility of session variable-name collisions with other applications, although unfortunately it cannot protect application data from being inspected or modified by other applications. This is because HttpSession objects must rely on the underlying servlet session environment for some of their functionality.)

Application and Session Lifecycle Management Through globals.jsa

An application must be notified when a significant state transition occurs. For example, applications often want to acquire resources when an HTTP session begins and release resources when the session ends, or restore or save persistent data when the application itself is started or terminated.

In standard servlet and JSP technology, however, only session-based events are supported.

For applications that use a globals.jsa file, OracleJSP extends this functionality with the following four events:

• session_OnStart

• session_OnEnd

• application_OnStart

• application_OnEnd

You can write event handlers in the globals.jsa file for any of these events that the server should respond to.

The session_OnStart event and session_OnEnd event are triggered at the beginning and end of an HTTP session, respectively.

The application_OnStart event is triggered for any application by the first request for that application within any single JVM. The application_OnEnd event is triggered when the OracleJSP container unloads an application.

For more information, see "The globals.jsa Event Handlers".

Overview of globals.jsa Syntax and Semantics

This section is an overview of general syntax and semantics for a globals.jsa file.

Each event block in a globals.jsa file--a session_OnStart block, a session_OnEnd block, an application_OnStart block, or an application_OnEnd block--has an event start tag, an event end tag, and a body (everything between the start and end tags) that includes the event-handler code.

The following example shows this pattern:

<event:session_OnStart>
   <% This scriptlet contains the implementation of the event handler %>
</event:session_OnStart>

The body of an event block can contain any valid JSP tags--standard tags as well as tags defined in a custom tag library.

The scope of any JSP tag in an event block, however, is limited to only that block. For example, a bean that is declared in a jsp:useBean tag within one event block must be redeclared in any other event block that uses it. You can avoid this restriction, however, through the globals.jsa global declaration mechanism--see "Global Declarations and Directives".

For details about each of the four event handlers, see "The globals.jsa Event Handlers".

Important: Static text as used in a regular JSP page can reside in a session_OnStart block only. Event blocks for session_OnEnd, application_OnStart, and application_OnEnd can contain only Java scriptlets.

JSP implicit objects are available in globals.jsa event blocks as follows:

• The application_OnStart block has access to the application object.

• The application_OnEnd block has access to the application object.

• The session_OnStart block has access to the application, session, request, response, page, and out objects.

• The session_OnEnd block has access to the application and session objects.

Example of a Complete globals.jsa File

This example shows you a complete globals.jsa file, using all four event handlers.

<event:application_OnStart>

   <%-- Initializes counts to zero --%>
   <jsp:useBean id="pageCount" class="oracle.jsp.jml.JmlNumber" scope = "application" />
   <jsp:useBean id="sessionCount" class="oracle.jsp.jml.JmlNumber" scope = "application" />
   <jsp:useBean id="activeSessions" class="oracle.jsp.jml.JmlNumber" scope = "application" />

</event:application_OnStart>

<event:application_OnEnd>

   <%-- Acquire beans --%>
   <jsp:useBean id="pageCount" class="oracle.jsp.jml.JmlNumber" scope = "application" />
   <jsp:useBean id="sessionCount" class="oracle.jsp.jml.JmlNumber" scope = "application" />
   <% application.log("The number of page hits were: " + pageCount.getValue() ); %>
   <% application.log("The number of client sessions were: " + sessionCount.getValue() ); %>

</event:application_OnEnd>

<event:session_OnStart>

   <%-- Acquire beans --%>
   <jsp:useBean id="sessionCount" class="oracle.jsp.jml.JmlNumber" scope = "application" />
   <jsp:useBean id="activeSessions" class="oracle.jsp.jml.JmlNumber" scope = "application" />
   <%
      sessionCount.setValue(sessionCount.getValue() + 1);
      activeSessions.setValue(activeSessions.getValue() + 1);
   %>
   <br>
   Starting session #: <%=sessionCount.getValue() %> <br>
   There are currently <b> <%= activeSessions.getValue() %> </b> active sessions <p>

</event:session_OnStart>

<event:session_OnEnd>

   <%-- Acquire beans --%>
   <jsp:useBean id="activeSessions" class="oracle.jsp.jml.JmlNumber" scope = "application" />
   <%
      activeSessions.setValue(activeSessions.getValue() - 1);
   %>

</event:session_OnEnd>

The globals.jsa Event Handlers

This section provides details about each of the four globals.jsa event handlers.

application_OnStart

The application_OnStart block has the following general syntax:

<event:application_OnStart>
   <% This scriptlet contains the implementation of the event handler %>
</event:application_OnStart>

The body of the application_OnStart event handler is executed when OracleJSP loads the first JSP page in the application. This usually occurs when the first HTTP request is made to any page in the application, from any client. Applications use this event to initialize application-wide resources, such as a database connection pool or data read from a persistent repository into application objects.

The event handler must contain only JSP tags (including custom tags) and white space--it cannot contain static text.

Errors that occur in this event handler but are not processed in the event-handler code are automatically trapped by the OracleJSP container and logged using the servlet context of the application. Event handling then proceeds as if no error had occurred.

Example: application_OnStart

The following application_OnStart example is from the "globals.jsa Example for Application Events--lotto.jsp". In this example, the generated lottery numbers for a particular user are cached for an entire day. If the user re-requests the picks, he or she gets the same set of numbers. The cache is recycled once a day, giving each user a new set of picks. To function as intended, the lotto application must make the cache persistent when the application is being shut down, and must refresh the cache when the application is reactivated.

The application_OnStart event handler reads the cache from the lotto.che file.

<event:application_OnStart>

<%
        Calendar today = Calendar.getInstance();
        application.setAttribute("today", today);
        try {
                FileInputStream fis = new FileInputStream
                            (application.getRealPath("/")+File.separator+"lotto.che");
                ObjectInputStream ois = new ObjectInputStream(fis);
                Calendar cacheDay = (Calendar) ois.readObject();
                if (cacheDay.get(Calendar.DAY_OF_YEAR) == today.get(Calendar.DAY_OF_YEAR)) {
                        cachedNumbers = (Hashtable) ois.readObject();
                        application.setAttribute("cachedNumbers", cachedNumbers);       
                }
                ois.close();
        } catch (Exception theE) {
                // catch all -- can't use persistent data
        }
%>

</event:application_OnStart>

application_OnEnd

The application_OnEnd block has the following general syntax:

<event:application_OnEnd>
   <% This scriptlet contains the implementation of the event handler %>
</event:application_OnEnd>

The body of the application_OnEnd event handler is executed when OracleJSP unloads the JSP application. Unloading occurs whenever a previously loaded page is reloaded after on-demand dynamic re-translation (unless the OracleJSP unsafe_reload configuration parameter is enabled), or when the OracleJSP container, which itself is a servlet, is terminated by having its destroy() method called by the underlying servlet container. Applications use the application_OnEnd event to clean up application level resources or to write application state to a persistent store.

The event handler must contain only JSP tags (including custom tags) and white space--it cannot contain static text.

Errors that occur in this event handler but are not processed in the event-handler code are automatically trapped by the OracleJSP container and logged using the servlet context of the application. Event handling then proceeds as if no error had occurred.

Example: application_OnEnd

The following application_OnEnd example is from the "globals.jsa Example for Application Events--lotto.jsp". In this event handler, the cache is written to file lotto.che before the application is terminated.

<event:application_OnEnd>

<%
        Calendar now = Calendar.getInstance();
        Calendar today = (Calendar) application.getAttribute("today");
        if (cachedNumbers.isEmpty() || 
                   now.get(Calendar.DAY_OF_YEAR) > today.get(Calendar.DAY_OF_YEAR)) {
                File f = new File(application.getRealPath("/")+File.separator+"lotto.che");
                if (f.exists()) f.delete();
                return;         
        }

        try {
                FileOutputStream fos = new FileOutputStream
                            (application.getRealPath("/")+File.separator+"lotto.che");
                ObjectOutputStream oos = new ObjectOutputStream(fos);
                oos.writeObject(today);
                oos.writeObject(cachedNumbers);
                oos.close();
        } catch (Exception theE) {
                // catch all -- can't use persistent data
        }
%>

</event:application_OnEnd>

session_OnStart

The session_OnStart block has the following general syntax:

<event:session_OnStart>
   <% This scriptlet contains the implementation of the event handler %>
   Optional static text...
</event:session_OnStart>

The body of the session_OnStart event handler is executed when OracleJSP creates a new session in response to a JSP page request. This occurs on a per client basis, whenever the first request is received for a session-enabled JSP page in an application.

Applications might use this event for the following purposes:

• to initialize resources tied to a particular client

• to control where a client starts in an application

Because the implicit out object is available to session_OnStart, this is the only globals.jsa event handler that can contain static text in addition to JSP tags.

The session_OnStart event handler is called before the code of the JSP page is executed. As a result, output from session_OnStart precedes any output from the page.

The session_OnStart event handler and the JSP page that triggered the event share the same out stream. The buffer size of this stream is controlled by the buffer size of the JSP page. The session_OnStart event handler does not automatically flush the stream to the browser--the stream is flushed according to general JSP rules. Headers can still be written in JSP pages that trigger the session_OnStart event.

Errors that occur in this event handler but are not processed in the event-handler code are automatically trapped by the OracleJSP container and logged using the servlet context of the application. Event handling then proceeds as if no error had occurred.

Example: session_OnStart

The following example makes sure that each new session starts on the initial page (index.jsp) of the application.

<event:session_OnStart>

   <% if (!page.equals("index.jsp")) { %>
         <jsp:forward page="index.jsp" />
   <% } %>

</event:session_OnStart>

session_OnEnd

The session_OnEnd block has the following general syntax:

<event:session_OnEnd>
   <% This scriptlet contains the implementation of the event handler %>
</event:session_OnEnd>

The body of the session_OnEnd event handler is executed when OracleJSP invalidates an existing session. This occurs in either of the following circumstances:

• The application invalidates the session by calling the session.invalidate() method.

• The session expires (times out) on the server.

Applications use this event to release client resources.

The event handler must contain only JSP tags (including tag library tags) and white space--it cannot contain static text.

Errors that occur in this event handler but are not processed in the event-handler code are automatically trapped by the OracleJSP container and logged using the servlet context of the application. Event handling then proceeds as if no error had occurred.

Example: session_OnEnd

The following example decrements the "active session" count when a session is terminated.

<event:session_OnEnd>

     <%-- Acquire beans --%>
     <jsp:useBean id="activeSessions" class="oracle.jsp.jml.JmlNumber" scope = "application" />
     
     <%
         activeSessions.setValue(activeSessions.getValue() - 1);
     %>

 </event:session_OnEnd>

Global Declarations and Directives

In addition to holding event handlers, a globals.jsa file can be used to globally declare directives and objects for the JSP application. You can include JSP directives, JSP declarations, JSP comments, and JSP tags that have a scope parameter (such as jsp:useBean).

This section covers the following topics:

• Global JSP Directives

• globals.jsa Declarations

• Global JavaBeans

• globals.jsa Structure

• Global Declarations and Directives Example

Global JSP Directives

Directives used within a globals.jsa file serve a dual purpose:

• They declare the information that is required to process the globals.jsa file itself.

• They establish default values for succeeding pages.

A directive in a globals.jsa file becomes an implicit directive for all JSP pages in the application, although a globals.jsa directive can be overwritten for any particular page.

A globals.jsa directive is overwritten in a JSP page on an attribute-by-attribute basis. If a globals.jsa file has the following directive:

<%@ page import="java.util.*" bufferSize="10kb" %>

and a JSP page has the following directive:

<%@page bufferSize="20kb" %>

then this would be equivalent to the page having the following directive:

<%@ page import="java.util.*" bufferSize="20kb" %>

globals.jsa Declarations

If you want to declare a method or data member to be shared across any of the event handlers in a globals.jsa file, use a JSP <%!... %> declaration within the globals.jsa file.

Note that JSP pages in the application do not have access to these declarations, so you cannot use this mechanism to implement an application library. Declaration support is provided in the globals.jsa file for common functions to be shared across event handlers.

Global JavaBeans

Probably the most common elements declared in globals.jsa files are global objects. Objects declared in a globals.jsa file become part of the implicit object environment of the globals.jsa event handlers and all the JSP pages in the application.

An object declared in a globals.jsa file (such as by a jsp:useBean statement) does not need to be redeclared in any of the individual JSP pages of the application.

You can declare a global object using any JSP tag or extension that has a scope parameter, such as jsp:useBean or jml:useVariable. Globally declared objects must be of either session or application scope (not page or request scope).

Nested tags are supported. Thus, a jsp:setProperty command can be nested in a jsp:useBean declaration. (A translation error occurs if jsp:setProperty is used outside a jsp:useBean declaration.)

globals.jsa Structure

When a global object is used in a globals.jsa event handler, the position of its declaration is important. Only those objects that are declared before a particular event handler are added as implicit objects to that event handler. For this reason, developers are advised to structure their globals.jsa file in the following sequence:

1. global directives

2. global objects

3. event handlers

4. globals.jsa declarations

Global Declarations and Directives Example

The following sample globals.jsa file accomplishes the following:

• It defines the JML tag library (in this case, the compile-time implementation) for the globals.jsa file, as well as for all subsequent pages.

  By including the taglib directive in the globals.jsa file, the directive does not have to be included in any of the individual JSP pages of the application.

• It declares three application variables for use by all pages (in the jsp:useBean statements).

For an additional example of using globals.jsa for global declarations, see "globals.jsa Example for Global Declarations--index2.jsp".

<%-- Directives at the top --%>

   <%@ taglib uri="oracle.jsp.parse.OpenJspRegisterLib" prefix="jml" %>

<%-- Declare global objects here --%>

   <%-- Initializes counts to zero --%>
   <jsp:useBean id="pageCount" class="oracle.jsp.jml.JmlNumber" scope = "application" />
   <jsp:useBean id="sessionCount" class="oracle.jsp.jml.JmlNumber" scope = "application" />
   <jsp:useBean id="activeSessions" class="oracle.jsp.jml.JmlNumber" scope = "application" />

<%-- Application lifecycle event handlers go here --%>

   <event:application_OnStart>
      <% This scriptlet contains the implementation of the event handler %>
   </event:application_OnStart>

   <event:application_OnEnd>
      <% This scriptlet contains the implementation of the event handler %>
   </event:application_OnEnd>

   <event:session_OnStart>
      <% This scriptlet contains the implementation of the event handler %>
   </event:session_OnStart>

   <event:session_OnEnd>
      <% This scriptlet contains the implementation of the event handler %>
   </event:session_OnEnd>

<%-- Declarations used by the event handlers go here --%>

---