Bean Extender Guide to Features


The Dip Creation Wizard

The Dip Creation Wizard is a code generation tool for creating beans known as "dips". Dips can be applied to existing beans in order to enhance, modify, restrict, or monitor functionality of the dipped bean. See "The Dipping Framework" for more information about dips. The primary features of the Dip Creation Wizard are:

The Dip Creation Wizard itself is a bean, and is built from beans, including custom beans such as notebook, listbox and HTML beans. It is a subclass of The Beanery, which is a general bean creation wizard tool, which can be run by invoking java com.ibm.beanery.Beanery if Beanery.jar and sk.jar are in the CLASSPATH. See the Beanery's online help for further information. The Beanery is available from IBM's alphaWorks web site.

An example of creating a dip using the Dip Creation Wizard is available in the Dip Creation Wizard Walk-Through.

Prerequisites, Installation and Execution

What platforms does the Dip Creation Wizard run on?

The Dip Creation Wizard is written completely in Java, and should run on any platform that supports Java 1.1.0 or later. The JDK for the execution platform  must be installed since the Dip Creation Wizard makes use of the Java compiler built into the JDK libraries.

The Dip Creation Wizard has been tested on OS/2 Warp 4.0 with IBM JDK 1.1.1, Windows NT 4.0 with Sun JDK 1.1.4, Windows 95 with Sun JDK 1.1.4 and IBM AIX 4.1.3 with IBM JDK 1.1.2.

How do I start the Dip Creation Wizard?

You may start the Dip Creation Wizard by adding dipWizard.jar, Beanery.jar, and sk.jar to your CLASSPATH, then invoking the java vm using the command java com.ibm.beans.tools.dip.DipCreationWizard

Can I start the Dip Creation Wizard with an initial file loaded?

You can load a dip model into the Dip Creation Wizard at startup by including its name as a parameter to the java command. For instance, java com.ibm.beans.tools.dip.DipCreationWizard splash.wiz will load the previous stored dip model as part of the startup. This feature may be used with the association feature of operating system shells to enable automatic launch of the Dip Creation Wizard when a .wiz file is opened.

What if the Dip Creation Wizard doesn't start?

The most common problem resulting in the Dip Creation Wizard not starting is a problem with the CLASSPATH (which needs to contain dipWizard.jar, Beanery.jar, and sk.jar). Ensure that you are at Java level 1.1.1 or later and that Java and the AWT can start correctly (you may try one of the sample programs).

If your Java level is less than 1.1.1 then the Dip Creation Wizard will not run since it requires services from this level of the Java libraries.

Generate dip: do I lose changes if I overwrite a file?

YES. Overwrite is a replacement of a file, not an update to it. If any changes were made to the file, then they will be lost. You will be prompted before any files are overwritten.

Compile dip: can't find text resources. Why?

This is a typical symptom when your CLASSPATH statement does not correctly match up with your output directory. When the java compiler runs, it compiles the base class, but cannot find the related file (in this case the text resource file) because the CLASSPATH is not set up correctly.

To fix this, ensure the output directory entry in the CLASSPATH statement matches the output directory specified on the Settings page.

What platforms does the make file work on?

The make file generated by the Dip Creation Wizard only works on Windows and OS/2. It should work with any make utility that supports NMAKE compatible text files. This file should be relatively easy to convert to Unix make file formats.

Using The Dip Creation Wizard

Menus

The File menu allows you to clear the current information (New), load previously saved information about a dip (Open), save the information about the dip to disk (Save, Save As) and exit the application (Exit). Note that the save options do not create a dip, they only save the state of the current working session so that you may return to this point later.

The View menu allows you to switch between different levels of detail. The Guide view is for starting dips, requiring the least amount of work to quickly create a dip. The Output view displays the source code or HTML that will be generated.

The Build menu is used to create the source code for the dip (Generate source), compile the files created (Compile) and test the generated dip (Test). The Test menu item will launch the BeanExtender Assembly Surface tool, which is a simple dip-aware bean aggregation enviroment, in order to try out the generated dip in action by applying it to your existing beans. For further information about the Assembly Surface tool, see the online help for the Assembly Surface.

The Help menu provides access to the Read Me file, the license agreement, online help, and the product information dialog. Help is also provided for each of the display items at the bottom of the window as the item gets the input focus.

Guide View

The guide view has seven pages that may be used to provide information for creating your dip. The Dip and Settings pages have required fields, the other pages are optional.

The Settings page

The last page, Settings, should be filled in the first time you use the Dip Creation Wizard, and its values will be remembered. You will probably fill in this page once, and only change it to update the year for your copyrights on an annual basis.

The author, company, year and notice fields are used to generate the file header information at the top of all text files.

The output directory field is used as the base directory for all generated files. Makefiles are generated to this directory, all source files are generated to a directory below the base directory. Here you can enter a default package prefix, which will appear as the first part of the dip's package name on the Dip page.

The Dip Page

This page requires that all entry fields contain data, though some of them will come up with acceptable default values. It is possible to create a dip only with information filled in on this page (assuming that the Settings page has been filled previously), however the generated dip will not be registered to listen for and react to property changes, method invocations, or event firings of the bean to which it is attached, nor will it have any properties or events of its own. The fields on this page are:

Dip Name
The class name for the dip, with no prefixes or spaces.

Dip Package
The dot-separated package name for the dip. This field comes pre-loaded with the package prefix from the Settings page. If you wish to place this dip into its own unique package, you can simply add one more level.

Dip Type
An arbitrary text string displayed to the user to identify this dip. See the DipInfo.typeName() method in the Bean Extender API Reference for more information.

Applicable To
Specifies the class which a bean must extend (or an interface which a bean must implement) in order to have this dip applied to it. Accept the default of java.lang.Object to allow this dip to be applied to any bean.

Priority
When a bean has multiple dips applied, the priority is used to determine the order in which each dip receives notification of an action occuring within the original bean. The higher the priority, the earlier the dip appears in the priority queue. 500 is the default. See the DipInfo.priority() method in the Bean Extender API Reference for more information.

Removable
Specifies whether this dip will allow itself to be removed from the bean to which it has been applied. See the DipInfo.isRemovable() method in the Bean Extender API Reference for more information.

Allow other dips
Specifies whether this dip will veto attempts to apply additional dips to the bean to which this dip is applied. A dip can not veto a dip already applied to the bean before this dip is applied. See the DipInfo.worksWith() method in the Bean Extender API Reference for more information.

Class comment
Text that will be placed before the class definition, and used as the class description in the HTML documentation.

The Listeners Page

This page is where you specify what you want your dip to listen for in the bean to which the dip is applied. You can listen for property changes, event firings, or general method invocations. You can choose to listen to all properties, events, or methods, or to only listen to selected ones. See "Creating a Dip" for more information on the different listeners provided by a dip.

DipMethodCallListener
Enables the dip to receive notification immediately after a method of its dippable bean is invoked.

DipMethodVetoListener
Enables the dip to receive notification immediately before a method of its dippable bean is invoked. The dip has the option to veto the invocation of the method.

DipPropertyChangeListener
Enables the dip to receive notification immediately after a property of its dippable bean is changed.

DipPropertyVetoListener
Enables the dip to receive notification immediately before a property of its dippable bean is changed. The dip has the option to veto the change of the property.

DipEventFireListener
Enables the dip to receive notification immediately after an event of its dippable bean is fired.

DipEventVetoListener
Enables the dip to receive notification immediately before an event of its dippable bean is fired. The dip has the option to veto the firing of the event.

Drop-down list
This list of the six potential listener types mentioned above allows the user of the wizard to select a given listener, and customize what that listener does. The following controls adjust as different listeners are selected to reflect each listener's customization.

Hook all methods
Specifies whether all methods corresponding to the listener selected in the above drop-down list need to be listened to.

"Hook all methods" and "Hook selected methods" are mutually exclusive.

Hook selected methods
Specifies whether only specific methods corresponding to the listener selected in the above drop-down list need to be listened to.

"Hook all methods" and "Hook selected methods" are mutually exclusive.

Listbox
If "Hook selected methods" is chosen, this is where the user of the wizard specifies which methods to listen to. This list is filled with all overridable methods of the "Applicable To" class entered on the Dip page.

The Methods Page

This page lets you specify additional methods of interest that you may want emitted into your dip's source code.

constructor
Allows initialization code to be entered that will be run when the dip is first instantiated.

finalize
Allows cleanup code to be entered that will be run when the dip gets garbage collected.

readObject
Allows transient data initialization code to be entered that will be run when the dip is deserialized.

writeObject
Allows special serialization control code to be entered that will be run when the dip is serialized.

createImplementation
Allows code to be entered to run when the dip is applied to a bean. The wizard will automatically generate code to reject the addition of the dip if the bean to which it is being applied is not an instance of the class specified in the "Applicable To" field of the Dip page. Also, code to store a reference to the bean to which the dip is applied will automatically be generated. It is highly recommended that this method be generated, unless the dip is applicable to all beans and does not need a reference to its dippable bean.

releaseImplementation
Allows cleanup code to be entered that will be run when the dip is removed from its dippable bean.

includeInMorphedClass
Allows specification of which methods to override when morphing a bean (only applicable if this dip is added as a pre-dip). If the user of the wizard specifies to only listen to selected methods, properties, or events (rather than choosing to listen to all methods on the Listeners page), then the wizard will automatically generate code specifying to only override those methods when generating a dippable bean and using this dip as a pre-dip.

The Properties Page

Many of the features of beans are delivered through the definition and implementation of the properties of the bean. The property page allows you to enter the information about the dip, and then will generate the code necessary to implement the properties and features requested. The fields on the page are:

Type
The Java data type of the property. This may be a native type or a class name.

Name
The name of the property as a Java variable name.

Binding
Specifies whether a property is unbound, bound or constrained.

Label Text
Used to define a text string for display in tool property sheets. This is useful for properties with multiple words that are not presented well by automated name generation in tools.

Description
Used by tools for popup help or status line helpers.

Property Editor
Currently not implemented.
When these fields have been filled in (test and description are optional), the Add button will populate the property list with the information.

When the list of properties has any entries, they may be selected. When a property is selected in the list, the fields are populated with its values. Changes may be made to the fields, and pressing the Update button will change the contents of the selected property. Pressing the Remove button will remove the currently selected property from the property list.

The Events Page

Most beans are the source of events, or listen for events to respond to. This page provides a list of events that this dip can be a source of, or that this dip listens for. Each of the events listed corresponds to events defined in java.awt.events, with the addition of the generic event which corresponds to the java.beans.PropertyEvent. See the status line text for each checkbox for further details about each event type.

The BeanInfo Page

When a dip is used in a builder tool, design time information is available through the BeanInfo class that corresponds to the dip. This page provides customization options for the creation of the BeanInfo class for this dip.

Inherit parent properties
If you want to have the properties from the parent class shown on the property sheet, in addition to the properties you define, check this box. Since SimpleDip (the parent class of all dips generated by the wizard) has no properties, this item currently has no effect.

Generate customizer
A customizer is used for special processing of properties that cannot be provided for in a property sheet. When a customizer is created for a bean, a Customize menu item will be made available in the builder tool, and when chosen will launch a dialog box for the developer to interact with.

Custom icons
Beans may support custom icons (16x16 and 32x32 pel color and monochrome GIF images). If your dip will have custom icons, check this box. The code to load the images will be generated, but you must provide the icons.

Output View

The Output view lists all of the files that will be generated in a list on the left side. When a file is selected in the list, the output will be generated and displayed on the right side. For source files, they will be displayed in a text display. For HTML documentation, they will be displayed in an HTML viewer.

The Output view is a preview only, it does not write the files to the disk.

Release Notes

This release has the following limitations:


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