<document> <header>
<product>resin</product>
<title>An Overview of Web Applications</title>
<description>
<p>
A web application is a self-contained subtree of the web site.  It uses
Servlets, Filters, JSP, and the functionality provided by Resin and any other
java code to provide a response to a client that makes an HTTP request.
</p>
</description>
</header>

<body>

<localtoc/>

<s1 title="Web applications">

<p>
Each web application is part of the web server.  It has a unique name or
path that identifies it within the server.
</p>

<p>
Each web application has a corresponding url. The url begins with the part
needed to identify the server, followed by the webapp path:
<code>http://server<var>/webapp-name</var></code>.  Each server has one
web-app that is the default, it is the one that is used when no webapp-name is
provided.
</p>

<p>
Web applications are "deployed" within a web server, such as Resin.  The
simplest way to "deploy" a new web application is to the create a subdirectory
in <code>$RESIN_HOME/webapps/<var>webapp-name</var></code>.  The special
webapp name <code>ROOT</code> is used for the default web application. (There
are other <a href="webapp-deploy.xtp">deployment options</a>, but for the
purposes of this discussion the one described here is used).
</p>

<p>
A web application has "web components", such as Servlets, Filters, JSPs,
supporting Java source files, and supporting java libraries.
</p>

<s2 title="Try it!">

<p>
You can make your own web application in a local install of Resin.  Make a
directory <code>$RESIN_HOME/webapps/test</code>.  Use the url
<code>http://localhost:8080/test</code> to access the web application.
</p>

<p>
To start with, you can make a file named
<code>$RESIN_HOME/test/index.jsp</code>.
</p>

<example title="$RESIN_HOME/test/index.jsp">
Hello, world!
</example>

<p>
<code>index.jsp</code> is a JSP file, and is also the name of the default page
to show for a directory.  So you can use the url
<code>http://localhost:8080/test/index.jsp</code> in your browser, or since
<code>index.jsp</code> is the default page to show, you can use
<code>http://localhost:8080/test</code>.  
</p>

</s2>

<s2 title="Example web application">

<p>
For example, <code>www.hogwarts.com</code> has two web
applications, the <var>default</var> web application, and a web-application
named "intranet".
</p>

<p>
<b>Server:</b> www.hogwarts.com<br/>
<b>Server URL:</b> http://www.hogwarts.com<br/>
<br/>
<b>webapp:</b> default webapp<br/>
<b>webapp URL:</b> http://www.hogwarts.com/<br/>
<b>filesystem directory:</b> $RESIN_HOME/webapps/ROOT<br/>
<b>default jsp page:</b> $RESIN_HOME/webapps/ROOT/index.jsp<br/>
<br/>
<b>webapp:</b> intranet<br/>
<b>webapp URL:</b> http://www.hogwarts.com/intranet<br/>
<b>filesystem directory:</b> $RESIN_HOME/webapps/intranet<br/>
<b>default jsp page:</b> $RESIN_HOME/webapps/intranet/index.jsp<br/>
</p>

</s2> <!-- Example web application -->

</s1>

<s1 name="components" title="Components of a web application">

<s2 name="servlet" title="Servlet">

<p>
From the Servlet Specification 3.0:
</p>

<blockquote>
A servlet is a web component, managed by a container, that generates
dynamic content. Servlets are small, platform independent Java classes
compiled to an architecture neutral bytecode that can be loaded
dynamically into and run by a web server. Servlets interact with web
clients via a request response paradigm implemented by the servlet
container. This request-response model is based on the behavior of the
Hypertext Transfer Protocol (HTTP).
</blockquote>

<p>
A Servlet is a Java class that has a method that gets called with
information about a client request and is expected to produce some
kind of result to be sent back to the client. It is just like any
other class in Java, it happens to inherit from <a href="javadoc|javax.servlet.http.HttpServlet|"/>, so Resin can call certain
methods on it when a request is made.  
</p>

<p>
A Servlet class is made available by placing the <code>.java</code> source file
in the approriate sub-directory and file of <code>WEB-INF/classes</code>:
</p>

<example title="WEB-INF/classes/example/HelloWorldServlet.java">
package example;

import java.io.*;

import javax.servlet.http.*;
import javax.servlet.*;

/**
 * Hello world servlet.  Most servlets will extend
 * javax.servlet.http.HttpServlet as this one does.
 */
public class HelloServlet extends HttpServlet {
  /**
   * Initialize the servlet.  Servlets should override this method
   * if they need any initialization like opening pooled
   * database connections.
   */
  public void init() throws ServletException
  {
  }

  /**
   * Implements the HTTP GET method.  The GET method is the standard
   * browser method.
   *
   * @param request the request object, containing data from the browser
   * @param repsonse the response object to send data to the browser
   */
  public void doGet (HttpServletRequest request,
                     HttpServletResponse response)
    throws ServletException, IOException
  {
    // Returns a writer to write to the client
    PrintWriter out = response.getWriter();

    // Write a string to the browser.
    out.println("Hello, world!");
    out.close();
  }
}
</example>

<p>
Entries in ithe <code>WEB-INF/web.xml</code> file tell Resin the URL that
should invoke the Servlet:
</p>

<example title="WEB-INF/web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;servlet&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-name&gt;
    &lt;servlet-class&gt;example.HelloServlet&lt;/servlet-class&gt;
  &lt;/servlet&gt;

  &lt;servlet-mapping&gt;
    &lt;url-pattern&gt;/hello&lt;/url-pattern&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-name&gt;
  &lt;/servlet-mapping&gt;
&lt;/web-app&gt;
</example>

<p>
In a web-app named "foo" on a server named "localhost" listening on port
"80", the servlet is now invoked with the URL
<code>http://localhost:8080/foo/hello</code>.
</p>

<p>More information on the usage of Servlets is available in the <a href="servlet.xtp">Servlet</a> section of the Resin documenation.</p>

</s2> <!-- servlet -->

<s2 name="jsp" title="JSP">

<p>
Java Server Pages are text files that contain text to be output (usually
HTML or somesuch) and special directives, actions, scripting elements, and
expressionsthat are used to generate results dynamically.  
</p>

<p>
From the JSP 2.0 specification:
</p>

<blockquote>
JavaServer Pages technology supports scripting elements as well as actions.
Actions encapsulate useful functionality in a convenient form that can be
manipulated by tools. Expressions are used to access data. Scripts can be used
to glue together this functionality in a per-page manner.
</blockquote>

<p>
With JSP the developer specifies the content mostly as the kind of thing they
want to send back to the client or browser, for example HTML.  Optionally
interspersed with the HTML are special xml tags (directives and actions), EL
expressions, or specially marked scripting code (Java code).   The special xml
tags, EL expressions and Java code are used to generate dynamic ouput.
</p>

<s3 name="jsp-translation" title="JSPs are translated into Servlets">
<p>
It is helpful to understand what it is that Resin does with a
JSP page.  Basically, it takes the JSP page and turns it into the Java
code for a Servlet, a process of <var>translation</var>.  

</p><p>From the JSP specification: </p>

<blockquote>
JSP pages are textual components.  They go through two
phases: a translation phase, and a request phase. Translation is done
once per page. The request phase is done once per request.
</blockquote>

<p>
The translation phase occurs when Resin takes a look at the
JSP page, reads it in, and creates a Servlet. This only needs to be
done once. Now when a request from a client comes in, Resin
will call the appropriate method in the Servlet that it created from the.
</p>

<p>
During translation, Resin takes all of the code that has been specially
marked in the JSP as java code and inserts it directly into the code for a
Servlet.  It takes all of the template text and makes the equivalent of print
statements to generate that ouput.
</p>

<p>
Because JSP files are translated into Servlets, JSP is an extension to Java
Servlets. Everything that applies to Java Servlets also applies to JSP.  Much
information that is relevent to JSP programming is found in documentation about
Java Servlets.  So you want to have the Servlet Specification around as a handy
reference, as well as the JSP Specification.  Any reference to the capabilities
and resources available to a Servlet are also available to a JSP page.  
</p>

<p>
This process is invisible to the JSP developer, all the developer
needs to do is make the JSP page and Resin will look at it and
turn it into a Servlet.
</p>

</s3> <!-- jsp-translation -->

<s3 name="jsp-syntax" title="The syntax of a JSP file">

<p>JSP has it's own <a href="jsp.xtp">section</a> in the Resin documentation,
the following is an introductory guide.</p>


<s4 title="template data - The text to be output">

<p>
Unless specially marked, the text in the JSP file will be sent exactly
as it is in the text file as part of the response. This is called
<var>template data</var> in the JSP specification.
</p>

</s4>

<s4 title="JSP EL and JSTL">

<p>
JSP EL is the JSP <var>Expression Language</var>.  It is used to evaluate
expressions that do not have side-effects (side-effects are changes to
Objects). The use of EL is recognizable by it's syntax: 
<code>${'${'} <var>expr</var> }</code>.
</p>

<p>
JSTL is the JavaServer Pages Standard Tag Libray, a set of <var>tags</var> that are
used to create dynamic output from JSP.  These tags look like regular XML tags,
and are interpreted by Resin at translation time to generate java code that
performs the desired action.
</p>

<p>
EL and JSTL are used throughout this discussion, the <a href="jsp.xtp">Resin JSP documentation</a>, the <a href="jstl.xtp">JSTL documentation</a> provide
more information.
</p>

<example title="x.jsp - Example JSP file using EL and JSTL">
&lt;%@page session="false" contentType="text/html" %&gt;
&lt;%@taglib uri="http://java.sun.com/jstl/core" prefix="c" %&gt;

&lt;head&gt;
&lt;title&gt;A simple thing&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;

&lt;!-- this comment gets all the way to the browser --&gt;
&lt;%-- this comment gets discarded when the JSP is translated into a Servlet --%&gt;
&lt;%
// some java code that makes the variable `x' available to EL
pageContext.setAttribute("x",new Integer(5));
%&gt;

The value of x is ${'${'} x }
The value of x + 2 is ${'${'} x + 2 }
Is x
less than 6?
&lt;c:if test="${'${'} x &lt; 6 }"&gt;
&lt;%@include file="y.jsp" %&gt;
&lt;/c:if&gt;
&lt;/body&gt;
</example>

<example title="y.jsp - Example java code in JSP file to be included">
Yes, it is true that x is less than 6, 
with a value of ${'${'} x }
</example>

<results title="x.jsp output - The result of a call to x.jsp">
&lt;head&gt;
&lt;title&gt;A simple thing&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;!-- this comment gets all the way to the browser --&gt;


The value of x is 5.
The value of x + 2 is 7.
Is x
less than 6?

Yes, it is true that x is less than 6,
with a value of 5.
&lt;/body&gt;
</results>
<p>
Prior to the introduction of JSTL and EL, JSP pages used the direct insertion
of Java code to accomplish the same thing.  The use of JSTL and EL is much
cleaner and more maintable.
</p>

</s4>

<s4 title="Including other files">

<p>
Often it is desirable to include the contents of another file into a
JSP file. For example, sometimes there is code that you find yourself
using over and over again. The mechanism for this is the
<var>include</var> directive:
</p>

<example>
&lt;%@ include file="<var>relativeURLspec</var>"%&gt;
</example>

<p>
Using the include directive it is exactly the same as if the included
text was in the original file.  The text is included at translation
time - when the JSP is turned into a servlet.
</p>

</s4>

<s4 title="Specifying content type">

<p>
A JSP page can use the <var>contentType</var> attribute of the
<code>page</code> directive to indicate the content type of the response it
 is sending. For example, <code>text/html</code> and
<code>text/wml</code> are valid content types.
</p>

<p>
Since this value is part of a directive, a given page will always
provide the same content type. It is also possible to dynamically
indicate the content type using the <code>response</code> object, which is
discussed later.
</p>

</s4>

<s4 title="Comments">

<p>
A JSP comment is of the form:
</p>

<example title="JSP comments">
&lt;%-- anything but a closing --%&gt; ... --%&gt;
</example>

<p>
The body of the JSP content is ignored completely. JSP Comments are discarded
at translation time, they do not become part of the Servlet that is used to
generate the response.  Comments are useful for documentation but also to
comment out some portions of a JSP page. JSP comments do not nest.
</p>

<p>
In order to generate comments that appear in the response to the requesting
client, the HTML and XML comment syntax is used, as follows:
</p>

<example title="HTML comments">
&lt;!-- comments ... --&gt;
</example>

</s4>

<s4 title="Java code in the JSP file">

<p>
Java code in the JSP is marked by the special characters <code>&lt;%</code>
and <code>%&gt;</code>.  To insert the value of a variable or an expression in
the output it is marked with <code>&gt;&lt;%= <var>expr</var> &amp;&gt;</code>.
</p>

<p>
Be careful not to depend on the ability of JSP to include Java code too much.
JSP is best used to present a <var>view</var> of data that has already been
prepared in Servlets or other code, as discussed in <a href="#architecture">Architecture</a>.
</p>

<p>
Now that JSTL and JSP EL exist, they are preferred over the insertion of Java
code directly.
</p>

<example title="x.jsp - Example java code in JSP file">
&lt;%@page session="false" contentType="text/html" import="java.util.*, example.*%&gt;

&lt;head&gt;
&lt;title&gt;A simple thing&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;!-- this comment gets all the way to the browser --&gt;
&lt;%-- this comment gets discarded when the JSP is translated into a Servlet --%&gt;
<b>&lt;% int x = 5; // java-style comments valid here %&gt;</b>
The value of x is <b>&lt;%= x %&gt;</b>.
The value of x + 2 is <b>&lt;%= x + 2 %&gt;</b>.
Is x
less than 6?
<b>&lt;% if (x &lt; 6) { %&gt;</b>
&lt;%@include file="y.jsp" %&gt;
<b>&lt;% } %&gt;</b>
&lt;/body&gt;
</example>

<example title="y.jsp - Example java code in JSP file to be included">
Yes, it is true that x is less than 6, 
with a value of <b>&lt;%= x %&gt;</b>.
</example>

<results title="x.jsp output - The result of a call to x.jsp">
&lt;head&gt;
&lt;title&gt;A simple thing&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;!-- this comment gets all the way to the browser --&gt;


The value of x is 5.
The value of x + 2 is 7.
Is x
less than 6?

Yes, it is true that x is less than 6,
with a value of 5.
&lt;/body&gt;
</results>

</s4>


<s4 title="Importing Java packages">

<p>
Usually when making a JSP the developer draws on classes from various
packages. Unless these packages are imported, the use of such a class
must include the fully qualified class name:
</p>

<example>
&lt;%
java.util.Date d = new java.util.Date();
%&gt;
</example>

<p>
Packages can be imported with the <var>import</var> attribute of the
<var>page</var> directive. Multiple packages are seperated with a comma:
</p>

<example>
&lt;%@ page import="java.util.*, example.*" %&gt;
&lt;%
Date d = new Date();
%&gt;
</example>

</s4>



<s4 title="Custom tag libraries">

<p>
Custom tag libraries are a mechanism that allows developers to make
functionality available to a JSP author through the use of XML tags.
</p>

<p>
As an example, a mail tag can be implemented and then used in the JSP
in the following manner:
</p>

<example title="HogwartsRegistrationMail.jsp - an example usage of a taglib">
&lt;mail:mailMessage 
  from="registration@hogwarts.com" 
  to="&lt;%= userEmail %&gt;" 
  subject="Hogwarts Registration"&gt;

Thank-you for registering with the Hogwarts news service.  We will be sending
you an email with twice-weekly with updates and the latest news from Hogwarts.

&lt;/mail:mailMessage&gt;
</example>

<p>
Tag libraries can be very useful, however they are somewhat
complicated to implement. They are probably best left to developers of
libraries -- the taglibs can provide some simple access to the
functionality of the library.
</p>

<p>
More information on implementing custom tag libraries is in the <a href="jsp.xtp">JSP section</a> of the Resin documentation.
</p>

</s4>

</s3> <!-- jsp-syntax -->


</s2> <!-- jsp -->

<s2 name="filter" title="Filter">

<p>
From the Servlet Specification 2.4:
</p>

<blockquote>
A filter is a reusable piece of code that can transform the content of HTTP
requests, responses, and header information. Filters do not generally create a
response or respond to a request as servlets do, rather they modify or adapt
the requests for a resource, and modify or adapt responses from a resource.
</blockquote>

<p>
A Filter is a Java class that is used to <var>intercept</var> the request and the
response ("<a href="#requestresponse">request</a>" and 
"<a href="#responseresponse">response</a>" are discussed later).  A filter can
intercept the request before it get's to other web components, such as a JSP or
Servlet, and change what the request looks like.  A filter can intercept the
response that is generated by web components, such as a JSP or Servlet, and
change (transform) the reponse before it is sent to the client.  
</p>

<p>More information on the usage of Filters is available in the <a href="servlet.xtp">Servlets and Filters</a> section of the Resin documenation.</p>

</s2> <!-- filter -->


<s2 name="classes" title="Custom java code">

<p>A developer can, and usually does, use the general facilities of Java to
create custom Java classes that are used by the Servlets, JSP, Filters, and
other components of the web applications.  Java source files are placed in the
<code>WEB-INF/classes/</code>  directory (for example,
<code>WEB-INF/classes/com/hogwarts/Util.java</code>, and are automatically
compiled by Resin.</p>

</s2> <!-- classes -->

<s2 name="lib" title="Java code libraries">

<p>A web application can take advantage of java code libraries.  These
libraries are usually packaged in a <code>.jar</code> file, and placed in the
<code>WEB-INF/lib</code> directory (for example,
<code>WEB-INF/lib/batik.jar</code>).  The libraries in the jar file are then
available to the Servlet, JSP, Filter, and other components of the web
application.</p>

<p>Jar libraries usually contain code that is not specific to the web
application, for example a library that provides a database driver, or a
library that is used to generate images.</p>

</s2> <!-- classes -->

</s1> <!-- components -->


<s1 title="The structure of web applications">

<p>
The componets of a web application are placed in appropriate files and
configured using the <code>WEB-INF/web.xml</code> file.  
</p>

<s2 title="Directory structure">

<deftable title="Web application directory structure">
<tr><th>File</th><th>Description</th></tr><tr><td>/index.jsp</td><td>A jsp file that is usually the default file that is accesed 
</td></tr><tr><td>/WEB-INF/web.xml</td><td>The file that configures the Web Application
</td></tr><tr><td>/WEB-INF/classes</td><td>A directory containing classes specific to this
application
</td></tr><tr><td>/WEB-INF/classes/com/hogwarts/foo/Util.java</td><td>&#160;
</td></tr><tr><td>/WEB-INF/classes/com/hogwarts/foo/Util.class</td><td>&#160;
</td></tr><tr><td>/WEB-INF/lib</td><td>A directory containing jar files 
</td></tr><tr><td>/WEB-INF/lib/mysql-connector-java-3.0.9-stable-bin.jar</td><td>An example usage of the lib directory, the MySQL driver
</td></tr></deftable>

<p>
For the most part, the directory structure of a web application
reflects the structure that the end-user will see from their browser.
</p>

<p>
In addition, a special directory named
<code>WEB-INF</code> is recognized by Resin.
</p>

<p>
This directory contains a <code>WEB-INF/classes</code> sub-directory which is
where you put any Java classes that are specifically for
your application.
</p>

<p>
There is also a <code>WEB-INF/lib</code> directory which can contain .jar files
for libraries that are needed by the application.  These .jar files are usually
third-party libraries or libraries that are reused amongst many different web
applications.
</p>

<p>
Finally, the file <code>WEB-INF/web.xml</code> is used to
configure your web application.
</p>

</s2>

<s2 title="web.xml">

<p>
A Web Application is configured with a deployment descriptor that
collects information about the JSP pages, Servlets, security zones,
and other resources used in the Web Application.
</p>

<p>
A full description of it can be found in the JSP specification.
</p>

<s3 title="A note about path seperators">

<p>
In the web.xml file (and in Java programming in general), always use
"/" as the path seperator. Do not use the MS-DOS/Windows "\"
path seperator.
</p>

</s3>

</s2> <!-- web.xml -->


<s2 title="Automatic compilation">

<p>
A convenience that is provided by Resin is the automatic
compilation of Java files that are changed.
</p>

<p>
You can take advantage of this by placing your java source files in
the <code>WEB-INF/classes/...</code> directory of your web application.
</p>

<p>
For example, if you have a file <code>Util.java</code>, in package
<code>com.hogwarts.foo</code>, place the file in
<code>WEB-INF/classes/com/hogwarts/foo/Util.java</code>. Now any
changes to <code>Util.java</code> will result in the automatic recompilation of
the java file into a class file.
</p>

</s2>

</s1> 


<s1 name="lifecycle" title="Lifecycle: ServletContexts, Sessions, Requests, Responses">

<p>
ServletContexts, Sessions, Requests, and Responses have corresponding
java objects that Resin creates. Each of these objects has a
unique scope: they are created at a certain time and destroyed at a
certain time.
</p>

<p>
The JavaServer Pages specification inherits from the Servlet
specification the concepts of ServletContexts, Sessions,
Requests and Responses.
</p>

<p>
These objects are created by Resin, they are always available
to a Servlet, Filter, or JSP page.
</p>

<s2 name="servletContext" title="ServletContext">

<p>
A ServletContext provides a view of the application that the Servlet, Filter,
or JSP is running in. The ServletContext models the Web Application. A
ServletContext is an object that is common to all
Servlets in an application.
</p>

<p>
A ServletContext is represented by a 
<a href="javadoc|javax.servlet.ServletContext"/> object.  
</p>

<s3 title="Scope of the ServletContext">

<p>
Resin creates a ServletContext as soon as the Web Application
is started, and it remains until the Web Application is closed.  There
is one ServletContext made for each web application, and any usage of
the ServletContext will always use the same one.
</p>

</s3>
</s2> <!-- servletContext -->

<s2 name="requestresponse" title="Request and Response">

<p>
Every time a user follows a URL that points to a Servlet or JSP within
the Web Application, Resin creates a Request object to
represent the current request.  Resin also creates a Response object
which the developer can use to set certain things that apply to the
response to the users browser.
</p>

<p>
A request is represented by a 
<a href="javadoc|javax.servlet.http.HttpServletRequest"/> object.  
A response is represented by a 
<a href="javadoc|javax.servlet.http.HttpServletResponse"/> object.  
</p>

<s3 title="Scope of the Request and Response">

<p>
A new Request and Response are created each time the user follows a
link into the Web Application. These objects last until the response
is sent back to the client. 
</p>

</s3>

</s2> <!-- requestresponse -->


<s2 name="session" title="Session">

<p>
A Session is established for each user of the web application. The
first time a user accesses anything within the web application, 
Resin recognizes this unknown user and creates a new Session to
represent them. This Session object will remain the same for that user
for the duration of their use of the web application.
</p>

<p>
A session is represented by a 
<a href="javadoc|javax.servlet.http.HttpSession"/> object.  
</p>

</s2>

<s2 title="Scope of the Session">

<p>
The Session is created the first time a user access a component in the 
web application that requests the session.  Resin sees the incoming request
from a user and checks to see if it has a Session for that user. If it does
not, it creates one. This session object will remain the same for that
user.
</p>

<p>
The end of the session object is a bit complicated. Since 
Resin cannot tell the difference between when the user has stopped
using the application and when the user is just taking a long time to
do something, Resin must guess.  Resin uses a time-out
value to determine when it should assume that the user has gone
away, it defaults to 30 minutes. What this means is that if a user has
not accessed any resource in the Web application for 30 minutes the
Resin will destroy the session object for that user.
</p>

<p>
A developer can also explicitly destroy the Session object, and that
is discussed later.
</p>

<s3 title="How Resin keeps track of the Session">

<p>
Resin establishes a session by giving the user's browser a
unique id that is returned back to Resin with each new
request. This is accomplished in one of two ways: using cookies or URL
rewriting.
</p>

</s3>

<s3 title="Cookies">

<p>
Resin attempts to track the session of a user by sending the
user's browser a cookie. This cookie contains a long string that
Resin creates that becomes the id of the session.
</p>

</s3>

<s3 title="URL rewriting">

<p>
Sometimes Resin cannot establish a cookie, either because the
user has disabled cookies in their browser or because the browser does
not support them (as is the case with some HDML and WML browsers). If the
cookie cannot be established then something called <var>URL rewriting</var> is
used. 
</p>

<p>
with URL rewriting, Resin rewrites every URL that it submits to the user so
that it contains a portion ';jsessionid=<var>id</var>;'. Then for each incoming
request the first thing it does is look for this parameter, and if it is
available it knows a session has been established and it removes the jsessionid
and uses it to find the users session object.
</p>

<p>
URL rewriting requires some assistance from the developer, which is
discussed later.
</p>

</s3>

</s2> <!-- session -->


</s1> <!-- lifecycle -->


<s1 name="obtain" title="Obtaining the ServletContext, Session, Request, and Response objects">

<s2 name="obtain-servlet" title="Servlet">

<p>
The Servlet implementation class usually obtains the ServletContext in the
<code>init()</code> method. The request and response object are passed in the
<code>doXXXX()</code> method.  The request object is used to obtain the
<a href="#session">Session</a>.
</p>

</s2>

<s2 name="obtain-jsp" title="JSP">

<p>
When translation of a JSP to a Servlet occurs, there are some variables that
are automatically defined. These variables can be used within any Java code
that is inserted in the page.
</p>

<deftable title="Implicit Variables in JSP">
<tr><th>Variable</th><th>Class</th><th>Description</th></tr><tr><td>response</td><td><a href="javadoc|javax.servlet.HttpServletResponse"/></td><td>
Assists in sending a response to the client. Includes the ability to
set the HTTP response headers.

</td></tr><tr><td>request</td><td><a href="javadoc|javax.servlet.HttpServletRequest"/></td><td>
Provides client request information including parameter name and
values from forms and the HTTP headers that the client sends.

</td></tr><tr><td>session</td><td><a href="javadoc|javax.servlet.HttpSession"/></td><td>
Provides a way to identify a user across more than one request 
and allows the developer to store information about that user (but see below).

</td></tr><tr><td>application</td><td><a href="javadoc|javax.servlet.ServletContext"/></td><td>
Every Web Application gets a ServletContext when it is started. It
contains information and attributes that apply to the whole
application.

</td></tr><tr><td>config</td><td><a href="javadoc|javax.servlet.ServletConfig"/></td><td>
The ServletConfig for this JSP page

</td></tr><tr><td>pageContext</td><td><a href="javadoc|javax.servlet.jsp.PageContext"/></td><td>
A variable specific to JSP (not available to servlets). It contains a
number of convenience functions for use in a JSP page.

</td></tr><tr><td>out</td><td><a href="javadoc|javax.servlet.jsp.JspWriter"/></td><td>
An Object that is used to write into the output stream

</td></tr></deftable>

<s3 title="Obtaining the session in JSP">

<p>With JSP, the <code>page</code> directive is used to indicate that the JSP needs
the session object.  When the page is executed, and has indicated that the
session is needed, a session will be created for the user if it has not already
and the <var>session</var> variable will be made available.</p>

<example>
&lt;%@page session="true"&gt;
</example>

<p>
The default for <code>session</code> is <var>true</var>, which is
convenient for pages that need the session, but creates an undue burden on the
server if the page does not need the session.  Therefore it is best to mark all
JSP pages with <code>session="false"</code> unless they really do need the
session.
</p>

<example>
&lt;%@page session="false"&gt;
</example>

</s3>


</s2> <!-- obtain-jsp -->

</s1> <!-- obtain -->


<s1 name="attributes" title="Attributes">

<p>
Each of the objects <code>application</code>, <code>session</code>, and
<code>request</code> can have <var>attributes</var>. These attributes consist
of a <var>name</var> and a <var>value</var>.
</p>

<p>
Using attributes the developer can store a value for later retrieval.
</p>

<p>
The <var>name</var> is a String that uniquely identifies the attribute, and the
<var>value</var> is a Java object.
</p>

<s2 title="The API for setting and getting attributes">

<p>
The following methods are available for the <code>application</code>,
<code>session</code>, and <code>request</code> objects.
</p>

<deftable title="API for attributes">
<tr><th>Method</th><th>Description</th></tr><tr><td>getAttribute(String name)</td><td>
Return the <code>Object</code> that is associated with the passed
<var>name</var>.  Usually you will need to cast the Object to whatever
class you know it to be.  If there is no attribute with the given name,
<code>null</code> is returned.

</td></tr><tr><td>setAttribute(String name, Object value)</td><td>
Associates the given <var>name</var> with the <var>value</var>. If an
attribute <code>name</code> already exists, it is replaced.

</td></tr><tr><td>removeAttribute(String name)</td><td>
Removes the attribute with the given <var>name</var> if it exists.
</td></tr></deftable>

</s2>

<s2 title="Choosing where to put attributes">

<p>
As a developer you have a choice of which object to store attributes
in. The object that you choose should be appropriate to the scope
within which you will need to get that value out again.
</p>

<p>
Whenever possible put the attribute in the request object. If that
cannot work, put it in the session object. And very rarely, put values
in the application object.  
</p>

<p>
The reason for this order is simple, all of the attributes in a
session cannot be garbage collected until they are explicitly removed
or the session expires. All of the objects in the application stay
until they are explicitly removed or the web application is stopped or
restarted.
</p>

</s2>

</s1> <!-- attributes -->

<s1 name="use-response" title="Using the Response object">

<s2 title="Encoding the URL">

<p>
Probably the most important and most frequent usage of the response
object is to rewrite the URL. Recall from earlier that in order to
maintain the identity of a Session with the user Resin may
have to add a special parameter to every URL. The developer must
co-operate with this, using the <a href="javadoc|javax.servlet.http.HttpServletResponse|encodeURL(String)">response.encodeURL</a> method.
</p>

<p>
Because of this, it is a good idea to form a String for every URL you
will use in a page and store it in a variable:
</p>

<example title="EncodingUrls.jsp - Encoding the URL's and storing them in a String variable">
&lt;%
    String boatUrl = response.encodeURL("water/boat.jsp");
    String goatUrl = response.encodeURL("animals/goat.jsp");
%&gt;

&lt;%-- the presentation --%&gt;

Hello, would you like some green eggs and ham?
Would you, could you, on a 
&lt;a href='&lt;%= boatUrl %&gt;'&gt;boat&lt;/a&gt;?
Would you, could you, with a
&lt;a href='&lt;%= goatUrl %&gt;'&gt;goat&lt;/a&gt;?

</example>

<p>
This has the added benefit of placing all of your URL's in
one place, allowing you to change them more easily.
</p>

</s2>

<s2 name="redirect" title="Redirecting the users browser">

<p>
Sometimes it is desirable to send a redirect to the client. This is a
response to the client that tells it to go to some other URL. This is
often used by developers so that the URL in the browser makes sense to
the user. It is however, a slow procedure because it requires a
response to go all the way back to the browser, and then the browser
will make a new request.
</p>

<p>
The redirect is accomplished by using the <code>response.sendRedirect()</code>
method. Again, the URL must be encoded, and a special kind of encoding
is needed for a redirect:
</p>

<example title="Redirect.jsp - an example of redirecting the client">
&lt;% 
   String redirectUrl = 
     response.encodeRedirectURL("elsewhere.jsp");

   response.sendRedirect(redirectUrl);
%&gt;
</example>

<s3 title="A note on redirecting wireless devices">

<p>
Redirects often do not work with wireless devices like cell phones and WML
clients, and the emulators of these devices. As well, the latency of a wireless
connection compounds the speed problem of using redirects.  Redirects should
probably be avoided with wireless devices.
</p>

</s3>
</s2> <!-- redirect -->


<s2 title="Setting the content type dynamically">

<p>
As mentioned eariler, the <code>&lt;%@ page contentType="..." %&gt;</code>
directive can be used to tell the browser the type of content that it is
getting.
</p>

<p>
The page directive method does not allow you to do this
dynamically. You can instead use: <code>response.setContentType("...")</code>
to set the content type.
</p>

</s2>

<s2 title="Telling the browser not to cache the page">

<p>
Often it is necessary to inform the browser that a page should not be
cached - the browser should ask for a new copy of the page every
time. The best way to do this is by setting appropriate HTTP headers
in the response to the browser.
</p>

<p>
Unfortunately, all the browsers work differently.  The following seems
to be a consensus on the headers to set:
</p>

<example title="nocache.jsp - Stop the browser from caching the page">
&lt;%
/** stop browser from caching */
response.setHeader("Cache-Control","no-cache,post-check=0,pre-check=0,no-cache");
response.setHeader("Pragma","no-cache");
response.setHeader("Expires","Thu,01Dec199416:00:00GMT");
%&gt;
</example>

</s2>

<s2 title="Telling the browser that the page is private">

<p>
A little known fact is that it is necessary to inform the browser with
certain pages that they are private pages, meaning they should never
be seen by anyone except the current user.
</p>

<p>
This applies to any pages that the user has needed a password to get to.
</p>

<example title="private.jsp - Telling the browser the page is private">
&lt;%
/**
 * Add an HTTP header to the response that 
 * indicates to the browser and any
 * intervening cache's that this is a private 
 * page, and should never be seen
 * by a different user.
 */
response.addHeader("Cache-Control","private");
%&gt;
</example>

</s2>

</s1> <!-- use-response -->

<s1 name="use-request" title="Using the Request object">

<s2 title="Retrieving the values set in form fields">

<p>
The main use of the request object is to get the values that a user
has supplied in a form submit. For example, with this HTML on
page a.jsp:
</p>

<example title="a.jsp - a form that submits a value">
&lt;% 
    String bUrl = response.encodeUrl("b.jsp");
%&gt;

&lt;%-- presentation --%&gt;

&lt;form method="post" action="&lt;%= bUrl %&gt;"&gt;
What is your favourite kind of eggs?
&lt;input type="text" name="favegss" size="25"&gt;
&lt;br&gt;
&lt;input type="submit" value="Submit"&gt;
&lt;input type="reset" value="Reset"&gt;
&lt;/form&gt;
</example>

<p>
The value that was supplied in ``eggs'' can be retrieved with:
</p>

<example title="b.jsp - retrieving a value from a form submit">

&lt;% 
    String aUrl = response.encodeUrl("a.jsp");
%&gt;

&lt;% 
    String faveggs = request.getParameter("eggs"); 
    if ((faveggs != null) &amp;&amp; (faveggs.trim().length() == 0))
        faveggs = null;
%&gt;

&lt;%-- presentation --%&gt;

&lt;% if (faveggs == null) { %&gt;
No eggs supplied!
&lt;a href="&lt;%= aUrl %&gt;"&gt;Try again&lt;/a&gt;
&lt;% } else if (faveggs.equals("green"))  { %&gt;
Of course we have &lt;%= faveggs %&gt; eggs! 
It's one of our favourites too.
&lt;% } else { %&gt;
We do not have &lt;%= faveggs %&gt; eggs.
&lt;% } %&gt;
</example>

</s2>

</s1> <!-- use-request -->

<s1 name="use-session" title="Using the Session object">

<p>
The Session object is used primarily to store two types of
information. The first is information about the user, and the second
is data that is built up and used over multiple pages.  A classic
example of information you would store in a session is user profile
information, or a shopping cart that is filled up over many pages.
</p>

<p>
It is important to try to limit the amount of information that is
stored in the session object.
</p>

<s2 title="Explicitly causing the session to end">

<p>
The session object will go away if the user is inactive for a certain
time (usually 1/2 hour). You can also explicitly destroy the session,
which you may want to do for example if the user chooses to logout.
</p>

<p>
This is accomplished with: <code>session.invalidate();</code>
</p>

</s2>

<s2 title="Doing something when the Session goes away">

<p>
It is possible to add a hook so that something can be done when
Resin decides that a Session has expired, or the Session is
explicitly destroyed.
</p>

<p>
To accomplish this, you write a class that implements the
<a href="javadoc|javax.servlet.http.HttpSessionBindingListener"/> interface.
Then you register this class with the session simply by putting it as one of
the attributes. The Session will notify all of it's attributes that implement 
<a href="javadoc|javax.servlet.http.HttpSessionBindingListener"/>.
</p>

<example title="SessionBind.jsp - An example of getting notification when a Session is destroyed">
&lt;%@page import="example.SessionListener" %&gt;

&lt;%
    // example.SessionListener implements HttpSessionBindingListener 
    SessionListener d = new SessionListener();
    session.setAttribute("sessiongoesbyebye", d);
%&gt;
</example>

</s2>

<s2 title="Warning! One session does not mean one browser window!">

<p>
It is important to realize that the user can have multiple
windows open that use the same session. If the user uses the "Open in
new Window" functionality of a browser, they will have two windows
open and the Web Application will see them both as belonging to the
same session. This has some ramifications on how the Session can be
used for shopping-cart like applications.
</p>

<p>
For example, let's assume that an application uses the Session
attribute "cart" to store shopping cart information about different
types of juice a user has chosen to purchase. 
</p>

<p>
The user may start one juice buying transaction and get to the
confirmation page, having 3 grape and 2 apple in their
cart. Now, what happens if at this point they use another browser
window to initiate another purchase? If the Web Application is using
the Session to store shopping cart information then the second window
may destroy the contents of the shopping cart, so that if the user
finishes the first window they end up buying nothing!
</p>

<p>
A possible solution for this is to keep a <var>version counter</var> in your
cart.  Every time the cart is changed, the version counter is updated.
Then, when your application shows the "confirm purchase" page (the next action
will cause the purchase to occur), it sends the version counter to the "confirm
purchase page".  The "confirm purchase" page submits that version counter as a
parameter.  The application can check the submitted version counter, and the
current version counter in the shopping cart - if they are different then the
cart has been modified in some other way, and a message is returned that the
purchase did not occur because the cart had been modified elsewhere.
</p>

</s2>
</s1> <!-- use-session -->


<s1 name="errors" title="Error Handling">

<s2 title="JSP Translation Time Processing Errors">

<p>
Some errors may occur at JSP translation time.  This could be, for
example, from an error in the syntax of some Java code in your JSP.
You will usually see this error in your browser the first time you try
to access the page.  Resin can also put the error in log files.
</p>

<p>
From the JSP specification:
</p>

<blockquote>
The translation of a JSP page source into a corresponding JSP page
implementation class using the Java technology by a JSP container can
occur at any time between initial deployment of the JSP page into the
runtime environment of a JSP container, and the receipt and processing
of a client request for the target JSP page. If translation occurs
prior to the JSP container receiving a client request for the target
(untranslated) JSP page then error processing and notification is
implementation dependent. Fatal translation failures shall result in
subsequent client requests for the translation target to also be
failed with the appropriate error; for HTTP protocols, error status
code 500 (Server Error).
</blockquote>

</s2>

<s2 title="Coompilation Time Processing Errors">

<p>
Some errors may occur at the time a Servlet or other source file is being
compiled by Resin. This could be, for example, from an error in the syntax of
the Java code.
You will usually see this error in your browser the first time you try
to access the page.  Resin might also put the error in log files.
</p>

</s2>

<s2 title="Client Request Time Processing Errors">

<p>
Java handles runtime errors with exceptions.  If an exception is not
caught in your JSP or Servlet, Resin will use a special error page
to send results back to the browser.  Resin uses a default error
page unless you explicitly provide an error page yourself.
</p>

<p>
From the JSP specification:
</p>

<blockquote>

<p>
During the processing of client requests, arbitrary runtime errors can
occur in either the body of the JSP page implementation class or in
some other code (Java or other implementation programming language)
called from the body of the JSP page implementation class. Such errors
are realized in the page implementation using the Java programming
language exception mechanism to signal their occurrence to caller(s)
of the offending behavior 1 .  These exceptions may be caught and
handled (as appropriate) in the body of the JSP page implementation
class.
</p>

<p>
However, any uncaught exceptions thrown from the body of the JSP page
implementation class result in the forwarding of the client request
and uncaught exception to the errorPage URL specified by the offending
JSP page (or the implementation default behavior, if none is
specified).
</p>

<p>
The offending java.lang.Throwable describing the error that occurred
is stored in the javax.ServletRequest instance for the client request
using the putAttribute() method, using the name
javax.servlet.jsp.jspException. Names starting with the prefixes java
and javax are reserved by the different specifications of the Java
platform; the javax.servlet prefix is used by the Servlet and JSP
specifications.  If the errorPage attribute of a page directive names
a URL that refers to another JSP, and that JSP indicates that it is an
error page (by setting the page directive's isErrorPage attribute to
true) then the exception implicit scripting language variable of that
page is initialized to the offending Throwable reference.
</p>

</blockquote>

</s2>
</s1> <!-- errors -->


<s1 name="architecture" title="Architecture">

<p>
There are many ways to use the capabilities that are offered by
JSP --  different models apply to different applications.
</p>

<s2 title="Simple JSP">

<p>
The simplest model is to use JSP as an add-on to existing web
pages. At the top of each page is the Java code that is necessary for
the display of the page, and at the bottom is the markup that is to be
output, with appropriate insertion of any dynamically generated
variables.
</p>

<p>
Note the seperation of the different logical parts. It is a very good
idea to keep the presentation section as Java-less as possible. Setup
all of the values in the logic part, and then use only simple
<code>&lt;%= var %&gt;</code> and <code>if</code> statements in the
presentation part.
</p>

<example title="SimpleJSP.jsp - the logic and display code in one page">
&lt;%-- urls --%&gt;

&lt;%
  // store your target urls in String variables
%&gt;

&lt;%-- incoming parameters --%&gt;
&lt;%
  // store form values from the request object in variables
%&gt;

&lt;%-- logic --%&gt;
&lt;%
  // we all make decisions with logic, right?
%&gt;

&lt;%-- presentation --%&gt;

&lt;markup&gt;
  &lt;forthebrowser&gt;
  &lt;/forthebrowser&gt;
&lt;/markup&gt;
</example>

<p>
This seems like a sensible approach. However, imagine that later it is
decided that a different set of HTML is needed for the output if there
is no news available. As well, support of WML output is required. Now
we need to put the display code for 4 different types of output into
one page.  Maybe we need to go to different places as well, for
example an administrator might get a different display page, or we
need to check the users profile to see what is apporiate to display.
This is too much complication to put all in one place.
</p>

<p>
This type of implementation, because of it's limitiations and it's
inability to change without exponentially increasing the complexity,
should be avoided.
</p>

</s2>

<s2 title="Seperating the logic into another JSP">

<p>
To address some of the disadvantages of the Simple JSP method, it is
possible to seperate the `logic' and the `presentation' into two
different JSP files.
</p>

<p>
In this model, instead of a link pointing directly to the page that
does the display, it points to a page that handles the incoming
request.  This 'logic' page contains the Java code that is responsible
for preparing the values that will be used for displaying. It stores
these prepared values as attributes of the <code>request</code> object,
and then <var>forwards</var> to the appropriate display page. The display
page then pulls the information it needs out of the request object and
displays it.
</p>

<example title="SeperateJsp.jsp - The logic JSP that prepares the data for display">

&lt;% 
/** -- incoming parameters -- */
     String strJuiceType = request.getParameter("juiceType");
     String strQuantity = request.getParameter("juiceQuantity");

/** -- logic -- */
Double cost;
String strCost;

here we might do a check to make sure mandatory fields
have values.

Here we might do a database lookup to determine the price, and
set the cost value to the price * quanitity

Now we might format the cost double into 
a two-decimal number and store it in strCost

/** -- set outgoing parameters
    -- forward to display page -- */

/** note that here we put juiceType in as a request
    attribute, even though the display page could get
    it from the request parameters. This helps us keep
    the interface between the logic and the presentation
    cleaner */

request.setAttribute("cost", strCost);
request.setAttribute("juiceType", strJuiceType);
request.setAttribute("quantity", strQuantity);

if (isWML)
    pageContext.forward("SeperateJspPresentationWML.jsp");
else
    pageContext.forward("SeperateJspPresentationHTML.jsp");
%&gt;
</example>

<example title="SeperateJspPresentationHTML.jsp - The JSP that presents the prepared information in HTML format">
&lt;%-- urls --%&gt;

&lt;%-- prepared objects --%&gt;

&lt;%
String cost = (String) request.getAttribute("cost");
String juiceType = (String) request.getAttribute("juiceType");
String quantity = (String) request.getAttribute("quantity");
%&gt;

&lt;%-- presentation --%&gt;

Hey, if you want &lt;%= quantity %&gt; bottles of 
&lt;%= juiceType =&gt; juice, it is going to cost
you $&lt;%= cost %&gt;
</example>

<p>
Here we have introduced a new thing: <code>pageContext.forward</code>.
</p>

</s2>

<s2 title="pageContext.forward">

<p>
The <code>pageContext.forward(String url)</code> forwards the processing to a
different JSP page.  That is, it passes control over to another
page. This page is then executed, inheriting the current request and
response objects. It is important that this is the last thing
that a JSP page does.
</p>

</s2>

<s2 title="Seperating the business logic into beans">

<p>
Even the seperation of all logic into a different JSP can get a bit muddled.
You can seperate the `logic' into two types of logic, business logic
and presentation logic.  
</p>

<p>
Presentation logic is logic that is part of the presentation.
Examples are form validation and formatting of numbers into strings.
</p>

<p>
Business logic is programming that involves your data.  If you can
separate something in your mind from the presentation, it doesn't
depend on the presentation in any way, that's business logic.
Examples are database lookups and shopping cart manipulation.
</p>

<p>
Your application will be cleaner and easier to manage if you put your
business logic in Java classes (beans) which hide the
complexities. You then use these classes in the logic.jsp.
</p>

</s2>

<s2 title="Model 2 (preferred)">

<p>
The final approach discussed here is called the `Model 2' approach. This
approach requires a level of sophistication that is usually not
warranted unless you use a library that supports it, however it is the
cleanest way to implement an application.
</p>

<p>
In this approach there is a special Servlet called a controller
servlet. The controller maps an incoming request to a Java class that
takes care of all of the 'business logic'. This Java class returns a result
that indicates to the controller where it should go next. The controller then
dispatches to the appropriate place.  
</p>

<p>
The flow of a request moves through these `business logic' pieces, finally
ending up at a `view'.  The logic pieces are responsible for examing the
submitted information (such as parameters from forms), managing logical flow,
and preparing objects for the <var>view</var>.  The objects for the view are stored
as attributes of the request (or sometimes, the session).
</p>

<p>
The view is responsible for preparing a response for the user using the
prepared objects now available as request or session objects.  This is where
JSP is often used, it works very well as the view component of a Model 2
architecture.
</p>

<p>
The developer tells the controller what the flow for each request is
by specifying it an external (usually XML) file.
</p>

<p>
This approach is by far the cleanest approach to using Servlets and JSP.  Most
applications of any significant complexity use a Model 2 architecture.  
</p>

</s2>
</s1> <!-- architecture -->



<s1 name="security" title="Security">

<p>
JSP inherits the Servlet security mechanism. Using the two fundamental
concepts of <var>Principals</var> and <var>Roles</var>, JSP provides
declarative and programmatic security.
</p>

<p>
In addition, there is builtin support for various HTTP methods of
login that establish a Principal and it's Roles based on a user login
and password.
</p>

<s2 title="Principals">

<p>
A Principal is established in association with a Session. There is a
one to one correspondence between the two. Usually the Principal is a
user, a real live honest to goodness person sitting at a computer
somewhere and accessing the Web Application.
</p>

<p>
The Application may require that the User go through a login process,
a successful login will establish a Principal, which will have a
certain set of Roles.
</p>

</s2>

<s2 title="Roles">

<p>
Servlet 2.2 Specification states:
</p>

<blockquote>
A role is an abstract logical grouping of users that is defined by the
Application Developer or Assembler.  When the application is deployed,
these roles are mapped by a Deployer to security identities, such as
principals or groups, in the runtime environment.
</blockquote>

<p>
Roles are similar to groups in Unix security.  As an example, you
might have a "member" role for users who have a membership, and an
"admin" role for administrators.  
</p>

<p>
Principals can have more than one role -- a user might be both a
"member" and an "admin".
</p>

</s2>

<s2 title="Declarative Security">

<p>
Servlet 2.2 Specification states:
</p>

<blockquote>
Declarative security refers to the means of expressing an
application's security structure, including roles, access control, and
authentication requirements in a form external to the application. The
deployment descriptor is the primary vehicle for declarative security
in web applications.
</blockquote>

<p>
Basically what this means in real terms is that you can specify
certain paths in web.xml that require certain roles. For example, you
can say that to access any page in the "/accountsetup/" subdirectory,
the user must have a role of "admin".
</p>

</s2>

<s2 title="Programmatic Security">

<p>
Servlet 2.2 Specification states:
</p>

<blockquote>
Programmatic security is used by security aware applications when
declarative security alone is not sufficient to express the security
model of the application. 
</blockquote>

<p>
Programmatic security lets you decide in some Java code what to do,
based on the role that a user has.  For example, you might make a
certain button appear in the button bar only for an "admin" user.
</p>

<deftable title="Programmatic Security API">
<tr><th>Method</th><th>Description</th></tr><tr><td><a href="javadoc|javax.servlet.http.HttpServletRequest|getRemoteUser()">request.getRemoteUser()</a>
return the name of an authenticated user.

</td></tr><tr><td><a href="javadoc|javax.servlet.http.HttpServletRequest|isUserInRole(String)">request.isUserInRole(String role)</a>
</td><td>return true if the current user is in a given security role.

</td></tr><tr><td><a href="javadoc|javax.servlet.http.HttpServletRequest|getUserPrincipal()">request.getUserPrincipal()</a>
</td><td>return the <a href="javadoc|java.security.Principal|"/> associated with the
current user.
</td></tr></deftable>

</s2>

<s2 title="When does Resin require a login?">

<p>
The resources in an Application are by default open to the public, and
do not require a login. As soon as the User attempts to access a
resource that has been declared to require a role in the web.xml,
Resin will insert in the process a login of some kind before
continuing on to the resource that was originally requested.
</p>

<p>
For example, if the "/members/*" area has been declared to require a
"member" role, as soon as the user tries to access anything in
"/members/" Resin will check to see if the user has logged in
yet. If the user has logged in, then the roles for the user are
checked to see if "member" is a role that user can take.  If the user
has not logged in, Resin inserts a login procedure and then
checks the roles.
</p>

</s2>

<s2 title="The login procedure">

<p>
The Servlet Specification details numerous methods for getting user
identification and password information from the user.
</p>

<p>
The example below shows usage of "Form Based Authentication", which
allows you to specify a login page to be sent to the user when needed,
and an error page that will be displayed if the user login fails.
</p>

<p>
The login page should submit a form to the url
<code>j_security_check</code> with the parameters 
<code>j_username</code> and 
<code>j_password</code> set to appropriate values.
</p>

<p>
Resin recognizes the special url <code>j_security_check</code> and
authenticates the username and password.
</p>

</s2>

<s2 title="Lifecycle of a Principal">

<p>
The Servlet authentication associates a <var>principal</var> with a <a href="#session">session</a>.  The principal will only last as long as the
Session; as soon as the Session is gone then the user will no longer be logged
in.
</p>

<p>As a result, invalidation of the Session will also cause a logout:</p>

<example>
session.invalidate();
</example>

<p>You can also cause a logout without invalidating the whole Session. Other
objects in the session will remain available but the principal will be
null:</p>

<example>
session.logout();
</example>

</s2>


<s2 title="Authenticating the User">

<p>
Once the user information is collected, the password must be verified
and the roles determined. Unfortunately, the Servlet specification
does not indicate a standard way for this to occur.
</p>

<p>
What that means is that every Container is likely to do this
differently, and you will have to refer to Container specific
documentation and examples.
</p>

</s2>

<s2 title="Example usage of Security">

<p>
The Resin documentation on <a href="security.xtp">Security</a> includes a
comprehensive discussion, and the <a href="../examples/security-basic/index.xtp">Basic
Security Tutorial</a> is a good starting point as well.
</p>

</s2>
</s1> <!-- security -->


</body>
</document>
