Oracle JavaServer Pages Developer's Guide and Reference Release 8.1.7 Part Number A83726-01 |
|
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:
For sample applications, see "Samples Using globals.jsa for Servlet 2.0 Environments".
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:
The globals.jsa
file also provides a vehicle for global Java declarations and JSP directives across all JSP pages of an application.
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.
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.)
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:
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".
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".
JSP implicit objects are available in globals.jsa
event blocks as follows:
application_OnStart
block has access to the application
object.
application_OnEnd
block has access to the application
object.
session_OnStart
block has access to the application
, session
, request
, response
, page
, and out
objects.
session_OnEnd
block has access to the application
and session
objects.
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>
This section provides details about each of the four globals.jsa
event handlers.
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.
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>
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.
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>
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:
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.
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>
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:
session.invalidate()
method.
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.
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>
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:
Directives used within a globals.jsa
file serve a dual purpose:
globals.jsa
file itself.
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" %>
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.
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.)
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:
The following sample globals.jsa
file accomplishes the following:
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.
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. |
|