A.3 Action Elements

Action elements use XML element syntax and represent components that are invoked when a client requests the JSP page. They may encapsulate functionality such as input validation using beans, database access, or passing control to another page. The JSP specification defines a few standard action elements, described in this section, and also includes a framework for developing custom action elements.

An action element consists of a start tag (optionally with attributes), a body, and an end tag. Other elements can be nested in the body. Here's an example:

<jsp:forward page="nextPage.jsp">
  <jsp:param name="aParam" value="aValue" />
</jsp:forward>

If the action element doesn't have a body, a shorthand notation can be used where the start tag ends with "/>" instead of ">", as shown by the <jsp:param> param action in this example. The action element name and attribute names are case-sensitive.

Some standard action attributes accept a request-time attribute value (marked with "RT expression" in the "Dynamic value accepted" column in the Attributes table for each action that follows), using the JSP expression syntax:

<% String headerPage = currentTemplateDir + "/header.jsp"; %>
<jsp:include page="<%= headerPage %>" />

The attribute descriptions for each action in this section define whether a request-time attribute value is accepted or not.

JSTL actions, described in Appendix B, and custom actions may accept JSTL Expression Language (EL) expressions for dynamic values instead of request-time attribute values.

The <jsp:fallback> action can be used only in the body of a <jsp:plugin> action. Its body specifies the template text to use for browsers that don't support the HTML <embed> or <object> elements.

Syntax

<jsp:fallback>
  Fallback body
</jsp:fallback>

Attributes

None

Example

<jsp:plugin type="applet" code="Clock2.class" 
  codebase="applet" 
  jreversion="1.2" width="160" height="150" >
  <jsp:fallback>
    Plugin tag OBJECT or EMBED not supported by browser.
  </jsp:fallback>
</jsp:plugin>

The <jsp:forward> action passes the request processing control to another JSP page or servlet in the same web application. The execution of the current page is terminated, giving the target resource full control over the request.

If any response content has been buffered when the <jsp:forward> action is executed, the buffer is cleared first. If the response has already been committed (i.e., partly sent to the browser), the forwarding fails with an IllegalStateException.

The URI path information available through the implicit request object is adjusted to reflect the URI path information for the target resource. All other request information is left untouched, so the target resource has access to all the original parameters and headers passed with the request. Additional parameters can be passed to the target resource through <jsp:param> elements in the <jsp:forward> element's body.

Syntax 1: Without parameters

<jsp:forward page="pageOrContextRelativePath" />

Syntax 2: With nested <jsp:param> actions

<jsp:forward page="pageOrContextRelativePath" />
  One or more <jsp:param> actions
</jsp:forward>

Attributes

Attribute name	Java type	Dynamic value accepted	Description
page	String	RT expression	A page-relative or context-relative URI path for the resource to forward to

Example

<jsp:forward page="list.jsp" />

The <jsp:getProperty> action adds the value of a bean property, converted to a string, to the response generated by the page.

Syntax

<jsp:getProperty name="beanVariableName" property="propertyName" />

Attributes

Attribute name	Java type	Dynamic value accepted	Description
name	String	No	The name assigned to a bean in one of the JSP scopes
property	String	No	The name of the bean's property to include in the page

Example

<jsp:getProperty name="clock" property="hours" />

The <jsp:include> action includes the response from another JSP page, servlet, or static file in the same web application. The execution of the current page continues after including the response generated by the target resource.

If any response content has been buffered when the <jsp:include> action is executed, the flush attribute controls whether or not to flush the buffer.

The URI path information, available through the implicit request object, reflects the URI path information for the source JSP page even in the target resource. All other request information is also left untouched, so the target resource has access to all the original parameters and headers passed with the request. Additional parameters can be passed to the target resource through <jsp:param> elements in the <jsp:include> element's body.

Syntax

<jsp:include page="pageOrContextRelativePath" [flush="true|false"] />

Attributes

Attribute name	Java type	Dynamic value accepted	Description
page	String	RT expression	A page-relative or context-relative URI path for the resource to include.
flush	boolean	No	Set to true to flush the buffer before including the target. Default is false.

Example

<jsp:include page="navigation.jsp" />

The <jsp:param> action can be used in the body of a <jsp:forward> or <jsp:include> action to specify additional request parameters for the target resource, as well as in the body of a <jsp:params> action to specify applet parameters.

Syntax

<jsp:param name="parameterName" value="parameterValue" />

Attributes

Attribute name	Java type	Dynamic value accepted	Description
name	String	No	The parameter name
value	String	RT expression	The parameter value

Example

<jsp:include page="navigation.jsp">
  <jsp:param name="bgColor" value="<%= currentBGColor %>" />
</jsp:include>

The <jsp:params> action can be used only in the body of a <jsp:plugin> action to enclose a set of <jsp:param> actions that specify applet parameters.

Syntax

<jsp:params>
  One or more <jsp:param> actions
</jsp:params>

Attributes

None

Example

<jsp:plugin type="applet" code="Clock2.class" 
  codebase="applet" 
  jreversion="1.2" width="160" height="150" >
  <jsp:params>
    <jsp:param name="bgcolor" value="ccddff" />
  </jsp:params>
</jsp:plugin>

The <jsp:plugin> action generates HTML <embed> or <object> elements (depending on the browser type) that result in the download of the Java Plugin software (if required) and subsequent execution of the specified Java applet or JavaBeans component. The body of the action can contain a <jsp:params> element to specify applet parameters and a <jsp:fallback> element to specify the text shown in browsers that don't support the <embed> or <object> HTML elements. For more information about the Java Plugin, see http://java.sun.com/products/plugin/.

Syntax

<jsp:plugin [align="bottom|middle|top"] [archive="archiveList"]
  code="className" codeBase="relativePath" [height="height"]
  [hspace="horizontalSpace"] [iepluginurl="pluginURL"]
  [jreversion="jreVersion"] [name="appletName"] 
  [nspluginurl="pluginURL"] [title="title"] type="applet|bean"
  [vspace="verticalSpace"] [width="width"] >
  Optionally one <jsp:param> and one <jsp:fallback> action
</jsp:plugin>

Attributes

Attribute name	Java type	Dynamic value accepted	Description
align	String	No	Alignment of the applet area. One of bottom, middle, or top.
archive	String	No	A comma-separated list of URIs for archives containing classes and other resources that will be preloaded. The classes are loaded using an instance of an AppletClassLoader with the given codebase. Relative URIs for archives are interpreted with respect to the applet's codebase.
code	String	No	The fully qualified class name for the object.
codebase	String	No	The relative URL for the directory that contains the class file. The directory must be a subdirectory to the directory holding the page according to the HTML 4.0 spec.
height	String	RT expression	The height of the applet area, in pixels or percentage.
hspace	String	No	The amount of whitespace to be inserted to the left and right of the applet area, in pixels.
iepluginurl	String	No	The URL for the location of the Internet Explorer Java Plugin. The default is implementation-dependent.
jreversion	String	No	Identifies the specification version number of the JRE the component requires in order to operate. The default is 1.1.
name	String	No	Applet name, used by other applets on the same page that needs to communicate with it.
nspluginurl	String	No	The URL for the location of the Netscape Java Plugin. The default is implementation-dependent.
title	String	No	Text to be rendered by the browser for the applet in some way, for instance as a tool tip.
type	String	No	The type of object to embed, one of applet or bean.
vspace	String	No	The amount of whitespace to be inserted to the above and below the applet area, in pixels.
width	String	RT expression	The width of the applet area, in pixels or percentage.

Example

<jsp:plugin type="applet" code="Clock2.class" 
  codebase="applet" 
  jreversion="1.2" width="160" height="150" >
  <jsp:params>
    <jsp:param name="bgcolor" value="ccddff" />
  </jsp:params>
  <jsp:fallback>
    Plugin tag OBJECT or EMBED not supported by browser.
  </jsp:fallback>
</jsp:plugin>

The <jsp:setProperty> action sets the value of one or more bean properties.

Syntax

<jsp:setProperty name="beanVariableName" property="propertyName"
  [param="parameterName" | value="value"] />

Attributes

Attribute name	Java type	Dynamic value accepted	Description
name	String	No	The name assigned to a bean in one of the JSP scopes.
property	String	No	The name of the bean's property to set or an asterisk (*) to set all properties with name matching request parameters.
param	String	No	The name of a request parameter that holds the value to use for the specified property. If omitted, the parameter name and the property name must be the same.
value	See the next table	RT expression	An explicit value to assign to the property. This attribute can't be combined with the param attribute.

The property type can be any valid Java type, including primitive types and arrays (i.e. an indexed property). If a runtime attribute value is specified by the value attribute, the type of the expression must match the property's type.

If the value is a String, either in the form of a request parameter value or explicitly specified by the value attribute, it's converted to the property's type as follows:

Property type	Conversion method
boolean or Boolean	Boolean.valueOf(String)
byte or Byte	Byte.valueOf(String)
char or Character	String.charAt(0)
double or Double	Double.valueOf(String)
int or Integer	Integer.valueOf(String)
float or Float	Float.valueOf(String)
long or Long	Long.valueOf(String)
short or Short	Short.valueOf(String)
Object	new String(String)

For other types, such as a java.util.Date, the JSP container uses a java.beans.PropertyEditor registered for the type and calls its setAsText(String) method. A property editor associated with a bean can, for instance, convert a string like 2001-11-22 to a Date object that represents this date. How to do so is described in Chapter 20.

Example

<jsp:setProperty name="user" property="*" />
<jsp:setProperty name="user" property="modDate" 
  value="<%= new java.util.Date( ) %>" />

The <jsp:useBean> action associates a Java bean with a name in one of the JSP scopes and also makes it available as a scripting variable. An attempt is first made to find a bean with the specified name in the specified scope. If it's not found, a new instance of the specified class is created.

Syntax 1: Using a concrete class, no body

<jsp:useBean id="beanVariableName" class="className"
  [scope="page|request|session|application"] />

Syntax 2: Using a concrete class, with a body

<jsp:useBean id="beanVariableName" class="className"
  [scope="page|request|session|application"]>
  Evaluated if a new instance is created
</jsp:useBean>

Syntax 3: Using a type and optionally a class or a serialized bean, no body

<jsp:useBean id="beanVariableName" type="className" 
  [class="className" | beanName="className"]
 [ scope="page|request|session|application"] />

Syntax 4: Using a type and optionally a class or a serialized bean, with a body

<jsp:useBean id="beanVariableName" type="className" 
  [class="className" | beanName="className"]
  [scope="page|request|session|application"]>
  Evaluated if a new instance is created
</jsp:useBean>

Attributes

Attribute name	Java type	Dynamic value accepted	Description
beanName	String	RT expression	The name of the bean, as expected by the instantiate( ) method of the Beans. class in the java.beans package
class	String	No	The fully qualified class name for the bean
id	String	No	The name to assign to the bean in the specified scope, as well as name of the scripting variable
scope	String	No	The scope for the bean, one of page, request, session, or application. The default is page
type	String	No	The fully qualified type name for the bean (i.e., a superclass or an interface implemented by the bean's class)

Of the optional attributes, at least one of class or type must be specified. If both are specified, class must be assignable to type. The beanName attribute must be combined with the type attribute, and isn't valid with the class attribute.

The action is processed in these steps:

Example

<jsp:useBean id="clock" class="java.util.Date" />

A.3.1 Custom Actions

A custom action element can be developed by a programmer to extend the JSP language. The JSP Standard Tag Library (JSTL) actions are developed using the API defined by the JSP specification. Application-specific custom actions can also be developed using this API, such as the custom actions for adding cookies to a response and setting headers for no caching used in this book. The JSTL actions are described in Appendix B, and all custom actions of a generic nature used in this book are described in Appendix E.

The general syntax for custom actions is the same as for the JSP standard actions: a start tag (optionally with attributes), a body, and an end tag. Other elements and template text can be nested in the body. Here's an example:

<ora:ifUserInRole value="admin">
  Greetings Master, I hope your day has been pleasant.
</ora:ifUserInRole>

The tag library containing the custom actions must be declared by the taglib directive, assigning a prefix for the custom action elements (ora in this example), before a custom action can be used in a JSP page.