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. Template text and other JSP
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> 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 "Yes" in the
"Dynamic value accepted" column in
the Attributes table for each action that follows). For such an
attribute, the value can be specified as an EL or Java expression, or
by a <jsp:attribute> element:
<% String headerPage = currentTemplateDir + "/header.jsp"; %>
<%-- Using a Java expression --%>
<jsp:include page="<%= headerPage %>" />
<% pageContext.setAttribute("scopedVar", headerPage);
<%-- Using an EL expression --%>
<jsp:include page="${scopedVar}" />
<%-- Using a <jsp:attribute> element --%>
<jsp:include>
<jsp:attribute name="page">
${scopedVar}
</jsp:attribute>
</jsp:include>
The attribute descriptions for each action in this section define
whether a request-time attribute value is accepted or not.
The
<jsp:attribute>
element defines an attribute value for another JSP action element, as
an alternative to entering the attribute value as a regular XML
attribute value in the opening tag or to define fragment input. It
can also be used in conjunction with the
<jsp:element> action to dynamically build a
template text markup element.
Syntax
<jsp:attribute name="attrName " [trim="true |false"]>
Attribute value, typically created by nested JSP elements
</jsp:attribute>
Attributes
|
name
|
String
|
No
|
The name of the attribute to assign a value. When the action is used
with an action other than <jsp:element>, the
named attribute must accept a dynamic value.
|
trim
|
boolean
|
No
|
Set to false to disable removal of leading and
trailing whitespace from the body evaluation result.
|
Example
<%-- Setting a JSP action attribute value --%>
<jsp:include>
<jsp:attribute name="page">
${someValue}
</jsp:attribute>
</jsp:include>
<%-- Defining an attribute for a generated markup element --%>
<jsp:element name="a">
<jsp:attribute name="href">
<c:url value="${someURL}" />
</jsp:attribute>
</jsp:element>
The
<jsp:body>
action defines a body for an action element. It's
required only when the action attributes are defined by
<jsp:attribute> elements.
Syntax
<jsp:body>
Body content
</jsp:body>
Attributes
None.
Example
<jsp:plugin type="applet" code="Clock2.class"
codebase="applet" jreversion="1.2">
<jsp:attribute name="width">160</jsp:attribute>
<jsp:attribute name="height">150</jsp:attribute>
<jsp:body>
<jsp:params>
<jsp:param name="bgcolor" value="ccddff" />
</jsp:params>
<jsp:fallback>
Plugin tag OBJECT or EMBED not supported by browser.
</jsp:fallback>
</jsp:body>
</jsp:plugin>
The
<jsp:doBody>
action must only be used in a tag file. It evaluates the
corresponding custom action body, adding the output to the calling
page's output stream or capturing it in a variable.
Syntax
<jsp:doBody [var="var " | varReader="varReader "]
[scope="page |request|session|application"] />
Attributes
|
scope
|
String
|
No
|
The scope for the variable.
|
var
|
String
|
No
|
The name of the variable to hold the evaluation result as a
String.
|
varReader
|
String
|
No
|
The name of the variable to capture and expose the evaluation result
as a java.io.Reader.
|
Example
<%-- Adding the evaluation result to the response --%>
<jsp:doBody/>
<%-- Capturing the evaluation result for further processing --%>
<jsp:doBody var="result" />
The
<jsp:element>
dynamically creates an XML element and adds it to the response.
It's useful primarily in JSP Documents (JSP pages in
XML syntax), where other approaches can't be used
because of the well-formedness requirement.
Syntax 1: Without a body
<jsp:element name="elementName" />
Syntax 2: With a body
<jsp:element name="elementName">
<jsp:attribute> and/or <jsp:body> actions
</jsp:element>
Attributes
|
name
|
String
|
Yes
|
The name of the generated element.
|
Example
<%-- Generates <a href="somepage.jsp">Some text</a>
<jsp:element name="a">
<jsp:attribute name="href">somepage.jsp</jsp:attribute>
<jsp:body>Some text</jsp:body>
</jsp:element>
The
<jsp:fallback>
action can only be used 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 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
|
page
|
String
|
Yes
|
Page- 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
|
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 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
|
page
|
String
|
Yes
|
A page- or context-relative URI path for the resource to include.
|
flush
|
boolean
|
No
|
Set to true to flush the buffer before including
the target.
|
Example
<jsp:include page="navigation.jsp" />
The
<jsp:invoke>
action must only be used in a tag file. It evaluates the named
fragment, adding the output to the calling page's
output stream or capturing it in a variable.
Syntax
<jsp:invoke fragment="fragmentName " [var="var " | varReader="varReader "]
[scope="page |request|session|application"] />
Attributes
|
fragment
|
String
|
No
|
The name of an attribute that defines a fragment.
|
scope
|
String
|
No
|
The scope for the variable.
|
var
|
String
|
No
|
The name of the variable to hold the evaluation result as a
String.
|
varReader
|
String
|
No
|
The name of the variable to capture and expose the evaluation result
as a java.io.Reader.
|
Example
<%@ attribute name="pattern" fragment="true" %>
<%-- Adding the evaluation result to the response --%>
<jsp:invoke fragment="pattern"/>
<%-- Capturing the evaluation result for further processing --%>
<jsp:invoke fragment="pattern" var="result" />
The
<jsp:output>
element can only be used in JSP Documents (JSP pages in XML syntax)
and tag files in XML syntax. It modifies properties of the generated
response.
Syntax
<jsp:output [omit-xml-declaration="true|yes|false|no"]
[doctype-root-element="elementName"
[doctype-public="publicID"] doctype-system="systemID"]
/>
Attributes
|
omit-xml-declaration
|
boolean
|
No
|
Set to true or yes to prevent
an XML declaration to be added to the response, or to
false or no to force an XML
declaration to be added.
The default is yes for a JSP Document with a
<jsp:root> element and for tag files in XML
syntax, no for all other cases.
|
doctype-root-element
|
String
|
No
|
The root element name to use in the generated DOCTYPE declaration.
|
doctype-public
|
String
|
No
|
The Public ID to use in the generated DOCTYPE declaration.
|
doctype-system
|
String
|
No
|
The System ID to use in the generated DOCTYPE declaration.
|
Example
<!-- Add an XML declaration to the response -->
<jsp:output omit-xml-declaration="true" />
<!-- Add a DOCTYPE declaration to the response -->
<jsp:output doctype-root-element="html"
doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN"
doctype-system='http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'/>
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
|
name
|
String
|
No
|
The parameter name.
|
value
|
String
|
Yes
|
The parameter value.
|
Example
<jsp:include page="navigation.jsp">
<jsp:param name="bgColor" value="<%= currentBGColor %>" />
</jsp:include>
The
<jsp:params>
action can only be used 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
|
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 applet.
|
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
|
Yes
|
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 spec 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 need 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 above and below the applet
area, in pixels.
|
width
|
String
|
Yes
|
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:root>
action element can only be used as the root element in a JSP Document
(a JSP page in XML syntax). In specification versions prior JSP 2.0,
using a <jsp:root> element was the only way
to identify a JSP page as a JSP Document, but there are now other
means (see Chapter 16) to do so. Hence, the
<jsp:root> element is optional and should
rarely be used.
Syntax
<jsp:root version="jspVersion">
Well-formed XML content
</jsp:root>
Attributes
|
version
|
String
|
No
|
The JSP specification with which the JSP Document is compliant.
|
Example
<jsp:root version="2.0">
<employee>
<name>${param.empName}</name>
<dept>${param.empDept}</dept>
<employee>
</jsp:root>
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
|
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 below
|
Yes
|
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 as a
Java expression, 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:
|
boolean or Boolean
|
Boolean.valueOf(String), false for an empty string
|
byte or Byte
|
Byte.valueOf(String), 0 for an empty string
|
char or Character
|
String.charAt(0), 0 for an empty string
|
double or Double
|
Double.valueOf(String), 0 for an empty string
|
int or Integer
|
Integer.valueOf(String), 0 for an empty string
|
float or Float
|
Float.valueOf(String), 0 for an empty string
|
long or Long
|
Long.valueOf(String), 0 for an empty string
|
short or Short
|
Short.valueOf(String), 0 for an empty string
|
Object
|
new String(String)
|
For other types, such as a java.util.Date, the JSP
container use 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 22.
Example
<jsp:setProperty name="user" property="*" />
<jsp:setProperty name="user" property="modDate"
value="<%= new java.util.Date( ) %>" />
The
<jsp:text>
action is primarily intended for JSP Documents (JSP pages in XML
syntax). Its body must only contain template text and EL expressions;
neither JSP action elements nor scripting elements are allowed. When
used in an XML document, the body content must be well-formed. The
action's body content is evaluated and the result is
added to the response with whitespace preserved.
Syntax
<jsp:text>
Template text and EL expressions only
</jsp:text>
Attributes
None.
Example
<jsp:text>
Some text and ${anELexpression}
</jsp:text>
<jsp:text>
<![CDATA[<unknownelement/>]]>
</jsp:text>
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
|
beanName
|
String
|
Yes
|
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 the
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:
Attempt to locate an object based on the id and
scope attribute values. Define a scripting language variable with the given
id of the specified type or
class. If the object is found, the variable's value is
initialized with a reference to the located object, cast to the type
specified by type or class.
This completes the processing of the action. If the action element
has a nonempty body, it's ignored. If the object isn't found in the specified scope and
neither class nor beanName is
specified, an InstantiationException is thrown.
This completes the processing of the action. If the object isn't found in the specified scope,
and the class attribute specifies a non-abstract
class with a public no-args constructor, a new instance of the class
is created and associated with the scripting variable and with the
specified name in the specified scope. After this, step 7 is
performed. If the object isn't found, and the specified class
doesn't fulfill the requirements, an
InstantiationException is thrown. This completes
the processing of the action. If the object isn't found in the specified scope,
and the beanName attribute is specified, the
instantiate( ) method of the
java.beans.Beans class is invoked with the
ClassLoader of the JSP implementation class
instance and the beanName as arguments. If the
method succeeds, the new object reference is associated with the
scripting variable and with the specified name in the specified
scope. After this, step 7 is performed. If the action element has a nonempty body, the body is processed. The
scripting variable is initialized and available within the scope of
the body. The text of the body is treated as elsewhere; if there is
template text, it's passed through to the response;
scriptlets and action tags are evaluated. A common use of a nonempty body is to complete initializing the
created instance; in that case, the body typically contains
<jsp:setProperty> actions and scriptlets.
Example
<jsp:useBean id="clock" class="java.util.Date" />
| 
No comments:
Post a Comment