webapp-overview.xtp

RESIN 3.2 最新源码

<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="[e-mail]" 
  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>