<document>
  <header>
    <product>resin</product>
    <title>Directives</title>
    <description>
      <p>
      JSP Directives control the processing of an entire
      page.  Directive examples include setting a scripting language,
      setting an error page, including other sections, and setting a
      character encoding.
      </p>
    </description>
  </header>

  <body>
    <summary/>

    <s1 name="jsp" title="JSP Directives">

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

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

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

        <p>Robust applications can return informative error pages when
        something goes wrong in a file, for example if a database is overloaded.
        <var>path</var> 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>

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

        <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</code> to get
        information about the thrown exception.</p>
      </s2>

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

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

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

        <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</var> into
        the JSP file.  The included file is parsed as JSP, so it can have
        active elements like expressions, declarations and scriptlets.</p>

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

        <example title="header.jsp">
          &lt;html&gt;&lt;head&gt;
          &lt;title&gt;&amp;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>
      </s2>

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

        <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>

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

        <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>
      </s2>

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

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

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

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

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

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

      <s2 name="isThreadSafe" index="synchronization" title="&lt;%@ page isThreadSafe=&quot;true&quot; %&gt;" type="defun">
        <p>Tells the JSP that multiple pages can execute in parallel.
          Defaults to true.</p>
        
        <p>JSP pages are always responsible for synchronization of shared
          variables, such as the <code>session</code> and <code>application</code>
              variables.  In some rare cases, a page may use servlet variables
              (created with a declaration), and be too lazy to handle the
              synchronization.</p>
        
        <p>Even with <code>isThreadSafe=false</code>, the JSP engine may create
            multiple instances of the JSP servlet. So the page author can never
            absolve herself of synchronization issues.</p>
        
        <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.</p>
        
        <example>
          &lt;%@ page isThreadSafe="false" %&gt;
          &lt;%! var count = 0; %&gt;
          &lt;h1&gt;Welcome, visitor &lt;%= count++ %&gt;
        </example>
        
      </s2>
      
      <s2 name="info" title="&lt;%@ page info=&quot;description&quot; %&gt;" type="defun">
        <p>Gives a brief description for the page.</p>
      </s2>
      
      <s2 name="contentType" title="&lt;%@ page contentType=&quot;description&quot; %&gt;" type="defun">
        <p>Sets the content type and character encoding of the page.</p>

        <p><code>contentType</code> can also set the character encoding, for
            example to utf-8. </p>
        <example>
          &lt;%@ page contentType="text/plain; charset=utf-8" %&gt;
          &lt;%! var count = 0; %&gt;
          &lt;h1&gt;Welcome, visitor &lt;%= count++ %&gt;
        </example>
      </s2>

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

        <p>In general, a filter is a better solution than using the
          extends directive.</p>
      </s2>

      <s2 name="taglib" title="&lt;%@ taglib prefix=&quot;x&quot; uri=&quot;foo&quot; %&gt;" type="defun">
        <p>Configures tags with prefix <var>x</var> to use the tag
            library <var>foo</var>.</p>
        
        <example>
          &lt;%@ taglib prefix='x' uri='http://www.caucho.com/mytag/test' %&gt;
          &lt;x:mytag/&gt;
        </example>

      </s2>
    </s1>
  </body>
</document>