</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 xless 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 variouspackages. Unless these packages are imported, the use of such a classmust 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 makefunctionality 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 JSPin 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 sendingyou 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 somewhatcomplicated to implement. They are probably best left to developers oflibraries -- the taglibs can provide some simple access to thefunctionality of the library.</p><p>More information on implementing custom tag libraries is in the <a href="doc|jsp|">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 HTTPrequests, responses, and header information. Filters do not generally create aresponse or respond to a request as servlets do, rather they modify or adaptthe 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 theresponse ("<a href="#requestresponse">request</a>" and "<a href="#responseresponse">response</a>" are discussed later).  A filter canintercept the request before it get's to other web components, such as a JSP orServlet, and change what the request looks like.  A filter can intercept theresponse that is generated by web components, such as a JSP or Servlet, andchange (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="doc|servlet|">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 tocreate custom Java classes that are used by the Servlets, JSP, Filters, andother 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 automaticallycompiled by Resin.</p></s2> <!-- classes --><s2 name="lib" title="Java code libraries"><p>A web application can take advantage of java code libraries.  Theselibraries 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 thenavailable to the Servlet, JSP, Filter, and other components of the webapplication.</p><p>Jar libraries usually contain code that is not specific to the webapplication, for example a library that provides a database driver, or alibrary 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 andconfigured 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 thisapplication</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 applicationreflects 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 iswhere you put any Java classes that are specifically foryour application.</p><p>There is also a <code>WEB-INF/lib</code> directory which can contain .jar filesfor libraries that are needed by the application.  These .jar files are usuallythird-party libraries or libraries that are reused amongst many different webapplications.</p><p>Finally, the file <code>WEB-INF/web.xml</code> is used toconfigure your web application.</p></s2><s2 title="web.xml"><p>A Web Application is configured with a deployment descriptor thatcollects 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 automaticcompilation of Java files that are changed.</p><p>You can take advantage of this by placing your java source files inthe <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 anychanges to <code>Util.java</code> will result in the automatic recompilation ofthe 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 correspondingjava objects that Resin creates. Each of these objects has aunique scope: they are created at a certain time and destroyed at acertain time.</p><p>The JavaServer Pages specification inherits from the Servletspecification the concepts of ServletContexts, Sessions,Requests and Responses.</p><p>These objects are created by Resin, they are always availableto 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. AServletContext is an object that is common to allServlets 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 Applicationis started, and it remains until the Web Application is closed.  Thereis one ServletContext made for each web application, and any usage ofthe 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 withinthe Web Application, Resin creates a Request object torepresent the current request.  Resin also creates a Response objectwhich the developer can use to set certain things that apply to theresponse 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 alink into the Web Application. These objects last until the responseis 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. Thefirst time a user accesses anything within the web application, Resin recognizes this unknown user and creates a new Session torepresent them. This Session object will remain the same for that userfor 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 requestfrom a user and checks to see if it has a Session for that user. If it doesnot, it creates one. This session object will remain the same for thatuser.</p><p>The end of the session object is a bit complicated. Since Resin cannot tell the difference between when the user has stoppedusing the application and when the user is just taking a long time todo something, Resin must guess.  Resin uses a time-outvalue to determine when it should assume that the user has goneaway, it defaults to 30 minutes. What this means is that if a user hasnot accessed any resource in the Web application for 30 minutes theResin will destroy the session object for that user.</p><p>A developer can also explicitly destroy the Session object, and thatis discussed later.</p><s3 title="How Resin keeps track of the Session"><p>Resin establishes a session by giving the user's browser aunique id that is returned back to Resin with each newrequest. This is accomplished in one of two ways: using cookies or URLrewriting.</p></s3><s3 title="Cookies"><p>Resin attempts to track the session of a user by sending theuser's browser a cookie. This cookie contains a long string thatResin creates that becomes the id of the session.</p></s3><s3 title="URL rewriting"><p>Sometimes Resin cannot establish a cookie, either because theuser has disabled cookies in their browser or because the browser doesnot support them (as is the case with some HDML and WML browsers). If thecookie cannot be established then something called <var>URL rewriting</var> isused. </p><p>with URL rewriting, Resin rewrites every URL that it submits to the user sothat it contains a portion ';jsessionid=<var>id</var>;'. Then for each incomingrequest the first thing it does is look for this parameter, and if it isavailable it knows a session has been established and it removes the jsessionidand uses it to find the users session object.</p><p>URL rewriting requires some assistance from the developer, which isdiscussed 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 thatare automatically defined. These variables can be used within any Java codethat 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 toset 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 andvalues 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. Itcontains information and attributes that apply to the wholeapplication.</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 anumber 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 needsthe session object.  When the page is executed, and has indicated that the