<document>
  <header>
    <product>resin</product>
    <resin-2.0>$resin/ref/jsp-directives.xtp</resin-2.0>
    <title>Directives</title>
    <description>
      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.
    </description>
  </header>

  <body>
    <summary/>

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

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

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

      <defun name=errorPage title='&lt;%@ page errorPage="path" %&gt;'
        index=errorPage>
        <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/> 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/> 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/> to get
        information about the thrown exception.</p>
      </defun>

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

        <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'>
        <p>Includes the raw file <var/path/> 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/> 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/> 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;&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;'>
        <p>Gives the <var/size/> of the page buffer in kb or <var/none/> for
        no buffer. Default 8kb.  If <code/buffer/> is <var/none/>, 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>
      </defun>

      <defun name=autoFlush index='page buffer' 
        title='&lt;%@ page autoFlush="true" %&gt;'>
        <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>
      </defun>

      <defun name=pagesession index='session' 
        title='&lt;%@ page session="true" %&gt;'>
        <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/> 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>
      </defun>

      <defun name=isThreadSafe index='synchronization'
             title='&lt;%@ page isThreadSafe="true" %&gt;'>
        <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/> 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>
        
        <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>
        
        <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>
        
      </defun>
      
      <defun name=info title='&lt;%@ page info="description" %&gt;'>
        <p>Gives a brief description for the page.</p>
      </defun>
      
      <defun name=contentType title='&lt;%@ page contentType="description" %&gt;'>
        <p>Sets the content type and character encoding of the page.</p>

        <p><code/contentType/> 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>
      </defun>

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

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

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

      </defun>
    </section>
  </body>
</document>
