<jsp:useBean>

Locates or instantiates a Bean with a specific name and scope.

JSP Syntax

<jsp:useBean
        id="beanInstanceName"
        scope="page | request | session | application"
        {
            class="package.class" |
            type="package.class" |
            class="package.class" type="package.class" |
            beanName="{package.class | <%= expression %>}" type="package.class"
        }
        {
            /> |
            > other elements </jsp:useBean>
        }

Examples

<jsp:useBean id="cart" scope="session" class="session.Carts" />
<jsp:setProperty name="cart" property="*" />

<jsp:useBean id="checking" scope="session" class="bank.Checking" >
<jsp:setProperty name="checking" property="balance" value="0.0" />
</jsp:useBean>

Description

The <jsp:useBean> element locates or instantiates a JavaBeans component. <jsp:useBean> first attempts to locate an instance of the Bean. If the Bean does not exist, <jsp:useBean> instantiates it from a class or serialized template.

To locate or instantiate the Bean, <jsp:useBean> takes the following steps, in this order:

1. Attempts to locate a Bean with the scope and name you specify.
2. Defines an object reference variable with the name you specify.
3. If it finds the Bean, stores a reference to it in the variable. If you specified type, gives the Bean that type.
4. If it does not find the Bean, instantiates it from the class you specify, storing a reference to it in the new variable. If the class name represents a serialized template, the Bean is instantiated by java.beans.Beans.instantiate.
5. If <jsp:useBean> has instantiated (rather than located) the Bean, and if it has body tags or elements (between <jsp:useBean> and </jsp:useBean>), executes the body tags.

The body of a <jsp:useBean> element often contains a <jsp:setProperty> element that sets property values in the Bean. As described in Step 5, the body tags are only processed if <jsp:useBean> instantiates the Bean. If the Bean already exists and <jsp:useBean> locates it, the body tags have no effect.

In this release, you can use a <jsp:useBean> element to locate or instantiate a Bean, but not an enterprise bean. To create enterprise beans, you can write a <jsp:useBean> element that calls a Bean that in turn calls the enterprise bean, or you can write a custom tag that calls an enterprise bean directly.

Attributes and Usage

• id="beanInstanceName"

  A variable that identifies the Bean in the scope you specify. You can use the variable name in expressions or scriptlets in the JSP file.

  The name is case sensitive and must conform to the naming conventions of the scripting language used in the JSP page. If you use the Java programming language, the conventions in the Java Language Specification. If the Bean has already been created by another <jsp:useBean> element, the value of id must match the value of id used in the original <jsp:useBean> element.

• scope="page | request | session | application"

  The scope in which the Bean exists and the variable named in id is available. The default value is page. The meanings of the different scopes are shown below:

  • page - You can use the Bean within the JSP page with the <jsp:useBean> element or any of the page's static include files, until the page sends a response back to the client or forwards a request to another file.

  • request - You can use the Bean from any JSP page processing the same request, until a JSP page sends a response to the client or forwards the request to another file. You can use the request object to access the Bean, for example, request.getAttribute(beanInstanceName).

  • session - You can use the Bean from any JSP page in the same session as the JSP page that created the Bean. The Bean exists across the entire session, and any page that participates in the session can use it. The page in which you create the Bean must have a <%@ page %> directive with session=true.

  • application - You can use the Bean from any JSP page in the same application as the JSP page that created the Bean. The Bean exists across an entire JSP application, and any page in the application can use the Bean.

• class="package.class"

  Instantiates a Bean from a class, using the new keyword and the class constructor. The class must not be abstract and must have a public, no-argument constructor. The package and class name are case sensitive.

• type="package.class"

  If the Bean already exists in the scope, gives the Bean a data type other than the class from which it was instantiated. If you use type without class or beanName, no Bean is instantiated. The package and class name are case sensitive.

• class="package.class" type="package.class"

  Instantiates a Bean from the class named in class and assigns the Bean the data type you specify in type. The value of type can be the same as class, a superclass of class, or an interface implemented by class.

  The class you specify in class must not be abstract and must have a public, no-argument constructor. The package and class names you use with both class and type are case sensitive.

• beanName="{package.class | <%= expression %>}" type="package.class"

  Instantiates a Bean from either a class or a serialized template, using the java.beans.Beans.instantiate method, and gives the Bean the type specified in type. The Beans.instantiate method checks whether a name represents a class or a serialized template. If the Bean is serialized, Beans.instantiate reads the serialized form (with a name like package.class.ser) using a class loader. For more information, see the JavaBeans API Specification.

  The value of beanName is either a package and class name or an Expression that evaluates to a package and class name, and is passed to Beans.instantiate. The value of type can be the same as beanName, a superclass of beanName, or an interface implemented by beanName.

  The package and class names you use with both beanName and type are case sensitive.

See Also

• <jsp:setProperty>
• <jsp:getProperty>
• Javadoc API reference for java.beans.Beans
• JavaBeans API Specification