Oracle JavaServer Pages Developer's Guide and Reference Release 8.1.7 Part Number A83726-01 |
Library | Service | Contents | Index

## 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 --%>

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index