The BDK BeanBox

[source: http://java.sun.com/beans/software/beanbox.html#top]

The BeanBox is a very simple test container. It allows you to try out the BDK example beans and your own beans by providing the following functionality:

Note that the BeanBox is intended as a test container and as a reference base, but it is not intended as a serious application development tool.

It must be emphasized that the BeanBox is merely one rather simplistic way of representing beans to humans. All bean-based tools should use the same standard JavaBeans APIs, but can provide very different ways of visually representing beans and different styles for manipulating and connecting beans.

Running the BeanBox

To start the BeanBox, cd to the beanbox directory and type "run". Note that you need to have the JDK "bin" directory in your path and you should be using JDK 1.1 or later.

The BeanBox comes up as three separate windows.


Adding a bean to the Composition window

To add a bean to the Composition window: The chosen bean will appear centered at the new location and will be the current selected bean.


Selecting a bean in the Composition window

The currently selected bean is marked with a black-and-white hashed boundary. The PropertySheet window shows its properties and the "edit" menu of the Composition window provides access to its events, bound properties, etc.

To select a bean you must click the mouse just outside of the bean in the boundary area where the black-and-white hashed boundary will appear.

Some beans (such as the ExplicitButton or the Juggler) will allow you to select the bean by clicking anywhere in the bean, but some other beans (such as the Molecule or the ChangeReporter) won't notice a click on the bean itself, and require you to click in the surrounding border area. This behavior reflects problems with mouse event processing which should be fixed in the final version of the BDK.


Moving or resizing a bean

You can move the currently selected bean by clicking the mouse on one of the black-and-white hashed borders, holding the mouse down, and dragging the bean.

Some beans, such as the BeanBox bean or the ExplicitButton, also allow themselves to be resized. You can try to resize the currently selected bean by clicking on one of the corners of the black-and-white boundary and holding the mouse down and stretching the corner out.


Editing a bean's properties

The currently selected bean has its properties displayed in the PropertySheet window.

For each editable property the PropertySheet window shows the name of the property and its current value. The current value may be shown as:

So for example, if you select an OurButton bean you can see eight different property values. You can edit the "label" property by simply typing in its associated text field. You can edit the "debug" property by clicking on the associated choice menu and selecting "True" instead of "False". You can edit the "font" property by clicking on the displayed sample text, which brings up a small dialog window that lets you use choice menus to select the font name, font style, and point size. Note that this is a modal dialog and you must click on "done" before you can continue.


Using a bean customizer

If the currently selected bean has a customizer, then the "edit" menu in the Composition window will include a "Customize..." entry. If you select that entry, then a dialog window will come up with the bean's customizer.

Two of the example beans have a customizer. The ExplicitButton has a trivial customizer that simply lets you set the button's label. The JDBC SELECT bean has a much more interesting customizer that will try to connect through JDBC to a local database to help you create a SQL query.


Connecting an event handler

The BeanBox allows you to connect an event from the currently selected bean to a target event handling method on any other bean.

The "edit" menu in the Composition window has an "events" menu that has a sub-menu for all the different kinds of events that the currently selected bean fires. These events are grouped and named according to their EventListener interfaces. For example, if you select an ExplicitButton bean you will see that it has two EventListener interfaces "button push" and "bound property change", each of which contain a single event.

If you select one of the events from this menu, the BeanBox will start drawing a "rubber band" line from the source bean. You can then click on the border of the target bean to which you want the event delivered. [Note that as with selection, you may need to click on the target bean's border rather than on the bean itself.]

The BeanBox will then check for methods in the target bean that accept the same EventObject argument that is fired by the source event. You will then be offered a dialog box to chose which matching method you would like to have called when the source event is fired. After you select a method, the BeanBox will generate, compile, and load an event adaptor class to connect the source bean's event to the target bean's event handler method.

Try this out by connecting an ExplicitButton's button push event to a Juggler's) start method. Now when you push the button the Juggler will start juggling.

Note that this particular visual style for connecting events and handlers isn't part of the JavaBeans architecture, nor is the associated search for a handler method with a particular method signature. Professional application development environments may do things like providing users with a handler method template and allowing the user to type in Java code for an event handler.

Connecting a bound property

The BeanBox allows you to connect a bound property from a source bean to a target property on some other bean. Then when the bound property on the source bean is changed, the associated target property is also automatically updated.

If the currently selected bean supports bound properties, then the "edit" menu will include a "Bind property..." item. If you chose this menu item, then the BeanBox will bring up a dialog showing the bound properties available on the source bean. You select the source property and press "OK". The BeanBox will draw a "rubber band" line and wait for you to click on the border of the target bean to which you want the property bound. [Note that as with selection, you may need to click on the target bean's border rather than on the bean itself.]

The BeanBox will bring up a dialog listing the available properties on the target bean that match the type of the source property. You select a target property and press "OK".

Now when the property on the source bean is changed, the property on the target bean will also be updated.

Try this out by connecting the background colors on two ExplicitButtons and then use the PropertySheet to change the background color of the source bean.


Saving and restoring beans

Once you have set up some beans in the BeanBox, you can use the "File" menu's "Save.." sub-menu to store the current state of the BeanBox.

This uses Java Object Serialization to automagically store away all the state of the beans into a named file.

You can then use the "File" menu's "Clear" item to discard the current set of beans and use the "Load..." item to read in and recreate all the serialized beans.

This provides a simple way to test the use of serialization with your beans.


Making applets from beans

You can also set up some beans in the BeanBox and then use the "File" menu's "MakeApplet" item to create an applet that behaves like this set of beans. The resulting applet uses Java Object Serialization to record the state of any beans effectively containing hidden-state, otherwise, it calls Beans.instantiate() to create a new bean. Only bean properties that have changed during the BeanBox session in which the applet was generated are restored.

Invoking the MakeApplet item will create a JAR file that contains the serialized data (if any) plus hookup and other classes. The action will also create: a test HTML file that uses that JAR file (plus any other JAR files containing the buttons used in the applet), a subdirectory with Java source files plus makefiles, and a "readme" file with more details.

The generated applet can be used in any fully compliant JDK1.1 browser. A simple test platform is the appletviewer from the JDK1.1 distributions. Another fully compliant browser is the HotJava Browser.

The preview2 release of Internet Explorer 4.0 has a couple of problems:

The generated applet will not work in the 4.0 and 4.01 versions of Netscape Communicator.


Getting an introspection report on a bean

If you want to see all the properties, methods, and events that the Beans introspector has found on a selected bean, you can use the BeanBox's "report" menu item under the "edit" menu.

This generates a summary report to standard output of the introspection information for the selected bean.


Adding your bean to the BeanBox

When the BeanBox starts, it loads all the JAR files that it finds in the "jars" directory. The BeanBox uses the manifest file in each JAR file to identify any bean classes in the JAR file, and adds those beans to the ToolBox palette window.

To add your bean to the BeanBox, you must wrap it in a JAR file which contains a suitable manifest file describing the bean. Take a look at one of the example bean makefiles such as demo\juggler.mk (for Windows nmake users) or demo/juggler.gmk (for Unix gnumake users) to see how to create a manifest file and a JAR file.

Once you have a suitable JAR file, simply add it to the "jars" directory and restart the BeanBox, or load the JAR directly using the "LoadJar..." item in the "File" menu.


Java, JavaBeans, and JavaSoft are trademarks of Sun Microsystems Inc.