Download the JDK
Search the Tutorials
Hide the TOC
Trail: JavaBeans(TM)
Lesson: Using the BeanContext API
Using the BeanContext API
Overview of the BeanContext API
Bean Context #1: Containment Only
Bean Context #2: Containment and Services
AWT Containers and the BeanContextProxy Interface
Home Page > JavaBeans(TM) > Using the BeanContext API
Bean Context #1: Containment Only

> The "containment" portion of the Extensible Runtime Containment and Services Protocol is defined by the `BeanContext` interface. In its most basic form, a `BeanContext` is used to logically group a set of related java beans, bean contexts, or arbitrary objects. JavaBeans nested into a `BeanContext` are known as "child" beans. Once nested, a child bean can query its `BeanContext` for various membership information, as illustrated in the following examples.

> Here are some possible `BeanContext` containment scenarios:

> The sample code presented in this chapter uses instances of the `BeanContextSupport` helper class to provide the basic `BeanContext` functionality. A `BeanContextSupport` object is simply a concrete implementation of the `BeanContext` interface.

> With a `BeanContextSupport` instance, it is possible to:

> - Add an object, bean, or `BeanContext`: `boolean add(Object o)`
> - Remove an object, bean, or `BeanContext`: `boolean remove(Object o)`
> - Add a `BeanContextMembershipListener`: `void addBeanContextMembershipListener(BeanContextMembershipListener bcml)`
> - Remove a `BeanContextMembershipListener`: `void removeBeanContextMembershipListener(BeanContextMembershipListener bcml)`
> - Get all JavaBean or `BeanContext` instances currently nested in this `BeanContext` as an array or as an Iterator: `Object[] toArray()`, `Object[] toArray(Object[] a)`, and `Iterator iterator()`
> - Determine whether or not a specified object is currently a child of the `BeanContext`: `boolean contains(Object o)`
> - Get the number of children currently nested in this `BeanContext`: `int size()`
> - Determine whether or not the `BeanContext` currently has zero children: `boolean isEmpty()`
> - Instantiate a new JavaBean instance as a child of the target `BeanContext`: `Object instantiateChild(String beanName)`

> The following test programs, which are run from the command line, illustrate the use of these methods.

> The comments in the source code explain the purpose of each.

> File: `Example1.java`

> >     import java.beans.beancontext.*;

> >     /**
> >      * A test program that adds a bean to a beancontext, and
> >      * reports on various aspects of the context's membership state.
> >      * This program also shows that a bean's getBeanContext() method
> >      * can be called to get a reference to its enclosing context.
> >      */
> >     public class Example1 {
> >         private static BeanContextSupport context = new BeanContextSupport(); // The BeanContext
> >         private static BeanContextChildSupport bean = new BeanContextChildSupport(); // The JavaBean

> >         public static void main(String[] args) {
> >             report();

> >             // Add the bean to the context
> >             System.out.println("Adding bean to context...");
> >             context.add(bean);

> >             report();
> >         }

> >         private static void report() {
> >             // Print out a report of the context's membership state.
> >             System.out.println("=============================================");

> >             // Is the context empty?
> >             System.out.println("Is the context empty? " + context.isEmpty());

> >             // Has the context been set for the child bean?
> >             boolean result = (bean.getBeanContext()!=null);
> >             System.out.println("Does the bean have a context yet? " + result);

> >             // Number of children in the context
> >             System.out.println("Number of children in the context: " + context.size());

> >             // Is the specific bean a member of the context?
> >             System.out.println("Is the bean a member of the context? " + context.contains(bean));

> >             // Equality test
> >             if (bean.getBeanContext() != null) {
> >                 boolean isEqual = (bean.getBeanContext()==context); // true means both references point to the same object
> >                 System.out.println("Contexts are the same? " + isEqual);
> >             }
> >             System.out.println("=============================================");
> >         }
> >     }

> Output:

> >     =============================================
> >     Is the context empty? true
> >     Does the bean have a context yet? false
> >     Number of children in the context: 0
> >     Is the bean a member of the context? false
> >     =============================================
> >     Adding bean to context...
> >     =============================================
> >     Is the context empty? false
> >     Does the bean have a context yet? true
> >     Number of children in the context: 1
> >     Is the bean a member of the context? true
> >     Contexts are the same? true
> >     =============================================

> File: `Example2.java`

> >     import java.beans.beancontext.*;

> >     /**
> >      * Test program that adds 100 beans to a context,
> >      * and calls size() to report the number of beans
> >      * currently nested. Finally,
> >      * this test calls toArray() to get references to
> >      * all child beans.
> >      */
> >     public class Example2 {
> >         public static void main(String[] args) {

> >             // A BeanContext
> >             BeanContextSupport context = new BeanContextSupport();

> >             // Many JavaBeans
> >             BeanContextChildSupport[] beans = new BeanContextChildSupport[100];

> >             System.out.println("Number of children in the context: " + context.size());

> >             // Create the beans and add them to the context
> >             for (int i = 0; i < beans.length; i++) {
> >                 beans[i] = new BeanContextSupport();
> >                 context.add(beans[i]);
> >             }
> >             System.out.println("Number of children in the context: " + context.size());

> >             // Context now has 100 beans in it, get references to them all
> >             Object[] children = context.toArray();
> >             System.out.println("Number of objects retrieved from the context: " + children.length);
> >         }
> >     }

> Output:

> >     Number of children in the context: 0
> >     Number of children in the context: 100
> >     Number of objects retrieved from the context: 100

> File: `Example3.java`

> >     import java.beans.beancontext.*;
> >     import java.io.*;

> >     /**
> >      * An example of how to use the instantiateChild() convenience method
> >      * to create a bean automatically nested into a bean context.
> >      */
> >     public class Example3 {
> >         public static void main(String[] args) {
> >             BeanContextSupport context = new BeanContextSupport();
> >             System.out.println("Number of children nested into the context: " + context.size());

> >             BeanContextChildSupport child = null;
> >             try {
> >                 child = (BeanContextChildSupport)context.instantiateChild("java.beans.beancontext.BeanContextChildSupport");
> >             }
> >             catch(IOException e){
> >                 System.out.println("IOException occurred: " + e.getMessage());
> >             }
> >             catch(ClassNotFoundException e){
> >                 System.out.println("Class not found: " + e.getMessage());
> >             }
> >             System.out.println("Number of children nested into the context: " + context.size());
> >         }
> >     }

> Output:

> >     Number of children nested into the context: 0
> >     Number of children nested into the context: 1

> ### BeanContextMembershipEvent Notification

> The `BeanContext` API uses the standard Java event model to register listeners and deliver events. For an overview of this standard event model, refer to Writing Event Listeners. For details about handling specific events, see Writing Event Listeners.

> In a basic `BeanContext`, the event classes and interfaces involved are:

> - `java.beans.beancontext.BeanContextMembershipEvent`: Encapsulates the list of children added to, or removed from, the membership of a particular `BeanContext`. An instance of this event is fired whenever a successful add(), remove(), retainAll(), removeAll(), or clear() is invoked on a given `BeanContext` instance.
> - `java.beans.BeanContextMembershipListener`: Objects wishing to receive BeanContextMembershipEvents implement this interface. It defines methods `void childrenAdded(BeanContextMembershipEvent bcme)` and `void childrenRemoved(BeanContextMembershipEvent bcme)`, which are called when a child is added to or removed from a given `BeanContext` instance.

> ### BeanContextMembershipEvent Notification: Sample Code

> File: `MembershipTest.java`

> >     import java.beans.beancontext.*;

> >     /**
> >      * A simple test program to illustrate delivery
> >      * of the BeanContextMembershipEvent.
> >      */
> >     public class MembershipTest {
> >         public static void main(String[] args) {
> >             BeanContextSupport context = new BeanContextSupport(); // the context
> >             MyMembershipListener listener = new MyMembershipListener();
> >             BeanContextChildSupport bean = new BeanContextChildSupport(); // a JavaBean
> >             context.addBeanContextMembershipListener(listener); // now listening!
> >             context.add(bean);
> >             context.remove(bean);
> >         }
> >     }

> >     /**
> >      * A custom implementation of the BeanContextMembershipListener interface.
> >      */
> >     class MyMembershipListener implements BeanContextMembershipListener {
> >         public void childrenAdded(BeanContextMembershipEvent bcme) {
> >             System.out.println("Another bean has been added to the context.");
> >         }

> >         public void childrenRemoved(BeanContextMembershipEvent bcme) {
> >             System.out.println("A bean has been removed from the context.");
> >         }
> >     }

> Output:

> >     Another bean has been added to the context.
> >     A bean has been removed from the context.

> ### The same example, implemented using an anonymous inner class

> >     import java.beans.beancontext.*;

> >     public class MembershipTest {
> >         public static void main(String[] args) {
> >             BeanContextSupport context = new BeanContextSupport();
> >             context.addBeanContextMembershipListener(new BeanContextMembershipListener() {
> >                 public void childrenAdded(BeanContextMembershipEvent bcme) {
> >                     System.out.println("Another bean has been added to the context.");
> >                 }

> >                 public void childrenRemoved(BeanContextMembershipEvent bcme) {
> >                     System.out.println("A bean has been removed from the context.");
> >                 }
> >             });
> >             BeanContextChildSupport bean = new BeanContextChildSupport();
> >             context.add(bean);
> >             context.remove(bean);
> >         }
> >     }

> Output:

> >     Another bean has been added to the context.
> >     A bean has been removed from the context.

Previous page: Overview of the BeanContext API
Next page: Bean Context #2: Containment and Services