<title css='default.css'>JSP Applications</title>

<summarylist/>

<section title='Introduction'>

JSP groups pages into applications which share common state.  A
bulletin board application groups pages for article reading, group
listing, user registration, and new article posting into a single
application.

<p/>Applications can keep track of user sessions, giving the users the
illusion of a single application out of disjointed pages.

<ul>
<li/>JSP organizes applications with an .application <a
href='#dir'>directory</a>.
<li/>The <a href='#global'>global.jsa</a> file contains common
declarations and procedures for starting and stopping sessions and
applications.
<li/><a href='#session'>Sessions</a> share state for a user's visit to
the site.
</ul>

</section>

<section name='dir' title='.application directory'>
The .application directory organizes an application.  It defines an
application docroot by its presense.  All files and directories in the
docroot are part of the same application.

<deftable title='.application contents'>
<tr><th>File/Directory</th><th>Contents</th></tr>
<tr><td>global.jsa</td><td>control file</td></tr>
<tr><td>scripts</td><td>common scripts</td></tr>
<tr><td>data</td><td>file data, e.g. text and xml</td></tr>
<tr><td>beans</td><td>Java class files for beans</td></tr>
<tr><td>tags</td><td>Java class files for tag compilation</td></tr>
</deftable>

<example title='Example directory structure'>
newsgroup/              // application docroot
  .application/         // application data
    global.jsa          // global control
    scripts/            // included scripts
      common.es
    data/               // application storage
      art1.xml          // example article
      art2.xml          // another article
    beans/              // application beans
      article.class     // Java article code
    tags/               // application tags
      dateHandler.class // date tag
  list.jsp              // list articles
  read.jsp              // read an article
  post.jsp              // post an article
</example>

<subsection title='Scripts'>
JSP applications can group common functions and classes into script
files, organizing and simplifying the application.  The individual
pages can then <a href='statements.html#import'>import</a> the common
scripts to use them.  JSP pages can focus on HTML presentation and the script
libraries can concentrate on the content.

<p/>As described in the <a href='statements.html#import'>import</a>
documentation, <resin/> searches for imported scripts along a
SCRIPTPATH.  For JSP pages, the SCRIPTPATH looks in the application
script directory first, then in the global libraries.

<def title='JSP SCRIPTPATH'>
  $APPDIR/.application/scripts
    :$RESIN_HOME/scripts
</def>
</subsection>

<subsection title='Data'>
The data subdirectory of .application can contain any data the JSP
application needs to store.  It could contain persistent state for a
counter, to the entire article tree for a complicated discussion
server.

<p/>The <a href='file.html'>File</a> object in a JSP script uses
.application/data as its current directory.
</subsection>

<subsection title='Tags'>
JSP 1.0 provides an extensible tag
architecture, allowing applications to design their own active
tags.  The tag handlers are Java classes extending the
<code/ChunkHandler/> interface.  When the JSP parser encounters a new
tag, it looks in tags for a matching class.
</subsection>

</section>

<section name=global title='global.jsa'>
The global.jsa file contains common declarations, application and
session bean declarations, and event handlers.  Its structure
resembles to a JSP file, except that it never creates content.

<p/>Session and application beans must be declared
in a global.jsa <a href='jsp.html#usebean'>jsp:usebean</a> directive.
Only page beans may be declared in a *.jsp file.  The
application beans will be instantiated when the first page of the
application is accessed and will persist until the server shuts down.

<p/><a href='jsp.html#error'>Error pages</a> global to the entire
application may be declared in the global.jsa file.  Local error page
declarations override the global declarations.

<p/>The <a href='jsp.html#language'>language</a> declared in the
global.jsa file is local to the global file.  It only declares the
language for the <a href='jsp.html#decl'>declaration</a> section and
the event handlers.

<subsection title='Event Handlers'>
Applications can declare event handlers to execute when an application
starts or stops and when a session starts and stops.  The event
handlers can initialize state, read data from storage, and store the
final state when the server shuts down.

<p/>Applications start on the first page access.  The application event
handlers <a href='jsp.html#appOnStart'>jsp:application:onStart</a> and
<a href='jsp.html#appOnEnd'>jsp:application:onEnd</a>
can use the <a href='jsp.html#application'>application</a> object.

<p/>Sessions start when a page accesses session state or when a
session bean is created.  Sessions end when the server times them out,
when the application ends, or when they are invalidated.  The session
event handlers <a href='jsp.html#sessionOnStart'>jsp:session:onStart</a> and
<a href='jsp.html#sessionOnEnd'>jsp:session:onEnd</a>
can use the <a href='jsp.html#session'>session</a> and
<a href='jsp.html#application'>application</a> objects.

<example title='Persistent Storage of Counter'>
&lt;jsp:application:onStart&gt;
  var file = File("counter");
  if (file.exists()) {
    var is = file.openRead();
    var counter = new Number(is.readln());
    is.close();
  } else
    var counter = 0;

  application.attributes.counter = counter;
&lt;/jsp:application:onStart&gt;

&lt;jsp:application:onEnd&gt;
  var os = File("counter").openWrite();
  os.writeln(application.attributes.counter);
  os.close();
&lt;/jsp:application:onEnd&gt;
</example>

</subsection>

</section>

<section name=session title='Sessions'>
Session variables let applications keep track of the user as she moves
through the site.  Any e-commerce site needs this capability to keep
track of the user's purchases.

<p/>JSP sessions start when the page accesses the <a
href='jsp.html#session'>session</a> variable.  If a page never uses
sessions, the jsp:session:onStart code will not execute and the web
server will not send the client any cookies.

<p/>Sessions end when the session times out, when the session is
invalidated, or when the application ends.

<p/><resin/> locks the session variable before executing the page.  So
JSP applications don't need to worry about synchronizing the session
variable.
</section>

<section name=beans title='JSP Beans'>
<p/>Java Beans get first class treatment in JSP 1.0.  Beans can be
created for a page, across a session, or for the entire application.

<p/>The .application/beans subdirectory can contain <a
href='jspapp.html#beans'>application beans</a> used by <a
href='jsp.html#usebean'>jsp:usebean</a>.  These are simply Java
classes implementing the bitmechanic work of an application.

<p/>For example, a shopping cart application may have a set of Java
classes that perform the security necessary for credit card
processing.  The application can put those classes in the beans
directory and access them from the JSP page.

Beans can be created with different lifetimes.
<ul>
<li/>Application beans last the lifetime of an application.
<li/>Session beans last for a user's session.
<li/>Page beans only last for a single page.
</ul>

<subsection title='Accessing Beans'>
Each bean is defined with a <a href='jsp.html#usebean'>jsp:usebean</a>
directive.  Page beans are defined in the JSP page. Session and
application beans are defined in the global.jsa file.

<p/>JSP assigns the created bean object to the <resinscript/> variable
named by jsp:usebean.

<p/>In addition, the created beans are stored in JSP variables: page
beans are stored in <code/request/>, session beans are stored in
<code/session/>, and application beans are stored in
<code/application/>.  Storing the beans in the JSP variables lets
other beans and functions retrieve the beans.

<example title='Beans in variables: test.jsp'>
&lt;jsp:usebean name='test' class='java.util.Hashtable'&gt;

&lt% test.put("a", 1); %&gt;
&lt%= test.get("a"); %&gt;
</example>

<example>
<example title='Page beans in request: test.jsp'>
&lt;jsp:usebean name='test' class='java.util.Hashtable'&gt;

&lt;% 
  var t = request.attributes["beans/test"] 
  t.put("a", 1);
%&gt;
&lt%= test.get("a"); %&gt;
</example>
<results>
1
</results>
</example>

</subsection>

</section>

