<document>
  <header>
    <product>resin</product>
    <title>Actions</title>
    <description type="brief">
      <p>
      Actions are the core of JSP.  Actions range from printing a
      script expression, to creating and storing a Java Bean.
      </p>
    </description>
  </header>

  <body>
<summary/>

<s1 name="lex" title="JSP Lexical">

<s2 name="jsp-escape" title="escapes" index="escapes" type="defun">
<p>The JSP actions can be escaped using <var>&lt;\%</var>.</p>

<example>
&lt;\% verbatim text %&gt;
</example>
<results>
&lt;% verbatim text %&gt;
</results>

</s2>

<s2 name="whitespace" title="whitespace" index="whitespace" version="Resin 1.2" type="defun">
<p>JSP whitespace is copied to the output directly, unless escaped.</p>

<p>In Resin 1.2, if you place a backslash immediately after a JSP action and
before a line end, Resin will omit the end of line.  In the following
example, Resin keeps the whitespace after the <var>&lt;%@page ... %&gt;</var> and
removes it after after the <var>&lt;%= 2 + 2 %&gt;</var>.</p>

<example>
&lt;% @page session="true" %&gt;
a
&lt;%= 2 + 2 %&gt;\
c
</example>
<results>

a
4c
</results>

</s2>

</s1>

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

<s2 name="directive" title="&lt;%@ name att1=&quot;v1&quot;... %&gt;" index="directive" type="defun">
<p>Sets a JSP <a href="jsp-directives.xtp">directive</a></p>

</s2>

<s2 name="expr" title="&lt;%= expression %&gt;" index="expression" type="defun">
<p>Prints the value of <var>expression</var> evaluated the page's
<a href="jsp-directives.xtp#language">language</a>.</p>

<p>The expression action is equivalent to the following:</p>
<def>
  out.print(<var>expression</var>);
</def>

<p>It also has the following XML equivalent</p>
<def>
&lt;jsp:expression&gt;
  <var>expression</var>
&lt;/jsp:expression&gt;
</def>

<p>The following simple example just prints the value of a form variable.
</p>

<example>
Name: &lt;%= request.getParameter("name") %&gt;
</example>
<results>
Name: George Washington
</results>
</s2>

<s2 name="scriptlet" title="&lt;% scriptlet %&gt;" index="scriptlets" type="defun">
<p>Executes the statements in <var>scriptlet</var> using the page's
<a href="jsp-directives.xtp#language">language</a>.</p>

<p>The <var>scriptlet</var> is any statement list in the language,
e.g. Java.  The scriptlet can use any of the <a href="jsp-variables.xtp">implicit variables</a>, such as the request
object and the out writer.</p>

<p>Scriptlets have the following XML equivalent</p>
<def>
&lt;jsp:scriptlet&gt;
  <var>scriptlet</var>
&lt;/jsp:scriptlet&gt;
</def>

<example>
&lt;h1&gt;Form results&lt;/h1&gt;

&lt;pre&gt;
&lt;%
  Enumeration e = request.getParameterNames();
  while (e.hasMoreElements()) {
    String key = e.nextElement();
    String value = request.getParameter(key);

    out.println(key + ": " + value);
  }
%&gt;
&lt;/pre&gt;
</example>
<results>
&lt;h1&gt;Form results&lt;/h1&gt;

&lt;pre&gt;
  Name: George Washington
  Rank: General
&lt;/pre&gt;
</results>
</s2>

<s2 name="decl" title="&lt;%! declaration %&gt;" index="declaration" type="defun">
<p>Adds <var>declaration</var> code to the Servlet class</p>

<p>JSP places the declaration code in the servlet class.  In contrast,
scriptlet and expression code are in a service method.  So
declarations can declare class variables and methods.</p>

<note>Declarations are primarily useful for Java, but are allowed in
JavaScript.</note>

<p>Declarations have the following XML equivalent</p>
<def>
&lt;jsp:declaration&gt;
  <var>declaration</var>
&lt;/jsp:declaration&gt;
</def>

<example>
&lt;%= foo() %&gt;

&lt;%!
  private int foo() { return 1329; }
%&gt;
</example>
</s2>

<s2 name="include" title="&lt;jsp:include page=&quot;path&quot;/&gt;" index="include, runtime" type="defun">
<p>Includes the contents of the local URL at <var>path</var> during
runtime.</p>

<p>jsp:include is a runtime action.  It will call the included
<var>path</var> just as if <var>path</var> its own HTTP request.  The result
of that page will be included in the current page.</p>

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

<p>For compile-time includes, use <a href="jsp-directives.xtp#include">&lt;%@ include file='path'%&gt;</a></p>

<example title="inc.jsp">
&lt;%= 2 + 2 %&gt;
</example>

<example title="test.jsp">
Header
&lt;jsp:include page='inc.jsp'/&gt;
Footer
</example>
<results>
Header
4
Footer
</results>

</s2>

<s2 name="forward" title="&lt;jsp:forward page=&quot;path&quot; /&gt;" index="forward; redirect" type="defun">
<p>Forwards the request to another page, i.e. an internal redirect.</p>

<p>If the page has already written some output, jsp:request will clear
the output <a href="jsp-directives.xtp#buffer">buffer</a>.</p>

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

<example title="fwd.jsp">
&lt;%= 2 + 2 %&gt;
</example>

<example title="test.jsp">
Header
&lt;jsp:forward page='inc.jsp'/&gt;
Footer
</example>
<results>
4
</results>
</s2>

<s2 name="usebean" title="&lt;jsp:useBean id=&quot;name&quot; ...&gt;..." index="bean, creation" type="defun">
<p>Creates a new bean and variable for the page.</p>

<deftable>
<tr><th>Attribute</th><th>Value</th><th>Meaning
</th></tr><tr><td>id</td><td>&#160;</td><td>The variable name for the bean
</td></tr><tr><td>class</td><td>&#160;</td><td>The bean's Java class
</td></tr><tr><td>scope</td><td>&#160;</td><td>&#160;
</td></tr><tr><td>&#160;</td><td>page</td><td>Only active in the page, stored in pageContext
</td></tr><tr><td>&#160;</td><td>request</td><td>Active for the request, stored in request
</td></tr><tr><td>&#160;</td><td>session</td><td>Active for the session, stored in session
</td></tr><tr><td>&#160;</td><td>application</td><td>Active for the application, stored in application
</td></tr></deftable>

<p>jsp:useBean enables a popular style JSP page creation where Java
Beans calculate the content, and JSP formats the presentation.</p>

<p>jsp:useBean creates an initializes a JSP bean for the page. The
scope attribute determines the bean lifetime.  For example, a session
bean will be created once in a session.</p>

<p>jsp:useBean assigns the bean to the variable <var>name</var>.  It will also
store the bean in the appropriate scope variable.  For example, an
application bean "foo" will be stored in the application variable.</p>

<p>jsp:useBean can also initialize beans.  When jsp:useBean creates a
new bean, it will execute the JSP in the jsp:useBean tag.</p>

<p>Roughly, JSP makes the following translation:</p>

<example>
&lt;jsp:useBean id='foo' 
                class='com.caucho.test.TestBean' 
                scope='session'&gt;
  &lt;% foo.myInitialization("test"); %gt;
&lt;/jsp:useBean&gt;
</example>
<def>
com.caucho.test.TestBean foo;
foo = (com.caucho.test.TestBean) session.getValue("foo");
if (foo == null) {
  foo = new com.caucho.test.TestBean();
  session.value.foo = foo;
  foo.myInitialization("test");
}
</def>

</s2>

<s2 name="getProperty" title="&lt;jsp:getProperty name=&quot;name&quot; ... /&gt;" index="bean, display" type="defun">
<p>Prints a bean property.</p>

<deftable>
<tr><th>Attribute</th><th>Meaning
</th></tr><tr><td>name</td><td>The variable name for the bean
</td></tr><tr><td>property</td><td>The property name to retrieve.
</td></tr></deftable>

<p>jsp:getProperty converts property names following the bean
standards.</p>

<p>Roughly, jsp:getProperty makes the following conversion:</p>

<example>
&lt;jsp:getProperty name='foo' property='bar'/&gt;
</example>
<def>
out.print(foo.getBar());
</def>

</s2>

<s2 name="setPropertyValue" title="&lt;jsp:setProperty ... value=&quot;value&quot;/&gt;" index="bean, setting" type="defun">
<p>Sets a bean property to <var>value</var>.</p>

<deftable>
<tr><th>Attribute</th><th>Meaning
</th></tr><tr><td>name</td><td>The variable name for the bean
</td></tr><tr><td>property</td><td>The property name to set.
</td></tr><tr><td>value</td><td>The value to set.
</td></tr></deftable>

<p>If value is a runtime attribute, the bean property gets the
expression value.  If it's a static string, the value is first
converted to the argument type and then set.</p>

<example>
&lt;jsp:setProperty name='foo' property='count' value='10'/&gt;
</example>
<results>
foo.setCount(10);
</results>
<example>
&lt;jsp:setProperty name='foo' property='string' value='10'/&gt;
</example>
<results>
foo.setString("10");
</results>
<example>
&lt;jsp:setProperty name='foo' property='count' value='&lt;%= 2 + 2 %&gt;'/&gt;
</example>
<results>
foo.setCount(2 + 2);
</results>
<example>
&lt;jsp:setProperty name='foo' property='count' value='2 + 2'/&gt;
</example>
<results>
error
</results>
<example>
&lt;jsp:setProperty name='foo' property='char' value='10'/&gt;
</example>
<results>
foo.setChar('1');
</results>

</s2>

<s2 name="setPropertyParam" title="&lt;jsp:setProperty ... param=&quot;param&quot;/&gt;" index="bean, setting" type="defun">
<p>Sets a bean property to a parameter value.</p>

<deftable>
<tr><th>Attribute</th><th>Value</th><th>Meaning
</th></tr><tr><td>name</td><td>&#160;</td><td>The variable name for the bean
</td></tr><tr><td>property</td><td><var>property</var></td><td>The property name to set.
</td></tr><tr><td>&#160;</td><td>*</td><td>Set all properties
</td></tr><tr><td>param</td><td><var>param</var></td><td>The form parameter to use as a value.
</td></tr><tr><td>&#160;</td><td><var>empty</var></td><td>If missing, use <var>property</var>
</td></tr></deftable>

<p>The second form of jsp:setProperty lets scripts easily set Bean
properties to form values.</p>
</s2>
</s1>

    </body>
</document>