8.6 Bean Tags

The tags that are part of the Bean tag library are used for accessing JavaBeans and their associated properties as well as for defining new beans 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 values of request cookies, headers, and parameters are also provided. Table 8-9 lists the tags within the Bean tag library.

Table 8-9. Custom tags within the Bean tag library

Tag name	Description
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.

Many of the tags in this tag library throw a JspException at runtime when they are used incorrectly (e.g., when you specify an invalid combination of tag attributes). JSP allows you to declare an "error page" in the <%@ page %> directive. If you want 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.

8.6.1 The define Tag

This tag retrieves a specified bean property and defines it as an attribute that is 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 (e.g., int is wrapped by java.lang.Integer). The property value is stored in the scope defined by the toScope variable.

8.6.2 The header Tag

This tag retrieves the value of the specified request header and defines the result as a page-scope attribute of type String. If no header with the specified name can be located and no default value is specified in the value attribute, a request-time exception will be thrown. If the attribute multiple is set to any non-null value, the id attribute will contain the result of the call to HttpServletRequest.getHeaders() rather than a call to HttpServletRequest.getHeader().

8.6.3 The include Tag

This tag performs an internal dispatch to the specified application component (or external URL) and makes the response data from that request available as a bean of type String. The value is stored into the id attribute. 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. This allows you to position the output as needed.

If the current request is part of a session, the generated request for the include will also include the session ID.

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 application-relative or context-relative URI found there.

href

Use the value of this attribute unchanged (as this might link to a resource external to the application, the session identifier is not included).

page

Use the value of this attribute as an application-relative URI to the desired resource. This value must start with a "/".

8.6.4 The message Tag

The message tag is one of the most widely used tags within the Struts tag libraries. It retrieves an internationalized message for the specified locale, using the specified message key, and writes it to the output stream. You can supply up to five parametric replacements (such as "{0}").

The message key may be specified directly, using the key attribute, or indirectly, using the name and property attributes to obtain it from a bean. The bundle attribute allows you to specify the name of an application-scope bean under which a MessageResources object can be found. If no locale attribute is specified, the Locale will be retrieved from the session using the key Action.LOCALE_KEY.

The following is an example of the message tag:

<td><bean:message key="global.user.firstName"/>:</td>

8.6.5 The parameter Tag

This tag retrieves the value of the specified request parameter and defines the result as a page-scope attribute of type String. If any non-null value is specified for the multiple attribute, the result will be a String[] obtained from calling getParameters() instead of getParameter().

8.6.6 The resource Tag

This tag retrieves the value of the specified web application resource and makes it available as either an InputStream or a String, depending on the value of the input attribute. If the input attribute contains any non-null value, an InputStream will be created. Otherwise, the resource will be loaded as a String.

This tag calls the getResourceAsStream() method using the name attribute. The name attribute must start with a /.

8.6.7 The write Tag

The write tag is another important tag within the Bean tag library, and it gets a great deal of use. It retrieves the value of the specified bean property and renders it to the page output as a String. The write tag uses the following rules:

• If the format attribute is specified, the value will be formatted based on the format string and the default locale. The formatKey attribute can also be used. It should specify the name of a format string from the message resource bundle.

• The formatKey attribute is used to specify a format string from the resource bundle. The specific resource bundle and locale can also be specified. If the bundle and locale are not specified, the default resource bundle and current user locale will be used.

• Otherwise, the usual toString() conversions will be applied.

The following is an example of using the write tag:

<td>Hello <bean:write name="user" property="firstName"/></td>

If the ignore attribute is set to true and the bean specified by the name and scope attributes is not found, the tag will not throw an exception. If not set, or set to false, a runtime exception will be thrown.