The Java EE 5 Tutorial

Using the managed-bean Element

You create a bean using a managed-bean element, which represents an instance of a bean class that must exist in the application. At runtime, the JavaServer Faces implementation processes the managed-bean element. If a page references the bean, the JavaServer Faces implementation instantiates the bean as specified by the element configuration if no instance exists.

Here is an example managed bean configuration from the Duke’s Bookstore application:

<managed-bean>
    <managed-bean-name> NA </managed-bean-name>
        <managed-bean-class>
             com.sun.bookstore6.model.ImageArea
         </managed-bean-class>
        <managed-bean-scope> application </managed-bean-scope>
        <managed-property>
            <property-name>shape</property-name>
            <value>poly</value>
        </managed-property>
        ...
    </managed-bean-name>
</managed-bean>

    Using NetBeans IDE, you can add a managed bean declaration by doing the following:

  1. After opening your project in NetBeans IDE, expand the project node in the Projects pane.

  2. Expand the Web Pages and WEB-INF nodes of the project node.

  3. Double-click faces-config.xml.

  4. After faces-config.xml opens in the editor pane, right-click in the editor pane.

  5. Select JavaServer Faces -> Add Managed Bean.

  6. In the Add Managed Bean dialog:

    1. Enter the display name of the bean in the Bean Name field.

    2. Click Browse to locate the bean’s class.

  7. In the Browse Class dialog:

    1. Start typing the name of the class you are looking for in the Class Name field. While you are typing, the dialog will show the matching classes.

    2. Select the class from the Matching Classes box.

    3. Click OK.

  8. In the Add Managed Bean dialog:

    1. Select the bean’s scope from the Scope menu.

    2. Click Add.

  9. In the Projects tab, right-click the bookstore1 project, and select Undeploy and Deploy.

The preceding steps will add the managed-bean element and three elements inside of it: a managed-bean-name element, a managed-bean-class element and a managed-bean-scope element. You will need to edit the XML of the configuration file directly to further configure this managed bean.

The managed-bean-name element defines the key under which the bean will be stored in a scope. For a component’s value to map to this bean, the component tag’s value attribute must match the managed-bean-name up to the first period. For example, this value expression maps to the shape property of the ImageArea instance, NA:

value="#{NA.shape}"

The part before the period (.) matches the managed-bean-name of ImageArea. Adding UI Components to a Page Using the HTML Component Tags has more examples of using the value attribute to bind components to bean properties.

The managed-bean-class element defines the fully qualified name of the JavaBeans component class used to instantiate the bean. It is the application developer’s responsibility to ensure that the class complies with the configuration of the bean in the application configuration resource file. This includes making sure that the types of the properties in the bean match those configured for the bean in the configuration file.

The managed-bean-scope element defines the scope in which the bean will be stored. The four acceptable scopes are none, request, session, or application. If you define the bean with a none scope, the bean is instantiated anew each time it is referenced, and so it does not get saved in any scope. One reason to use a scope of none is that a managed bean references another managed bean. The second bean should be in none scope if it is supposed to be created only when it is referenced. See Initializing Managed Bean Properties for an example of initializing a managed bean property.

If you are configuring a backing bean that is referenced by a component tag’s binding attribute, you should define the bean with a request scope. If you placed the bean in session or application scope instead, the bean would need to take precautions to ensure thread safety because UIComponent instances depend on running inside of a single thread.

The managed-bean element can contain zero or more managed-property elements, each corresponding to a property defined in the bean class. These elements are used to initialize the values of the bean properties. If you don’t want a particular property initialized with a value when the bean is instantiated, do not include a managed-property definition for it in your application configuration resource file.

If a managed-bean element does not contain other managed-bean elements, it can contain one map-entries element or list-entries element. The map-entries element configures a set of beans that are instances of Map. The list-entries element configures a set of beans that are instances of List.

To map to a property defined by a managed-property element, you must ensure that the part of a component tag’s value expression after the period matches the managed-property element’s property-name element. In the earlier example, the shape property is initialized with the value poly. The next section explains in more detail how to use the managed-property element.