Bean Extender Guide to Features
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:
- generate dip, plus its bean information, customizer, text bundle,
documentation, and makefile
- compile and provide support for packaging the dip into a jar file
- interactive testing of the dip, via the BeanExtender Assembly Surface
- support for unbound, bound, or constrained properties
- support for being an event source or event target
- control over which methods of the parent class get overriden
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
- An unbound property has getter and setter methods, but does not fire an
event when its value changes.
- A bound property fires a change event when its value changes
- A constrained property fires a vetoable change event before
its value changes, allowing listening
objects to veto the change. If no listening object vetoes the change, the
property acts like a bound property.
- 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.
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.
This release has the following limitations:
- WARNING: The code generator does NOT preserve changes to source files
made outside the wizard.
A warning message is shown before overwriting a file, but if you say yes,
any changes you made to the file will be lost.
- values entered are checked for correct form, but not content. Use valid
characters for forming file system names in names entered.
[ Top of Page | Previous Page | Next Page | Table of Contents | Documentation Homepage ]