<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" ]|	
   beanName="{package.class | <%= expression %>}" 	
      type="package.class" | 	
   type="package.class"	
}	
{ /> | > other elements </jsp:useBean> }

XML Syntax

<jsp:useBean id="beanInstanceName"	
   scope="page|request|session|application"	
{	
   class="package.class"  [ type="package.class" ]  |	
   beanName="{package.class | %= expression %}"	
      type="package.class" |	
   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.

You can use a <jsp:useBean> element to locate or instantiate a JavaBeans component , 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 page.

  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 resource.

  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 resource. 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. The value of type must be a superclass of class or an interface implemented by class.

  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 a class, a serialized template, or an expression that evaluates to a class or serialized template. When you use beanName, the bean is instantiated by the java.beans.Beans.instantiate method. The Beans.instantiate method checks whether the package and class you specify represents a class or a serialized template. If they represent a serialized template, Beans.instantiate reads the serialized form (which has a name like package.class.ser) using a class loader.

  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>
• http://java.sun.com/products/javabeans/docs/