Struts Framework
Welcome
Home
Kickstart FAQ
User Guide
Resources
Who We Are
Downloads
Binaries
Source Code
Getting Started
Installation
Release Notes
Javadoc
Mailing Lists
Bug Database
Developer Guides
Bean Tags
HTML Tags
Logic Tags
Template Tags
Digester
Utilities
TagLib Documentation
Bean Tags
HTML Tags
Logic Tags
Template Tags
Current Development
Installation (nightly)
Release Notes (nightly)
Javadoc (nightly)
Workflow Proposal
TODO List
Struts Bean Tags

This tag library contains tags useful in accessing beans and their properties, as well as defining new beans (based on these accesses) that are accessible to the remainder of the page via scripting variables and page scope attributes. Convenient mechanisms to create new beans based on the value of request cookies, headers, and parameters are also provided.

Many of the tags in this tag library will throw a JspException at runtime when they are utilized incorrectly (such as when you specify an invalid combination of tag attributes). JSP allows you to declare an "error page" in the <%@ page %> directive. If you wish to process the actual exception that caused the problem, it is passed to the error page as a request attribute under key org.apache.struts.action.EXCEPTION.

If you are viewing this page from within the Struts Documentation Application (or online at http://jakarta.apache.org/struts), you can learn more about using these tags in the Bean Tags Developer's Guide.

Tag NameDescription
cookie Define a scripting variable based on the value(s) of the specified request cookie.
define Define a scripting variable based on the value(s) of the specified bean property.
header Define a scripting variable based on the value(s) of the specified request header.
include Load the response from a dynamic application request and make it available as a bean.
message Render an internationalized message string to the response.
page Expose a specified item from the page context as a bean.
parameter Define a scripting variable based on the value(s) of the specified request parameter.
resource Load a web application resource and make it available as a bean.
size Define a bean containing the number of elements in a Collection or Map.
struts Expose a named Struts internal configuration object as a bean.
write Render the value of the specified bean property to the current JspWriter.
cookie - Define a scripting variable based on the value(s) of the specified request cookie.

Retrieve the value of the specified request cookie (as a single value or multiple values, depending on the multiple attribute), and define the result as a page scope attribute of type Cookie (if multiple is not specified) or Cookie[] (if multiple is specified).

If no cookie with the specified name can be located, and no default value is specified, a request time exception will be thrown.

Attribute NameDescription
id

Specifies the name of the scripting variable (and associated page scope attribute) that will be made available with the value of the specified request cookie.

[Required] [RT Expr]
multiple

If any arbitrary value for this attribute is specified, causes all matching cookies to be accumulated and stored into a bean of type Cookie[]. If not specified, the first value for the specified cookie will be retrieved as a value of type Cookie.

[RT Expr]
name

Specifies the name of the request cookie whose value, or values, is to be retrieved.

[Required] [RT Expr]
value

The default cookie value to return if no cookie with the specified name was included in this request.

[RT Expr]
define - Define a scripting variable based on the value(s) of the specified bean property.

Retrieve the value of a specified bean property, and define it as an attribute (in the scope specified by the toScope property) accessible to the remainder of the current page. No type conversion is performed on the returned property value, unless it is a Java primitive type, in which case it is wrapped in the appropriate wrapper class (i.e. int is wrapped by java.lang.Integer).

If you specify a "value" attribute, the exposed bean will be of type java.lang.String and initialized to the specified value.

If a problem occurs while retrieving the specified bean property, a request time exception will be thrown.

The <bean:define> tag differs from <jsp:useBean> in several ways, including:

  • Unconditionally creates (or replaces) a bean under the specified identifier.
  • Can create a bean with the value returned by a property getter of a different bean (including properties referenced with a nested and/or indexed property name).
  • Can create a bean whose contents is a literal string (or the result of a runtime expression) specified by the value attribute.
  • Does not support nested content (such as <jsp:setProperty> tags) that are only executed if a bean was actually created.

USAGE NOTE - There is a restriction in the JSP 1.1 Specification that disallows using the same value for an id attribute more than once in a single JSP page. Therefore, you will not be able to use <bean:define> for the same bean name more than once in a single page.

See the Bean Developer's Guide section on bean creation for more information about these differences, as well as alternative approaches to introducing beans into a JSP page.

Attribute NameDescription
id

Specifies the name of the scripting variable (and associated page scope attribute) that will be made available with the value of the specified property.

[Required] [RT Expr]
name

Specifies the attribute name of the bean whose property is accessed to define a new page scope attribute (if property is also specified) or the attribute name of the bean that is duplicated with the new reference created by this tag (if property is not also specified). This attribute is required unless you specify a value attribute.

[RT Expr]
property

Specifies the name of the property to be accessed on the bean specified by name. This value may be a simple, indexed, or nested property reference expression. If not specified, the bean identified by name is given a new reference identified by id.

[RT Expr]
scope

Specifies the variable scope searched to retrieve the bean specified by name. If not specified, the default rules applied by PageContext.findAttribute() are applied.

[RT Expr]
toScope

Specifies the variable scope into which the newly defined bean will be created. If not specified, the bean will be created in page scope.

[RT Expr]
type

Specifies the fully qualified class name of the value to be exposed as the id attribute. If not specified, the default type is java.lang.String (if you specify a value attribute), or java.lang.Object otherwise.

[RT Expr]
value

The java.lang.String value to which the exposed bean should be set. This attribute is required unless you specify the name attribute.

[RT Expr]
header - Define a scripting variable based on the value(s) of the specified request header.

Retrieve the value of the specified request header (as a single value or multiple values, depending on the multiple attribute), and define the result as a page scope attribute of type String (if multiple is not specified) or String[] (if multiple is specified).

If no header with the specified name can be located, and no default value is specified, a request time exception will be thrown.

Attribute NameDescription
id

Specifies the name of the scripting variable (and associated page scope attribute) that will be made available with the value of the specified request header.

[Required] [RT Expr]
multiple

If any arbitrary value for this attribute is specified, causes a call to HttpServletRequest.getHeaders() and a definition of the result as a bean of type String[]. Otherwise, HttpServletRequest.getHeader() will be called, and a definition of the result as a bean of type String will be performed.

[RT Expr]
name

Specifies the name of the request header whose value, or values, is to be retrieved.

[Required] [RT Expr]
value

The default header value to return if no header with the specified name was included in this request.

[RT Expr]
include - Load the response from a dynamic application request and make it available as a bean.

Perform an internal dispatch to the specified application component (or external URL) and make the response data from that request available as a bean of type String. This tag has a function similar to that of the standard <jsp:include> tag, except that the response data is stored in a page scope attribute instead of being written to the output stream. If the current request is part of a session, the generated request for the include will also include the session identifier (and thus be part of the same session).

The URL used to access the specified application component is calculated based on which of the following attributes you specify (you must specify exactly one of them):

  • forward - Use the value of this attribute as the name of a global ActionForward to be looked up, and use the context-relative URI found there.
  • href - Use the value of this attribute unchanged (since this might link to a resource external to the application, the session identifier is not included.
  • page - Use the value of this attribute as a context-relative URI to the desired resource.
Attribute NameDescription
anchor

Optional anchor tag ("#xxx") to be added to the generated hyperlink. Specify this value without any "#" character.

[RT Expr]
forward

Logical name of a global ActionForward that contains the actual content-relative URI of the resource to be included.

[RT Expr]
href

Absolute URL (including the appropriate protocol prefix such as "http:") of the resource to be included. Because this URL could be external to the current web application, the session identifier will not be included in the request.

[RT Expr]
id

Specifies the name of the scripting variable (and associated page scope attribute) that will be made available with the value of the specified web application resource.

[Required] [RT Expr]
name

Context-relative name (starting with a '/') of the web application request to be dispatched, and whose response data is to be made available as a bean. DEPRECATED - Use the "page" attribute instead.

[RT Expr]
page

Context-relative URI (starting with a '/') of the web application resource to be included.

[RT Expr]
transaction

Set to true if you want the current transaction control token included in the generated URL for this include.

[RT Expr]
message - Render an internationalized message string to the response.

Retrieves an internationalized message for the specified locale, using the specified message key, and write it to the output stream. Up to five parametric replacements (such as "{0}") may be specified.

Attribute NameDescription
arg0

First parametric replacement value, if any.

[RT Expr]
arg1

Second parametric replacement value, if any.

[RT Expr]
arg2

Third parametric replacement value, if any.

[RT Expr]
arg3

Fourth parametric replacement value, if any.

[RT Expr]
arg4

Fifth parametric replacement value, if any.

[RT Expr]
bundle

The name of the application scope bean under which the MessageResources object containing our messages is stored. If not specified, the default name (the value of the Action.MESSAGES_KEY constant string) is used.

[RT Expr]
key

The message key of the requested message, which must have a corresponding value in the message resources.

[Required] [RT Expr]
locale

The name of the session scope bean under which our currently selected Locale object is stored. If not specified, the default name (the value of the Action.LOCALE_KEY constant string) is used.

[RT Expr]
page - Expose a specified item from the page context as a bean.

Retrieve the value of the specified item from the page context for this page, and define it as a scripting variable, and a page scope attribute accessible to the remainder of the current page.

If a problem occurs while retrieving the specified configuration object, a request time exception will be thrown.

Attribute NameDescription
id

Specifies the name of the scripting variable (and associated page scope attribute) that will be made available with the value of the specified page context property.

[Required] [RT Expr]
property

Name of the property from our page context to be retrieved and exposed. Must be one of application, config, request, response, or session.

[Required] [RT Expr]
parameter - Define a scripting variable based on the value(s) of the specified request parameter.

Retrieve the value of the specified request parameter (as a single value or multiple values, depending on the multiple attribute), and define the result as a page scope attribute of type String (if multiple is not specified) or String[] (if multiple is specified).

If no request parameter with the specified name can be located, and no default value is specified, a request time exception will be thrown.

Attribute NameDescription
id

Specifies the name of the scripting variable (and associated page scope attribute) that will be made available with the value of the specified request parameter.

[Required] [RT Expr]
multiple

If any arbitrary value for this attribute is specified, causes a call to ServletRequest.getParameterValues() and a definition of the result as a bean of type String[]. Otherwise, ServletRequest.getParameter() will be called, and a definition of the result as a bean of type String will be performed.

[RT Expr]
name

Specifies the name of the request parameter whose value, or values, is to be retrieved.

[Required] [RT Expr]
value

The default parameter value to return if no parameter with the specified name was included in this request.

[RT Expr]
resource - Load a web application resource and make it available as a bean.

Retrieve the value of the specified web application resource, and make it available as either a InputStream or a String, depending on the value of the input attribute.

If a problem occurs while retrieving the specified resource, a request time exception will be thrown.

Attribute NameDescription
id

Specifies the name of the scripting variable (and associated page scope attribute) that will be made available with the value of the specified web application resource.

[Required] [RT Expr]
input

If any arbitrary value for this attribute is specified, the resource will be made available as an InputStream. If this attribute is not specified, the resource will be made available as a String.

[RT Expr]
name

Context-relative name (starting with a '/') of the web application resource to be loaded and made available.

[Required] [RT Expr]
size - Define a bean containing the number of elements in a Collection or Map.

Given a reference to an array, Collection or Map, creates a new bean, of type java.lang.Integer, whose value is the number of elements in that collection. You can specify the collection to be counted in any one of the following ways:

  • As a runtime expression specified as the value of the collection attribute.
  • As a JSP bean specified by the name attribute.
  • As the property, specified by the property attribute, of the JSP bean specified by the bean attribute.
Attribute NameDescription
collection

A runtime expression that evaluates to an array, a Collection, or a Map.

[RT Expr]
id

The name of a page scope JSP bean, of type java.lang.Integer, that will be created to contain the size of the underlying collection being counted.

[Required] [RT Expr]
name

The name of the JSP bean (optionally constrained to the scope specified by the scope attribute) that contains the collection to be counted (if property is not specified), or whose property getter is called to return the collection to be counted (if property is specified.

[RT Expr]
property

The name of the property, of the bean specified by the name attribute, whose getter method will return the collection to be counted.

[RT Expr]
scope

The bean scope within which to search for the JSP bean specified by the name attribute. If not specified, the available scopes are searched in ascending sequence.

[RT Expr]
struts - Expose a named Struts internal configuration object as a bean.

Retrieve the value of the specified Struts internal configuration object, and define it as a scripting variable and as a page scope attribute accessible to the remainder of the current page. You must specify exactly one of the formBean, forward, and mapping attributes to select the configuration object to be exposed.

If a problem occurs while retrieving the specified configuration object, a request time exception will be thrown.

Attribute NameDescription
id

Specifies the name of the scripting variable (and associated page scope attribute) that will be made available with the value of the specified Struts internal configuration object.

[Required] [RT Expr]
formBean

Specifies the name of the Struts ActionFormBean definition object to be exposed.

[RT Expr]
forward

Specifies the name of the global Struts ActionForward definition object to be exposed.

[RT Expr]
mapping

Specifies the matching path of the Struts ActionMapping definition object to be exposed.

[RT Expr]
write - Render the value of the specified bean property to the current JspWriter.

Retrieve the value of the specified bean property, and render it to the current JspWriter as a String. If there is a PropertyEditor configured for the property value's class, the getAsText() method will be called. Otherwise, the usual toString() conversions will be applied.

If a problem occurs while retrieving the specified bean property, a request time exception will be thrown.

Attribute NameDescription
filter

If this attribute is set to true, the rendered property value will be filtered for characters that are sensitive in HTML, and any such characters will be replaced by their entity equivalents. By default, filtering is performed - to disable it, you must explicitly set this attribute to false.

[RT Expr]
ignore

If this attribute is set to true, and the bean specified by the name and scope attributes does not exist, simply return without writing anything. The default value is false, which will cause a runtime exception to be thrown, consistent with the other tags in this tag library.

[RT Expr]
name

Specifies the attribute name of the bean whose property is accessed to retrieve the value specified by property (if specified). If property is not specified, the value of this bean itself will be rendered.

[Required] [RT Expr]
property

Specifies the name of the property to be accessed on the bean specified by name. This value may be a simple, indexed, or nested property reference expression. If not specified, the bean identified by name will itself be rendered. If the specified property returns null, no output will be rendered.

[RT Expr]
scope

Specifies the variable scope searched to retrieve the bean specified by name. If not specified, the default rules applied by PageContext.findAttribute() are applied.

[RT Expr]

Copyright (c) 2000-2002, Apache Software Foundation