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

<objsummary/>

<section name='jsp' title='JSP Directives'>

<defun name=language title='&lt;%@ page language="lang" %&gt;'
       index=language>
<sum>Sets the JSP script language to <var/lang/>. Defaults to Java.</sum>
All JSP 1.0 implementations must support Java.  Some implementations,
like <resintm/>, may support other scripting languages, e.g. JavaScript.
</defun>

<defun name=import title='&lt;%@ page import="package" %&gt;' index=import>
<sum>Adds to the Java package import list for the generated Java file.</sum>
<note>Only relevant when using Java.</note>
</defun>

<defun name=errorPage title='&lt;%@ page errorPage="path" %&gt;'
       index=errorPage>
<sum>Defines a page to display if an error occurs in the JSP page.</sum>

<p/>Robust applications can return informative error pages when
something goes wrong in a file, for example if a database is overloaded.
<var/path/> is returned as the response file.  The error page
can use the additional implicit variable <a
href='#exception'>exception</a> containing the thrown exception.

<p><var/path/> is relative to the current page.  Its root is relative
to the application root.

<p>The error page itself can be a JSP page.  If the error page is a
JSP page, it can use the implicit variable <code/exception/> to get
information about the thrown exception.
</defun>

<defun name=isErrorPage title='&lt;%@ page isErrorPage="true" %&gt;' 
       index='error page'>
<sum>Gives an error page access to the <code/exception/> implicit variable.
Default to false.</sum>

<example title='errorpage.jsp'>
&lt%@ page isErrorPage="true" %&gt;
&lt;h1&gt;Received error &lt;%= exception.message %&gt;&lt;/h1&gt;
</example>
</defun>

<defun name=include title='&lt;%@ include file="path" %&gt;'
       index='include, at translation'>
<sum>Includes the raw file <var/path/> at translation time.</sum>

<p>The include directive is a replacement for an SSI include (or the C
'#include').  It includes the contents of the file at <var/path/> into
the JSP file.  The included file is parsed as JSP, so it can have
active elements like expressions, declarations and scriptlets.

<p><var/path/> is relative to the current page, and its root is the
application root.

<example title='header.jsp'>
&lt;html&gt;&lt;head&gt;
&lt;title&gt;&lt%= title %&gt;&lt;/title&gt;
&lt;/head&gt;
&lt;body color=white&gt;
</example>

<example title='page.jsp'>
&lt;% var title = "Hello, World"; %&gt;
&lt;%@ include file='header.jsp' %&gt;

&lt;h1&gt;&lt;%= title %&gt;&lt;/h1&gt;
</example>
</defun>

<defun name=buffer index='page buffer' 
       title='&lt;%@ page buffer=sizekb %&gt;'>
<sum>Gives the <var/size/> of the page buffer in kb or <var/none/> for
no buffer. Default 8kb.</sum>  If <code/buffer/> is <var/none/>, all
output is immediately flushed. 

<p>JSP 1.0 gives page writers flexibility by buffering its output
before sending the response to HTTP.  The buffering allows <a
href='#errorpage'>error recovery</a> and forwarding, even after
generating some content.  Once the buffer has filled, it will be
flushed.  So applications must still detect their errors early.

<p>The following example generates an XML document (for variety).  If
the form's query is missing the 'name' parameter, it will redirect the
results.

<example>
&lt;?xml version='1.0'?&gt;
&lt;form&gt;
&lt;%
  if (request.form["name"] == null)
    pageContext.forward("redo-form.jsp");

  for (var name in request.form) {
    out.print("&lt;" + name + "&gt;");
    out.print(request.form[name]);
    out.println("&lt;/" + name + "&gt;");
  }
%&gt;
&lt;/form&gt;
</example>
</defun>

<defun name=autoFlush index='page buffer' 
       title='&lt;%@ page autoFlush="true" %&gt;'>
<sum>Tells JSP to flush the page buffer when it fills.
Default is true.</sum>

<p>If autoFlush is false, the JSP engine will throw an exception if
the buffer overflows.
</defun>

<defun name=pagesession index='session' 
       title='&lt;%@ page session="true" %&gt;'>
<sum>Tells JSP that the page participates in a session. Defaults to true.</sum>

<p>The session declaration makes the session implicit variable
available to a JSP page.

<p>If the page doesn't use sessions, it should set <code/session/> to false.

<example>
&lt;%@ page session="true" %&gt;
&lt;% 
  session.value.count++;
%&gt;
&lt;h1&gt;Welcome, visitor &lt;%= count %&gt;&lt;/h1;&gt;
</example>
</defun>

<defun name=isThreadSafe index='synchronization'
       title='&lt;%@ page isThreadSafe="true" %&gt;'>
<sum>Tells the JSP that multiple pages can execute in parallel.
Defaults to true.</sum>

<p>JSP pages are always responsible for synchronization of shared
variables, such as the <code/session/> and <code/application/>
variables.  In some rare cases, a page may use servlet variables
(created with a declaration), and be too lazy to handle the
synchronization.

<p>Even with <code/isThreadSafe=false/>, the JSP engine may create
multiple instances of the JSP servlet. So the page author can never
absolve herself of synchronization issues.

<p>In the following example, a JSP engine might create 3 servlet
instances of the page.  So three calls to the same page may return
counts of 17, 3 and 398.  In addition, the JSP engine is free to
destroy and recreate the servlet at any time, essentially resetting
the counter to 0.

<example>
&lt;%@ page isThreadSafe="false" %&gt;
&lt;%! var count = 0; %&gt;
&lt;h1&gt;Welcome, visitor &lt;%= count++ %&gt;
</example>

</defun>

<defun name=info title='&lt;%@ page info="description" %&gt;'>
<sum>Gives a brief description for the page.</sum>
</defun>

<defun name=contentType title='&lt;%@ page contentType="description" %&gt;'>
<sum>Sets the content type and character encoding of the page.</sum>
<p/><code/contentType/> can also set the character encoding, for
example to utf-8. 
<example>
&lt;%@ page contentType="text/plain; charset=utf-8" %&gt;
&lt;%! var count = 0; %&gt;
&lt;h1&gt;Welcome, visitor &lt;%= count++ %&gt;
</example>
</defun>

<defun name=extends title='&lt;%@ page extends="Java class" %&gt;'>
<sum>Changes the generated servlet's class.</sum>

<p>You should not use this directive unless you know exactly what
you're doing.
</defun>

<defun name=taglib title='&lt;%@ taglib prefix="x" uri="foo" %&gt;'>
<sum>Configures tags with prefix <var/x/> to use the tag
library <var/foo/>.</sum>

<example>
&lt;%@ taglib prefix='x' uri='http://www.caucho.com/mytag/test' %>
&lt;x:mytag/>
</example>

</defun>
</section>
