Bean Extender Guide to Features


Assembly Surface

The Assembly Surface tool provides an interface to allow beans to be assembled and published as new beans. The supported views are:
Beans This view displays a collection of known beans within selected repositories.
Contents This view displays the beans currently being assembled within the Assembly Surface tool.
Customizer This view displays the customizer for the currently selected bean.
Dips This view allows for the inspection, addition, removal, and registration of dips and dippable beans.
Event Connection This view allows you to wire beans together by associating an event generated by a source bean with an action or method defined in a target bean.
Network Deployment This view allows you to access network deployment warehouses and catalogs for deploying Java components, and accessing deployed components, within an enterprise intranet environment.
Layout This view allows you to lay out all AWT-based beans you add to the Assembly Surface.
Log This view displays informational and error messages that occur during the process of creating a bean.
Properties This view allows you to modify any of the public properties of the currently selected bean.
Publish These views (Publish and Publish BeanInfo) allow you to define the interface and explicit bean information for the assembled bean.
Scripting This view allows you to attach Java or NetRexx code to an event listener method.
Source This view allows you to view the source of the bean being assembled.

The following graphic shows an example Assembly Surface.


* Figure sembly1 not displayed.

The Assembly Surface has the following rows of controls:

Using the Assembly Surface

To build a new bean by assembling one or more existing beans, do the following:

  1. Start the Assembly Surface tool by running the command:
    java com.ibm.beans.tools.assembly.AssemblySurfaceMain
    

  2. Select the Beans item from the View menu to open the Beans view, if the Beans tab is not displayed.

  3. Select the set of repositories containing the beans you want to use by clicking on the Add file repositories... button for beans stored in a JAR or zip file or the Add directory repository... button for beans stored as individual files in a directory.

  4. Select each bean you want to include as part of your new bean, and click on the Add beans button. Each selected bean is displayed in the Contents view. If you want, you can add a bean multiple times to create multiple copies of the bean on the Assembly Surface.

  5. When you finish, you can either close the Beans view or leave it open to add more beans to the assembly. You can close any open view by selecting the view from the View menu or by right clicking on its folder tab and selecting the Close viewmenu item.

When you have one or more beans added to the Assembly Surface, you can assemble them into a new composite bean. To assemble beans, select one or more views from the View menu to open the corresponding Assembly Surface tools. Any options a view provides can be selected from the Options item for that view.

When you finish assembling your new bean using the various views, you can create a finished bean. To generate the new bean, do the following:

  1. Type the desired class name, package name, and destination repository location in the fields provided at the top of the Assembly Surface tool. If necessary, you can change the name in the provided parent class field. The parent class field is called the Extends field.

  2. Click on the Generate button.

The new bean with the specified class and package name is created in the selected repository. If an error occurs during the generating process, an error message is displayed on the status line. If you are not sure of the cause of the error, you can open the Source view to see whether error messages are in the source code. If the source code contains error messages, correct the problem causing the error, and click on the Generate button.

You can save the current state of your work by selecting the Save or Save as item from the File menu. Regardless of whether you save the current state of the Assembly Surface, the Assembly surface automatically saves the current state in a special file each time you exit the Assembly Surface. You can restore this state the next time you start the Assembly Surface by clicking on the Open last Session item from the File menu.

If you want, you can have the generation process save the information used to construct the bean as part of the bean. This modification allows you and users of your bean to browse or edit your bean after assembly using the data stored in the bean repository. To enable this capability, ensure that there is a check in the Edit data check box prior to generating the bean. This check box is located near the top of the Assembly Surface.

Using the Assembly Surface User Interface

The Assembly Surface User Interface consists of a number of different views. However, each view shares common features with the other views. You can customize these common features to suit your personal preferences. For information on the specific contents of each view, see "Using the Assembly Surface Views".

Each view in the Assembly Surface User Interface is represented by a tab in a notebook. The Assembly Surface contains three notebooks, arranged horizontally in the Assembly Surface window. The views that you have opened when you exit the Assembly Surface are saved. The next time you invoke the Assembly Surface, these views are restored.

If you do not like the organization of notebook tabs, you have the option of creating a separate window for any tab. To create a new window for any view represented by a notebook tab, right-click on the tab and select the Move view to window item from the pop-up menu. This new view window is displayed at the exact size and in the exact location as the original window. You can move and size this new window. The size and placement of this window is remembered across all invocations of the Assembly Surface. Therefore, future invocations of the Assembly Surface will display your window preferences at the sizes and locations where you last left them.

If you do not like the window-view representation and want to return to the notebook style, you can change the view window back to a notebook tab. To change a view window back to a tab:

  1. Right-click on the tab for the view.
  2. Click on the Move view to tab item from the pop-up menu.

Although you changed a notebook tab to its window-view representation, the tab remains part of the original notebook. If you click on a tab that you converted to a separate window, the view area within the notebook is empty. If you click on this empty area, the view window is brought to the front of the Assembly Surface.

Using the Assembly Surface Views

This section describes how to use the following views:

Using the Beans View

The Beans view allows you to display, select, and perform actions on beans stored in repositories. The design of the view is a tabbed notebook and each page represents a set of beans stored in a particular repository.

The following graphic is an example of the Beans view of the Assembly Surface.


* Figure sembly5 not displayed.

The first page of the notebook is labeled "Repositories" and lists the set of all repositories you are currently using. You can use this page to:

To view the beans stored in a repository that you have added, select the notebook tab labeled with the repository name. The first time you select a tab, there is a delay while the associated repository is opened and its contents are loaded into the Assembly Surface. After loading, the set of beans stored in the repository are displayed on the selected notebook page. This delay occurs only on the initial time you select a repository tag unless the repository was updated since you last viewed it. If the repository was updated, there is another delay while the repository reloads onto the Assembly Surface.

After a set of beans is displayed, you can select one or more beans on which to perform actions. You select a bean by clicking on its icon or label. You can deselect a selected bean by clicking on the icon or label again. You can deselect all selected beans by clicking on an empty area of the notebook page.

On a selected bean, you can perform the following actions by clicking on a button on the notebook page:

If a repository was updated, but the contents are not displayed in the Beans view, you can reload the contents of the repository by clicking on the Update view of repository button.

You can perform most of the previously explained actions by using a pop-up menu item. To perform these action using a pop-up menu option:

  1. Right-click on the bean on which you want to perform the operation.
  2. Click on the appropriate action from the pop-up menu.

Using the Contents View

The Contents view displays the beans currently being assembled within the Assembly Surface tool.

The following graphic an example of the Contents view of the Assembly Surface.


* Figure sembly6 not displayed.

You can rename any of the beans by selecting the bean within the contents view, typing its new name in the entry field at the top of the view, and then clicking on the Name button.

If the name is not valid, the Contents view modifies the name to an acceptable name.

You can browse the definition of a bean by double clicking on the bean or by selecting the bean and then selecting the Browse bean definition item from the Contents submenu of the Options menu.
Note:You can only browse beans that were generated using the Edit data feature of the Assembly Surface.

You can delete any bean by selecting the bean and then clicking on the Delete button.

Using the Dips View

The Dips view allows you to display, select, apply, and remove dips from beans used in the assembly.

The Dips view consists of the following views:

The Available dips view is similar to the view supplied by the Beans view. The main differences are:

In the Available dips view, you can select one or more dips. You can click on the Apply dips to selected beans button to apply the selected dips to the bean selected in the Contents view. The Update view of repository button is similar to the Beans view. It reloads the contents of the repository and displays the dips it contains on the notebook page.

The following graphic is an example of the Available dips view of the Assembly Surface.


* Figure sembly7 not displayed.

The Applied dips view lists the set of dips that were applied to the bean currently selected in the Contents view. You can remove a dip from the bean by selecting the dip from the list and clicking on the Remove button.

The following graphic is an example of the Applied dips view of the Assembly Surface.


* Figure sembly8 not displayed.

Using the Customizer View

The Customizer view displays the customizer associated with the bean currently selected in the Contents view.

The following graphic is an example of the Customizer view of the Assembly Surface.


* Figure sembly9 not displayed.

The customizer allows you to specify or select the properties of a bean. The customizer is similar to the Properties view. The main difference is that a customizer is written for a specific bean while the Properties view is a generic view that works on any bean.

Because a customizer is designed for a specific bean, a customizer can be better suited to specifying its associated bean's properties than the Properties view. However, not all beans have a customizer. If a bean does not have a customizer, the view indicates that no customizer is available.

Using the Event Connections View

The Event Connections view allows you to wire beans together by associating an event generated by a source bean with an action in a target bean. You can configure the Event Connections view to operate in a tree view style or in a list view style. The view style is determined by selecting one of the menu items from the View styles submenu associated with the Event Connections section of the Options menu.

Using the Tree View Style

In the tree view style, you are presented with two panels. The left panel is a listing of event source beans. The right panel is a listing of the event target beans.

The following graphic is an example of the Tree View Style of the Event Connections view of the Assembly Surface.


* Figure sembly10 not displayed.

Each event source bean can be expanded to display the events that the bean can fire. For propertyChange and vetoableChange events, the properties of the event source bean that can fire the event are listed when either event is expanded. Selecting a method or property from the event source list updates the event target list with the set of event target beans that can be connected to the selected event.

Expanding an event target bean displays those methods that can be invoked on the target bean when the selected source bean event is fired. To complete a connection, select an appropriate target bean method and click on the Connect button. The new connection is added to the list of current event connections displayed at the bottom of the view.

To delete an existing connection, select the connection from the list of current connections, then click on the Disconnect button.

Using the List View Style

In the list view style, you are presented with a series of list boxes to perform a connection.

The following graphic is an example of the List View Style of the Event Connections view of the Assembly Surface.


* Figure sembly11 not displayed.

With this view, you perform the following sequence:

  1. Select a bean from the event sources list to update the source events list with all events for which the selected bean is an event source.

  2. Select an event from the source events list to cause the event targets list to display the list of beans to which the selected event can be connected.

  3. Select a target bean from the event targets list to cause the target methods list to show all methods in the selected target bean that can be invoked when the selected source event occurs.

  4. Select a method from the target methods list to specify the action to taken when the specified event occurs and to cause the Connect button to be enabled.

  5. Click on the Connect button to complete the connection and add the connection to the list of connections shown at the bottom of the view.

To remove a previously specified connection, select the connection from the list at the bottom of the view and click on the Disconnect button.

Using the Layout View

The Layout view allows you to visually specify the size and position of each AWT-based bean in the current assembly. It works best in a separate view window.

The following graphic is an example of the Layout view of the Assembly Surface.


* Figure sembly12 not displayed.

Using a separate view window allows for precise sizing of the assembled bean. For additional information, see "Using the Assembly Surface User Interface".

The default setting for this view is to automatically add and position all AWT-based beans that are added to the Contents view. This option is controlled by selecting the Automatically add beans item from the Options menu. If you do not select the automatic option, then you must use the Add item from the Edit menu to add the currently selected bean in the Contents view to the layout surface.

When a bean is on the layout surface, it can be resized by selecting the bean and dragging the corner of the border or moved by selecting the bean and dragging the window to a new location.

You can influence the parent class of a new bean by checking one of the menu choices from the Generate as item from the Options menu. The possible choices are Panel, Applet, or Frame.

Selecting the Hide item from the Edit menu allows you to specify which beans are to be initially hidden in the new bean.

Selecting the Show item from the Edit menu reveals previously hidden beans. The current selection in the Contents view determines which bean is revealed.

Selecting the Enable Applets item from the Options menu allows you to initialize and start any embedded bean that is an applet. Deselecting this menu item stops any embedded applets and displays them as a boxes.

Selecting the Set background item from the Options menu allows you to set the background color of the assembled bean.

Selecting the Close item from the View menu saves the current layout and exits the Layout view. Selecting this menu item is the same as selecting the Save item from the View menu and then selecting the Quit item from the View menu.

To delete all work on the current layout, select the Discard item from the View menu.

Using the Log View

The Log view lists all informational or error messages that occur during the bean assembly process.

The following graphic is an example of the Log view of the Assembly Surface.


* Figure sembly13 not displayed.

The Log view allows you to save the current contents of the log to a file by clicking on the Save Output to File... button and providing the file name in the dialog that is displayed. You can insert markers in the log to visually separate one group of log messages from another by clicking on the Mark button. You can delete all messages from the log by clicking on the Clear button.

In most cases, when the log is updated, a message is displayed on the status line. This message indicates that the Log view has changed. This message is to alert you to the fact that potentially important information was written to the log.

Using the Network Deployment View

The Network Deployment view allows you to access network deployment warehouses and catalogs for deploying Java components, and accessing deployed components, within an enterprise intranet environment.

The following graphic is an example of the Network Deployment view of the Assembly Surface.


* Figure sembly18 not displayed.

The network deployment view allows you to perform several operations upon warehouses and catalogs, which are used in deploying Java components and accessing deployed Java components. A network deployment warehouse is a repository of Java components. These components can be deployed (stocked) and later redeployed (restocked). A network deployment catalog contains entries, each of which describe a component or components stored in a warehouse. A catalog entry can be added to the catalog (stocked) and later updated (restocked). You can browse the catalog and issue queries on the catalog, in order to access (order) any deployed Java components.

Using the Properties View

The Properties view allows you to modify any of the public properties of the currently selected bean. Each of the properties of the bean is displayed in a column format. The name of the property is on the left, and the current value for the property is on the right. As changes are made to a property value field, the changes are applied to the corresponding bean.

The following graphic is an example of the Properties view of the Assembly Surface.


* Figure sembly14 not displayed.

Some property values have a custom editor pop-up dialog that can be displayed by clicking on the value field. The custom editor can then be used to specify a new value for the property.

Using the Publish Views

The Publish views (Publish and Publish BeanInfo) allow you to define the interface and explicit bean information for an assembled bean.

The following graphic is an example of the Publish view of the Assembly Surface.


* Figure sembly15 not displayed.

You can open each view individually by selecting it from the Publish submenu, or you can open both views simultaneously by selecting the All item from the Publish submenu.

The Publish view allows you to define the interface for the assembled bean. You can create new methods, properties, events, or fields. You can also have the assembled bean implement an existing interface. The Publish view allows you to select which subset of methods, properties, and events of the component bean are to be exposed as part of the interface of the assembled bean.

The Publish BeanInfo view allows you to define the explicit bean information of the assembled bean. The Publish BeanInfo view allows you to select which subset of methods, properties, and events of the component bean are to be exposed. Additionally, you can select which icon is to visually represent the assembled bean.

Using the Scripting View

The Scripting view allows you to attach Java or NetRexx code to an event listener method. The Java code is entered using a scripting IDE and executed when the event for that listener interface is fired at runtime.

The following graphic is an example of the Scripting view of the Assembly Surface.


* Figure sembly16 not displayed.

For additional information, see the "The Scripting IDE".

Using the Source View

The Source view displays the Java source code that is being generated for the current bean.

The following graphic is an example of the Source view of the Assembly Surface.


* Figure sembly17 not displayed.

You can use this view to gain a better understanding of how the Assembly Surface creates new beans and to determine where syntax errors in your code have occurred. In some cases, the bean may use several source files. If so, there is a separate notebook tab for each source file. Selecting a tab displays the source code for that file.

You can save a copy of any source code by clicking on the Save source code to file... button. A file dialog prompts you to specify the name of the file to which you want the source code copied. After entering a file name, the Java source code is copied to the specified file.

The contents of the Source view are updated each time the view is opened, the bean is generated, or its tab is selected. You can explicitly update the view by clicking on the Update source code button.

If a compilation error occurs during the bean generation process, the source view will contain the source in error along with any error messages generated by the Java compiler. Each error message is inserted immediately after the statement in error and has the form

>>> error message <<<
You can remove the error messages by click on the Remove error messages button.

Managing Dependencies Between Beans

When you create a bean using the Assembly Surface, you typically are creating a new Java bean that aggregates and modifies the behavior of one or more other Java beans. In many cases, the new bean will be stored in a JAR file that is different from the JAR files containing the original beans.

However, when you do this procedure, you should be aware that you are creating a dependency between the new JAR file and each of the original JAR files. For anyone to use this new bean, he or she must have not only the contents of the new JAR file but must also have the contents of each of the original JAR files.

In general, there are several approaches to managing the distribution and deployment of this new bean. These approaches are:

Dependency management applies to beans that were dipped and beans that were assembled. A bean that was dipped depends on the JAR file in which the dipped bean is stored and depends on the JAR files containing the dips that were applied. These techniques for managing bean dependencies work equally well for dipped beans.

Be aware that dependencies are not always obvious. If a bean being assembled uses a bean stored in another JAR file, and this second bean uses a dip stored in a third JAR file, then the assembled bean depends on all three JAR files:

For this reason, you must apply one of the dependency management techniques to all inclusive JAR files.


[ Top of Page | Previous Page | Next Page | Table of Contents | Documentation Homepage ]