JSP.2.13 Standard Actions

The JSP 1.1 specification defines some standard action types that are always available, regardless of the version of the JSP container or web server the developer uses. The standard action types are in addition to any custom types specific to a given JSP container implementation.

JSP.2.13.1 <jsp:useBean>

A jsp:useBean action associates an instance of a Java programming language object defined within a given scope available with a given id via a newly declared scripting variable of the same id .

The jsp:useBean action is quite flexible; its exact semantics depends on the attributes given. The basic semantic tries to find an existing object using id and scope ; if it is not found it will attempt to create the object using the other attributes. It is also possible to use this action only to give a local name to an object defined elsewhere, as in another JSP page or in a servlet; this can be done by using the type attribute and not providing class or beanName attributes.

At least one of type and class must be present, and it is not valid to provide both class and beanName . If type and class are present, class must be assignable (in the Java platform sense) to type; failure to do so is a translation-time error.

The attribute beanName is the name of a bean, as specified in the JavaBeans specification for an argument to the instantiate() method in java.beans.Beans . That is, it is of the form "a.b.c," which may be either a class or the name of a resource of the form "a/b/c.ser" that will be resolved in the current ClassLoader . If this is not true, a request-time exception, as indicated in the semantics of instantiate() , will be raised. The value of this attribute can be a request-time attribute expression.

The actions performed are:

1. Attempt to locate an object based on the attribute values ( id, scope ). The inspection is done appropriately synchronized per scope namespace to avoid non-deterministic behavior.

2. Define a scripting language variable with the given id in the current lexical scope of the scripting language of the specified type (if given) or class (if type is not given).

3. If the object is found, the variable's value is initialized with a reference to the located object, cast to the specified type . If the cast fails, a java.lang.ClassCastException shall occur. This completes the processing of this useBean action.

   If the jsp:useBean element had a non-empty body, it is ignored. This completes the processing of this useBean action.

4. If the object is not found in the specified scope and neither class nor beanName is given, a java.lang.InstantiationException shall occur. This completes the processing of this useBean action.

5. If the object is not found in the specified scope, and the class specified names a non-abstract class that defines a public no-args constructor, then that class is instantiated , and the new object reference is associated with the scripting variable and with the specified name in the specified scope using the appropriate scope-dependent association mechanism (see PageContext). After this, step 7 is performed.

   If the object is not found, and the class is either abstract, an interface , or no public no-args constructor is defined therein, then a java.lang.InstantiationException shall occur. This completes the processing of this useBean action.

6. If the object is not found in the specified scope, and beanName is given, then the method instantiate() of java.beans.Beans will be invoked with the ClassLoader of the servlet object 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 using the appropriate scope-dependent association mechanism (see PageContext). After this, step 7 is performed.

7. If the jsp:useBean element has a non-empty body, the body is processed . The 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 will be passed through to the out stream; scriptlets and action tags will be evaluated.

   A common use of a non-empty body is to complete initializing the created instance; in that case the body will likely contain jsp:setProperty actions and scriptlets. This completes the processing of this useBean action.

Examples

In the following example, a bean with name "connection" of type " com.myco.myapp.Connection " is available after this element, either because it was already created or because it is newly created.

 <jsp:useBean id="connection" class="com.myco.myapp.Connection" /> 

In this next example, the timeout property is set to 33 if the bean was instantiated.

 <jsp:useBean id="connection" class="com.myco.myapp.Connection">       <jsp:setProperty name="connection" property="timeout"   value="33">  </jsp:useBean> 

In our final example, the object should have been present in the session. If so, it is given the local name wombat with WombatType . A ClassCastException may be raised if the object is of the wrong class, and an InstantiationException may be raised if the object is not defined.

 <jsp:useBean id="wombat" type="my.WombatType" scope="session"/> 

JSP.2.13.1.1 Syntax

This action may or may not have a body. If the action has no body, it is of the form:

 <jsp:useBean id="  name  " scope="pagerequestsessionapplication"  typeSpec  />  typeSpec  ::= class="  className  "                class="  className  " type="  typeName  "                type="  typeName  " class="  className  "                beanName="  beanName  " type="  typeName  "                type="  typeName  " beanName="  beanName  "                type="  typeName  " 

If the action has a body, it is of the form:

 <jsp:useBean id="  name  " scope="pagerequestsessionapplication"  typeSpec  >  body  </jsp:useBean> 

In this case, the body will be invoked if the bean denoted by the action is created. Typically, the body will contain either scriptlets or jsp:setProperty tags that will be used to modify the newly created object, but the content of the body is not restricted.

The <jsp:useBean> tag has the attributes in Table JSP.2-7.

Table JSP.2-7. Attributes of the jsp:useBean Tag

id	The name used to identify the object instance in the specified scope's namespace, and also the scripting variable name declared and initialized with that object reference. The name specified is case sensitive and shall conform to the current scripting language variable-naming conventions.
scope	The scope within which the reference is available. The default value is page . See the description of the scope attribute defined earlier herein.
class	The fully qualified name of the class that defines the implementation of the object. The class name is case sensitive. If the class and beanName attributes are not specified, the object must be present in the given scope.
beanName	The name of a bean, as expected by the instantiate() method of the java.beans.Beans class. This attribute can accept a request-time attribute expression as a value.
type	If specified, it defines the type of the scripting variable defined. This allows the type of the scripting variable to be distinct from, but related to, that of the implementation class specified. The type is required to be either the class itself, a superclass of the class, or an interface implemented by the class specified. The object referenced is required to be of this type, otherwise a java.lang.ClassCastException shall occur at request time when the assignment of the object referenced to the scripting variable is attempted. If unspecified, the value is the same as the value of the class attribute.

JSP.2.13.2 <jsp:setProperty>

The jsp:setProperty action sets the value of properties in a bean. The name attribute denotes an object that must be defined before this action appears.

There are two variants of the jsp:setProperty action. Both variants set the values of one or more properties in the bean based on the type of the properties. The usual bean introspection is done to discover what properties are present and, for each, its name, whether it is simple or indexed, its type, and setter and getter methods .

Properties in a bean can be set from one or more parameters in the request object, from a String constant, or from a computed request-time expression. Simple and indexed properties can be set using setProperty . The only types of properties that can be assigned to from String constants and request parameter values are those listed in Table JSP.2-8; the conversion applied is that shown in the table. Request-time expressions can be assigned to properties of any type; no automatic conversions will be performed.

When assigning values to indexed properties the value must be an array; the rules described in the previous paragraph apply to the elements.

A conversion failure leads to an error; the error may be at translation or at request-time.

Table JSP.2-8. Valid Assignments in jsp:setProperty

Property Type	Conversion on String Value
boolean or Boolean	As indicated in java.lang.Boolean.valueOf(String)
byte or Byte	As indicated in java.lang.Byte.valueOf(String)
char or Character	As indicated in java.lang.Character.valueOf(String)
double or Double	As indicated in java.lang.Double.valueOf(String)
int or Integer	As indicated in java.lang.Integer.valueOf(String)
float or Float	As indicated in java.lang.Float.valueOf(String)
long or Long	As indicated in java.lang.Long.valueOf(String)

Examples

The following two elements set a value from the request parameter values.

 <jsp:setProperty name="request" property="*" />  <jsp:setProperty name="user" property="user" param="username" /> 

The following element sets a property from a value

 <jsp:setProperty name="results" property="row" value="<%= i+1 %>" /> 

JSP.2.13.2.1 Syntax

 <jsp:setProperty name="  beanName  "  prop_expr  />  prop_expr  ::=    property="*"                      property="  propertyName  "                    property="  propertyName  " param="  parameterName  "                   property="  propertyName  " value="  propertyValue  "  propertyValue  ::=  string  

The value propertyValue can also be a request-time attribute value, as described in Section JSP.2.12.1, "Request-Time Attribute Values."

  propertyValue  ::=  expr_scriptlet   [2]  

^[2] See syntax for expression scriptlet "<%= ... %>."

The <jsp:setProperty> element has the attributes in Table JSP.2-9.

Table JSP.2-9. Attributes of the jsp:setProperty Tag

name	The name of a bean instance defined by a <jsp:useBean> element or some other element. The bean instance must contain the property you want to set. The defining element (in JSP 1.1 only a <jsp:useBean> element) must appear before the <jsp:setProperty> element in the same file.
property	The name of the bean property whose value you want to set. If you set propertyName to * then the tag will iterate over the current ServletRequest parameters, matching parameter names and value type(s) to property names and setter method type(s), setting each matched property to the value of the matching parameter. If a parameter has a value of "" , the corresponding property is not modified.
param	The name of the request parameter whose value you want to give to a bean property. The name of the request parameter usually comes from a web form. If you omit param , the request parameter name is assumed to be the same as the bean property name. If the param is not set in the Request object, or if it has the value of "" , the jsp:setProperty element has no effect (a noop). An action may not have both param and value attributes.
value	The value to assign to the given property. This attribute can accept a request-time attribute expression as a value. An action may not have both param and value attributes.

JSP.2.13.3 <jsp:getProperty>

An <jsp:getProperty> action places the value of a bean instance property, converted to a String , into the implicit out object, from which you can display the value as output. The bean instance must be defined as indicated in the name attribute before this point in the page (usually via a useBean action).

The conversion to String is done as in the println() methods; i.e., the toString() method of the object is used for Object instances, and the primitive types are converted directly.

If the object is not found, a request-time exception is raised.

Examples

 <jsp:getProperty name="user" property="name" /> 

JSP.2.13.3.1 Syntax

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

The attributes are in Table JSP.2-10

Table JSP.2-10. Attributes of the jsp:getProperty Tag

name	The name of the object instance from which the property is obtained.
property	Names the property to get.

JSP.2.13.4 <jsp:include>

A <jsp:include .../> element provides for the inclusion of static and dynamic resources in the same context as the current page. See Table JSP.E2-2 for a summary of include facilities.

The resource is specified using a relative URLspec that is interpreted in the context of the web server (i.e., it is mapped). See Section JSP.2.5.2.

An included page has access only to the JspWriter object and it cannot set headers. This precludes invoking methods like setCookie (). A request-time Exception will be raised if this constraint is not satisfied. The constraint is equivalent to the one imposed on the include () method of the RequestDispatcher class.

A jsp:include action may have jsp:param subelements that can provide values for some parameters in the request to be used for the inclusion.

Request processing resumes in the calling JSP page, once the inclusion is completed.

If the page output is buffered then the buffer is flushed prior to the inclusion. See Section JSP.B.4 for an implementation note. See Section JSP.5.4.5 for limitations on flushing when out is not the top-level JspWriter .

Examples

 <jsp:include page="/templates/copyright.html"/> 

JSP.2.13.4.1 Syntax

 <jsp:include page="  urlSpec  " flush="true"/> 

and

 <jsp:include page="  urlSpec  " flush="true">       { <jsp:param .... /> }*  </jsp:include> 

The first syntax just does a request-time inclusion. In the second case, the values in the param subelements are used to augment the request for the purposes of the inclusion.

The valid attributes are given in Table JSP.2-11.

Table JSP.2-11. Attributes of the jsp:include Tag

page	The URL is a relative urlSpec as in Section JSP.2.5.2. Accepts a request-time attribute value (which must evaluate to a string that is a relative URL specification).
flush	Mandatory boolean attribute. If the value is " true ," the buffer is flushed. A " false " value is not valid in JSP 1.1.

JSP.2.13.5 <jsp:forward>

A <jsp:forward page="urlSpec" /> element allows the runtime dispatch of the current request to a static resource, a JSP page or a Java servlet class in the same context as the current page. A jsp:forward effectively terminates the execution of the current page. The relative urlSpec is as in Section JSP.2.5.2.

The request object will be adjusted according to the value of the page attribute.

A jsp:forward action may have jsp:param subelements that can provide values for some parameters in the request to be used for the forwarding.

If the page output is buffered, then the buffer is cleared prior to forwarding.

If the page output was unbuffered and anything has been written to it, an attempt to forward the request will result in an IllegalStateException .

Examples

The following element might be used to forward to a static page based on some dynamic condition.

 <% String whereTo = "/templates/"+someValue; %>  <jsp:forward page='<%= whereTo %>' /> 

JSP.2.13.5.1 Syntax

 <jsp:forward page="  relativeURLspec  " /> 

and

 <jsp:forward page="  urlSpec  ">       { <jsp:param .... /> }*  </jsp:forward> 

This tag allows the page author to cause the current request processing to be effected by the specified attributes as in Table JSP.2-12

Table JSP.2-12. Attributes of the jsp:forward Tag

page

The URL is a relative urlSpec is as in Section JSP.2.5.2.

Accepts a request-time attribute value (which must evaluate to a string that is a relative URL specification).

JSP.2.13.6 <jsp:param>

The jsp:param element is used to provide key/value information. This element is used in the jsp:include , jsp:forward , and jsp:plugin elements.

When doing jsp:include or jsp:forward , the included page or forwarded page will see the original request object, with the original parameters augmented with the new parameters, with new values taking precedence over existing values when applicable . The scope of the new parameters is the jsp:include or jsp:forward call; i.e., in the case of a jsp:include the new parameters (and values) will not apply after the include. This is the same behavior as in the ServletRequest include and forward methods (see Section SRV.8.1.1 in the Servlet 2.2 specification).

For example, if the request has a parameter A=foo and a parameter A=bar is specified for forward, the forwarded request shall have A=bar,foo . Note that the new param has precedence.

JSP.2.13.6.1 Syntax

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

This action has two mandatory attributes: name and value . name indicates the name of the parameter; value , which may be a request-time expression, indicates its value.

JSP.2.13.7 <jsp:plugin>

The plugin action enables a JSP page author to generate HTML that contains the appropriate client browser-dependent constructs ( <object> or <embed> ) that will result in the download of the Java plugin software (if required) and subsequent execution of the applet or JavaBeans component specified therein.

The <jsp:plugin> tag is replaced by either an <object> or <embed> tag, as appropriate for the requesting user agent, and emitted into the output stream of the response. The attributes of the <jsp:plugin> tag provide configuration data for the presentation of the element, as indicated in Table JSP.2-13.

Table JSP.2-13. Attributes of the jsp:plugin Tag

type	Identifies the type of the component; a bean, or an applet.
code	As defined by HTML spec
codebase	As defined by HTML spec
align	As defined by HTML spec
archive	As defined by HTML spec
height	As defined by HTML spec
hspace	As defined by HTML spec
jreversion	Identifies the spec version number of the JRE the component requires in order to operate ; the default is "1.1."
name	As defined by HTML spec
vspace	As defined by HTML spec
title	As defined by HTML spec
width	As defined by HTML spec
nspluginurl	URL where JRE plugin can be downloaded for Netscape Navigator, default is implementation defined.
iepluginurl	URL where JRE plugin can be downloaded for IE, default is implementation defined.

The <jsp:param> elements indicate the parameters to the applet or JavaBeans component.

The <jsp:fallback> element indicates the content to be used by the client browser if the plugin cannot be started (either because <object> or <embed> is not supported by the client browser or due to some other problem). If the plugin can start but the applet or JavaBeans component cannot be found or started, a plugin specific message will be presented to the user, most likely a popup window reporting a ClassNotFoundException .

Examples

 <jsp:plugin type=applet code="Molecule.class" codebase="/html" >         <jsp:params>                    <jsp:param                        name="molecule"                        value="molecules/benzene.mol"/>         </jsp:params>         <jsp:fallback>                    <p> unable to start plugin </p>         </jsp:fallback>  </jsp:plugin> 

JSP.2.13.7.1 Syntax

 <jsp:plugintype="beanapplet"         code="  objectCode  "         codebase="  objectCodebase  "         { align="  alignment  "              }         { archive="  archiveList  "          }         { height="  height  "                }         { hspace="  hspace  "                }         { jreversion="  jreversion  "        }         { name="  componentName  "           }         { vspace="  vspace  "                }         { width="  width  "                  }         { nspluginurl="  url  "              }         { iepluginurl="  url  "              }>         { <jsp:params>              { <jsp:param name="  paramName  " value="  paramValue  " /> }+          </jsp:params> }         { <jsp:fallback>  arbitrary_text  </jsp:fallback> }  </jsp:plugin>