BeansExpress
JBuilder's BeansExpress is the fastest way to build and deploy JavaBeans.
Quick Steps
- Open a new or existing project.
- Open new or existing class(es) with parameterless constructor(s).
- Add the desired UI and behavior to
your bean(s).
- Add Properties, Methods and Events as needed.
- Optionally, create a BeanInfo class to control the presentation of your bean in designers.
- Deploy your bean(s) in a .JAR file.
- Put your beans on the Component Palette.
QuickStep 1:
Open a new or existing project.
- If you do not have an existing project for this bean, create one now using the Project Wizard. Use File|New and then double click Project.
- If you do have an existing project that contains java classes you want to turn into JavaBeans, use File|Open to open that project now.
Go on to step 2
QuickStep 2:
Open new or existing class(es).
- If you do not have an existing Java class for this
bean, create one now.
- The fastest way to create a new bean based on a Panel, intended to be part of a user interface, is to select
File|New, click the BeansExpress tab on the Object Gallery, and double click the New Bean tool.
- For other types of beans, you could use one one of the File|New wizards, such as Frame, Panel, Class, or DataModule.
Note: If you are using File|New Class, be sure to check the "Generate default constructor" checkbox to assure meeting the bean requirement of having a parameterless constructor available.
- If you do have an existing java class in your project for this bean, make sure that it has a public
parameterless constructor.
Once you have a class started for your new bean,
go on to step 3
QuickStep 3:
Add the desired UI and behavior to your bean(s).
- If your bean doesn't yet have the UI or behavior that you want:
- Use the UI Designer to add the UI and user interaction logic, if any.
- Use the DataAccess components to access data, if needed.
- Use the Interaction Wizard or add code by hand to create live behavior and engine code as needed.
- For more in-depth information on designing and creating components, see the
JBuilder Component Writer's Guide.
- If your bean already has the UI and behavior that you want, you are ready to go on.
Go on to step 4
QuickStep 4:
Add Properties, Methods and Events as needed.
To make your bean a good reusable component, you will need to add appropriate Properties, Methods
and Events to it. This "PME" interface is what the customers of your component will need for embedding it in other
software.
Note: in JBuilder documentation, "bean" and "component" are synonymous, because JBuilder uses the JavaBeans model for software components.
For more detailed information on adding appropriate Properties, Methods, and Events to your bean, refer to the
JBuilder Component Writer's Guide.
Go on to step 5
QuickStep 5:
Create a BeanInfo class (optional)
If you want to change the way that your bean's PME appears in design tools (for example, change the PME element names or add descriptions), then you can create a BeanInfo class. You can use the Bean Info tool
on the BeansExpress page of the Object Gallery to accomplish this quickly. Choose File|New, click the
BeansExpress tab, and double click Bean Info.
Go on to step 6
QuickStep 6:
Deploy your bean(s) in a .JAR file.
Compile your project, then use Wizards|Deployment to launch the Deployment Wizard.
The Deployment Wizard will assist you to place all the necessary files for one or more beans from your project into a .JAR (Java Archive) file for distribution to your customers.
Note: you may want to test your beans on the Component Palette (see next step) during
development, before deploying them in a .JAR file. You should always place your deployed bean on the Component Palette and test it from there, after using the Deployment Wizard, to be sure that you have put all the necessary files into the .JAR file.
Go on to step 7
QuickStep 7:
Put your beans on the Component Palette.
Use Tools|Configure Palette to bring up the Palette Properties dialog. Here you can add your beans to the Component Palette for testing or production use in the JBuilder environment.
- If you haven't used the Deployment Wizard yet (for example, you are still developing your bean and want
to test it while it is still separate class files), then use the "Add from Package" page of the Palette Properties dialog.
- Once you have deployed your bean in a .JAR file, you should place it on the Component Palette using the "Add from
Archive" page of the Palette Properties dialog. This is also the way that your bean customer can install your bean from the .JAR file onto their Component Palette.
For more information, see Managing your palette, or click the Help button on the Palette Properties dialog.
Congratulations, you have finished building and deploying your JavaBean! You and your customers can use it from the Component Palette to build new applications and components.
About JBuilder's BeansExpress
About BeansExpress
There is a BeansExpress tab on the Object Gallery, on which you will find several tools and examples that will enable you to build most simple beans quickly. To get to these tools and examples, choose File|New and click the BeansExpress tab of the Object Gallery.
Here is a quick introduction to each of the items on the BeansExpress page, and what they can do for you.
The first two items can be used to generate sample beans into your project. You can examine these sample beans to get a feel for what a bean looks like.
The next three items are tools that you can use create your own new beans from scratch.
BeansExpress also provides you with a BeansExpress tutorial for learning these samples and tools.
About the Ok Cancel Bean sample
The Ok Cancel Bean item on the Object Gallery can be used to generate a sample bean into your project. This sample demonstrates:
- How a compound UI component can be structured from existing components.
- How ActionEvent aggregation can be handled.
An example of using the Ok Cancel Bean sample bean shows you how to place this example bean onto the Component Palette and then use it in a design.
About the DB Bean database browser sample
The DB Bean item in the Object Gallery creates a sample bean in your project. This sample demonstrates a simple database UI
bean with which you can quickly browse a database.
This sample bean provides a slightly more complex example than the Ok Cancel Bean of a compound bean built up from several UI elements, and includes some simple usage of DataAccess components as well.
This bean shows an example of one way of hiding DataAccess objects inside a bean.
For a true database-only bean, with no UI, you would probably want to start with a DataModule. See
Encapsulating your data for more information on creating DataModules.
To see DB Bean in action, see An example of using the DB Bean sample.
About the New Bean tool
The purpose of the New Bean tool is to create a new JavaBean in your project. This will be a bean subclassing BeanPanel. BeanPanel is a Panel that contains some enhancements to simplify your job of creating a new bean quickly.
To use the New Bean tool to start a new bean:
- Open a new or existing project in which to place the bean.
- Choose File|New, select the BeansExpress tab of the Object Gallery, and double-click New Bean.
A new class, named NewBean by default, is added to your project.
If you wish to rename the class, do the following:
- Select the file in your project, and choose File|Rename.
- Do a search and replace in the file, changing "NewBean" to the new name.
- Place the new class into Design mode. (To do this, click the class file node in the upper left of the AppBrowser, then click the Design tab that appears at the bottom of the AppBrowser.) Then build the UI that you want the bean to have, and add any special behavior that the bean will need.
- Add Properties, Methods, and Events.
- Properties:
Add property setters and getters that will expose to your bean user the properties you want to make public for controlling your bean's initialization or subsequent operation. These will be the properties that will typically show up on the Properties tab of the Component Inspector when the developer using your bean selects your bean in a design.
To add new properties, first copy the setExample and getExample methods. Then change their property name to your new property. Both the setter and getter names should change, and you will want to change the example instance variable to be your own property variable name. If appropriate, insert additional behavior in the getter or setter.
- Events:
Add support for any events that you want your bean to be able to generate. These will be the events that will typically show up on the Event tab of the Component Inspector when the developer using your bean selects your bean in a design.
- ActionEvents:
To handle the typical case of a bean that is a compound UI built up from other JBCL UI components, you will find a simplified means of aggregating outgoing ActionEvents. For each place in your bean where an internal UI event occurs (such as the clicking of a particular button control), call the fireActionEvent that was provided by the New Bean tool, with an appropriate new event command string.
Technical details: fireActionEvent calls the processActionEvent method in the BeanPanel parent class. BeanPanel also contains all the necessary mechanisms for event listener registration and for distributing event notifications.
- Other events:
To add new events other than ActionEvent, you can use the New Event Bean tool.
See also Working with events in the Component Writer's Guide.
To complete the process of creating and deploying your bean, you can:
- Optionally, create a BeanInfo class if you want to change the way your PME appears in UI designers. To do this, use the BeansExpress Bean Info tool.
- Deploy your bean, using the Deployment Wizard (choose Wizards|Deployment).
- Place your bean onto the Component Palette (choose Tools|Configure Palette).
See also: An example of using the New Bean tool.
About the New Event Bean tool
The purpose of the New Event Bean tool is to create all of the pieces needed for a new event set that you can use with a bean you are creating. This will give you:
- The event object class.
- The event registration methods.
- A multicast uncracked event notification mechanism.
- A method that when called will send event notification to all listeners.
Note: The New Event Bean tool will place all of these pieces of code into a single new file in your project. This places several public classes into one file. Although this is, strictly speaking, valid Java, you will undoubtedly want to move pieces of the resulting file out into separate .java files of their own. Some of the pieces are dummy stubs that represent other classes you may already have in your project; these pieces can be discarded as appropriate.
See also: An example of using the New Event Bean tool.
About the Bean Info tool
The purpose of the Bean Info tool is to create a BeanInfo class to correspond with some existing class in your project.
For example, if you have a class called MyBean in your class, this tool will create a class called MyBeanInfo.
A BeanInfo class controls the way that the PME of your bean is presented in visual UI designer environments. For example, you may want to hide some parts of the PME from visual designers, or you may want to use alternate names for the PME elements, to make them more understandable in visual designers.
See also: An example of using the Bean Info tool.
BeansExpress Tutorial
This section is a walkthrough of some examples using the BeansExpress tools that are on the Object Gallery.
The first two show you example beans, so you can get a feel for what a bean looks like, and how to put them on the Component Palette and deploy them.
The next three examples lead you through the steps of creating your own new bean from scratch, using the BeansExpress tools.
Example of using the Ok Cancel Bean sample
This example shows you how to place this sample bean onto the Component Palette and then use it in a design.
- Open or create a project into which the OkCancelBean file will be created. For example, use File|New Project
and accept the defaults from the Project Wizard.
- Create the OkCancelBean class into your project. To do this, select File|New, click the BeansExpress
tab of the Object Gallery, and double-click the Ok Cancel Bean icon. You will see a new node, called OkCancelBean, in the project.
- Compile the OkCancelBean. To do this, click the bean to select it, then right-click and choose Make. You should see "Compiler: Successful, with no errors." in the status bar.
- Place the OkCancelBean onto the Palette:
- Choose Tools|Configure Palette.
- Select the "Add from Package" page of the dialog. (We haven't deployed the OkCancelBean class file
in a .JAR file yet, so we will simply be adding the OkCancelBean class file from your project's package.)
- Click the Browse button to bring up a file browser for locating the .class file.
- Browse to the subdirectory of
jbuilder\myclasses\
where your project's OkCancelBean.class file is,
select the file, and click OK.
The Palette Properties dialog loads its list box with a list of all the classes that are beans in this packages of classes.
OkCancelBean might be the only bean listed.
- Select OkCancelBean in the list.
- Use the pull-down to select "Others". This indicates that the new bean should be installed on the Others tab
of the Component Palette.
- To complete the installation, click the Install button. You should see the message "Installation complete"
appear on the dialog.
- Click the OK button to close the Palette Properties dialog.
- Change the Palette to the Others tab. You should see the new OkCancelBean button on it. Note the correct
class name displayed in the tooltip when you position your mouse pointer over the new button.
- Use the OkCancelBean in a new UI frame.
- Close the project that you created for building the OkCancelBean.
- Choose File|New Project, to create a new project in which you will use the bean from the Component Palette in a new UI, as though you were a customer for your bean.
- Run the Application Wizard, and accept the defaults, to create a new application and frame. Choose File|New... Application, and accept the defaults.
- Select the Frame1 class in the upper left, and click the Design tab at the bottom of the AppBrowser.
- Select the Others tab on the Component Palette and click the new OkCancelBean button.
- Draw a rectangle across the bottom of your UI in the UI Designer, where the OkCancelBean panel should go. You should see a panel appear there with Ok Cancel and Help buttons.
Congratulations, you have successfully built a bean, put it on the Component Palette, and used it in another design!
OkCancelBean gives you an opportunity to see the effect of a bean implementing the BlackBox interface, namely that, although the bean uses a compound UI, made up of buttons on a panel, it acts as a single entity when dropped into another design. Try clicking the OkCancelBean panel in your Frame design, and see the selection nibs around it. Try clicking on
one of its buttons, note that the nibs don't select just the button. When a component implements BlackBox, it is tagged as a UI element that should be treated as a single entity when used in the designers.
Next, you can try building and using the somewhat more complex database browsing bean, in the Example of using the DB Bean sample, or you can try building a bean of your own, similar to
this OkCancelBean, in the Example of using the New Bean tool.
Example of using the DB Bean sample
Here is an example of using the DB Bean sample, building it, placing it on the Component Palette, and using it in a quickly designed UI.
- To use the DB Bean, you will need to have installed a jdbc-accessible database. By default, the DB Grid attaches to the default data source available when you follow the normal instructions for installing Local Interbase
with JBuilder.
- Use steps similar to those in the Example of using the Ok Cancel Bean sample
to:
- Place the DB Bean sample into a project.
- Choose Build|Make.
- Place the bean onto the Others page of the Palette.
- Create a new project where you will use the bean in a UI Frame.
- Draw the DB Bean component onto the UI Frame design.
At this point, if you have Local Interbase installed and have the default DataSet Tutorial datasource set up, you should see data appear in the DB Bean grid in the designer.
- Compile and run your test application.
- Try out the bean in in the application.
In the future, when you need a quick look into what columns and records are in a database, remember this DB Bean.
Example of using New Bean tool
This example shows you how to use the New Bean tool to create a bean that is a simple panel with three buttons: Yes, No, and Cancel. This bean will be similar to the Ok Cancel Bean sample, except that you will build it yourself.
- If you don't already have a project for the YesNoCancel bean, use the Project Wizard to create one.
- Next, choose File|New, select BeansExpress, and double-click the icon for the New Bean tool.
A new class will be generated into your project.
Take a brief look through the source of the new file. Note that the new class extends
borland.jbcl.control.BeanPanel, which provides support for making beans quickly. The new class implements borland.jbcl.util.BlackBox, which has the effect of keeping the designer (when somebody eventually uses your bean in a design) from trying to redesign the UI of your compound
component. The compound component is treated as a single component.
- Change the name of the class to YesNoCancelPanel, as follows:
- Select the file in your project, choose File|Rename, and change the name to: YesNoCancelPanel.java
- Do a search-and-replace in the file, changing "NewBean" to "YesNoCancelPanel".
- Add four buttons to the design, as follows:
- Put the class into Design mode: select it in your project, and click the Design tab of the AppBrowser.
- Draw four buttons on the panel, side by side.
- Change their Labels, in the Inspector, to Yes, No, Cancel, and Help.
- Change their <name> properties to yesButton, noButton, cancelButton, and helpButton, to make your subsequent work easier.
- Change the layout of the inner bevelPanel1 to FlowLayout.
- Add a Property to your bean that controls the visibility of the Help button, as follows:
- Search and replace the variable named example to helpVisible. Find the line where the variable is declared, and change its type to boolean and its initial value to true.
- Rename the setExample method to the boolean form of the property getter, setHelpVisible, and change its
parameter String s to boolean v.
In the setExample method, change the line that reads:
example=s;
to read:
helpButton.setVisible(v);
helpVisible = v;
- Rename the getExample method to isHelpVisible, and change the return type to boolean.
Change its body from:
return example;
to:
return helpVisible;
- Aggregate the button events to a single ActionEvent
coming out of the panel, as follows:
- Find the line that reads:
public static final String EXAMPLE_EVENT = "ExampleEvent";
and change it into four lines that read:
public static final String YES_EVENT = "Yes";
public static final String NO_EVENT = "No";
public static final String CANCEL_EVENT = "Cancel";
public static final String HELP_EVENT = "Help";
- Change the fireExampleActionEvent method
name to fireActionEvent,
give it a single parameter, String s, and pass that parameter,
instead of EXAMPLE_EVENT, to the processActionEvent call.
So now the method should look like:
protected void fireActionEvent(String s) {
//Args: event source,event ID, event command
processActionEvent(
new ActionEvent(
this,ActionEvent.ACTION_PERFORMED, s));
}
- Now add the event handlers for the four buttons, and implement
the event handling methods to call the fireActionEvent method
with the appropriate string. Here is what you do for the
Yes button, for example:
- Select the yesButton in the design, switch to the Event
tab of the Inspector, double click on actionPeformed, and
click Enter (or just double click on the Yes button in the UI Designer).
- Add a line to the body of the yesButton_actionPerformed method, so that
it reads:
void yesButton_actionPerformed(ActionEvent e) {
fireActionEvent(YES_EVENT);
}
- Do the same for the other three buttons, being
sure to use the correct event string.
- Compile the class, fixing any typos as needed.
- Put your new bean class on the Other tab of the
JBuilder Palette, as follows:
- Be sure that YesNoCancelPanel is selected
in the project.
- Select Tools|Configure Palette
- With the Pages tab of the dialog selected, select the Others item in the left hand list.
- Select the Add from Archive tab.
- Click the Browse button, browse to the jbuilder\myclasses subdirectory
containing your class file, and double click the class file.
The Palette Properties dialog should now list all of the .class files generated by your project.
- Select the YesNoCancelPanel item (only).
- Click the install button to install the component onto that Palette.
- Click the OK button to close the Palette Configuration dialog.
- Check the palette's Other tab: you should see an icon whose
popup help shows your class.
- Test your bean in a new UI:
- Close the project containing your bean.
- Run the Project Wizard to create a new project,
then the Application Wizard. On the second page of the
Application Wizard, check the "Generate status bar" item.
- Switch the frame file into design mode
- Select your YesNoCancelPanel from the Palette and draw it onto
the new frame. It should appear with all 4 buttons visible.
- Click on one of the buttons.
Note that doing so doesn't select the button, rather it selects
the entire YesNoCancelPanel. This is because
YesNoCancel implements
borland.jbcl.util.BlackBox,
which tells the UI Designer
that the inside of YesNoCancelPanel is not designable when
it is dropped as a component into another design.
- Look in the inspector. Note that, in addition to the
properties exposed by a BeanPanel, you should see
a helpVisible property. Try toggling it from true to false and back,
and watch what happens to your bean in the UI Designer.
- In the UI Designer, double click the YesNoCancelPanel,
and edit the event handling method so that it reads:
void yesNoCancelPanel1_actionPerformed(ActionEvent e) {
statusBar.setText(e.getActionCommand());
}
- Run the application, try pressing various buttons, and
see what appears in the status bar.
Congratulations, you have built a bean, placed it on the palette,
and used it in another application.
Example of using New Event Bean tool
This example will show you how to use the New Event Bean tool
to create a new type of event, and make your bean generate it.
We will use results of the previous tutorial step, the
YesNoCancelPanel bean, create a new type of
"help enable changed" event, and generate it when the help button
is enabled or disabled.
- Reopen the project for your YesNoCancelPanel.
- Select File|New, select the BeansExpress tab, and
double click the New Event Bean tool.
- On the dialog that comes up, click the Parameters button,
enter HelpEnableChange, click OK on the parameter dialog,
and click OK on the New Event Bean dialog.
A new class, HelpEnableChange.java, will be added to
your project.
- Choose File|Open/Create and create a new empty java file in your project's
directory, named HelpEnableChangeListener.java.
Be sure to check the add to project button, then click OK.
- Go to the HelpEnableChange.java file, cut the HelpEnableChangeListener
interface declaration to the clipboard, and then paste it into the
new empty file of that name.
- You will also need to copy the package name and the java.util.* import
to the top of the HelpEnableChangeListener.java file.
- Copy the following items from the dummy
HelpEnableChangeExampleBean class in
HelpEnableChanged.java and paste them into the body
of the YesNoCancelPanel class. (Make sure you put
the methods into that class, and not be confused by
the ActionAdapters at the bottom of the file.):
- Once you have done that, delete the entire dummy
HelpEnableChangeExampleBean class from
HelpEnableChanged.java. This should leave just the
one HelpEnableChange class in the
HelpEnableChange.java file, plus the package and
import statements at the top.
- Place at the top of the YesNoCancelPanel.java file
a line that reads:
import java.util.*;
- In HelpEnableChange.java, change the three lines that look like:
static final int EVENT1=1;
static final int EVENT2=2;
static final int EVENT3=3;
to read:
static final int DISABLED=0;
static final int ENABLED=1;
- In HelpEnableChangeListener.java, change the lines that read:
public void event1(HelpEnableChange e);
public void event2(HelpEnableChange e);
public void event3(HelpEnableChange e);
to read:
public void disabled(HelpEnableChange e);
public void enabled(HelpEnableChange e);
- In YesNoCancelPanel.java, change the body of the
processHelpEnableChange method to have two cases,
for DISABLED and ENABLED, and be sure to have them each call
the correct new event listener methods.
The new method should read:
protected void processHelpEnableChange(HelpEnableChange e) {
switch (e.getID()) {
case HelpEnableChange.DISABLED:
for (int i=0; i<listenerList.size(); i++)
//Send event to all registered listeners
((HelpEnableChangeListener)listenerList.elementAt(i)).disabled(e);
break;
case HelpEnableChange.ENABLED:
for (int i=0; i<listenerList.size(); i++)
((HelpEnableChangeListener)listenerList.elementAt(i)).enabled(e);
break;
}
}
- Find the setHelpVisible method in HelpEnableChange.java,
and add a new statement to it calling the
processHelpEnableChange() method,
so the method now looks like:
public void setHelpVisible(boolean v) {
helpButton.setVisible(v);
helpVisible = v;
processHelpEnableChange(
new HelpEnableChange(
this,
v?HelpEnableChange.ENABLED:HelpEnableChange.DISABLED));
}
- Recompile YesNoCancelPanel.
- Now test your bean's ability to generate this new event:
- Close all projects
- Reopen the test project that you created in the NewBean example.
- Add a pair of buttons to the frame, one labeled "disable help", and the
other "enable help".
- Double click on the "disable help" button,
and edit its event handling method to read:
void button1_actionPerformed(ActionEvent e) {
yesNoCancelPanel1.setHelpVisible(false);
}
- Similarly, install an event handling method for the enable button:
void button2_actionPerformed(ActionEvent e) {
yesNoCancelPanel1.setHelpVisible(true);
}
- Select the YesNoCancelPanel in the design
- Select the Events tab on the inspector, double click the
enabled event, and add a statement to the
event handling method that displays text to the status bar. The
method should look like:
void yesNoCancelPanel1_enabled(HelpEnableChange e) {
statusBar.setText("help disabled");
}
- Do the same for the disabled event:
void yesNoCancelPanel1_disabled(HelpEnableChange e) {
statusBar.setText("help enabled");
}
- Run the test application, click the new buttons, and you can see
that the new event mechanisms for the custom event are working.
Congratulations, using the New Event Bean tool you have built a new
custom event generation mechanism into a bean, seen it in the Inspector,
and used it in an application.
Example of using the Bean Info tool
This example will show you how to build a BeanInfo class
for your bean.
A BeanInfo class is a class that describes your bean.
In particular, it manages the way that your bean will
appear in visual design tools. A BeanInfo
class will allow you to hide or expose properties,
give them aliases for design purposes, and
give them brief descriptions that will be visible
in design tools.
The beans on the JBuilder Palette use BeanInfo
classes for providing the tool tips that are seen
in the Inspector for various properties, as well
as for hiding some of the properties from
the visual design tools, if they should only
be used programmatically for example.
A BeanInfo class is associated, by design
tools, with the actual bean class by a naming
rule: add "BeanInfo" to the name of the class.
For example, if you wanted to give the OkCancelBean
bean a BeanInfo class, it should be
in the same package, and named OkCancelBeanBeanInfo.
BeanInfo classes are optional.
Here is an example of adding OkCancelBeanBeanInfo
to the OkCancelBean sample:
- Follow the instructions in
Example of using the Ok Cancel Bean sample
to create an OkCancelBean.
- Select File|New, select the BeansExpress tab, and select the Bean Info tool.
The Paste Snippet dialog will come up for the Bean Info.
- Click the Parameters button.
- In the "Name for bean info class", enter "OkCancelBeanBeanInfo"
- In the "Bean class", enter "OkCancelBean"
- Browse through the source code that was
generated for the new OkCancelBeanBeanInfo class.
Notice that there are a number of documented
but commented-out methods and variables in the code.
You can remove the commenting to activate the items you may want,
adjusting them to contain the correct information
for describing the Properties, Methods, and Events
of your bean. Note that these methods and variables are
all implemented and initialized in the
borland.jbcl.util.BasicBeanInfo base class,
so it is not necessary to implement or set them
all here, only as you need to do so to customize
the BeanInfo.
- Find the propertyDescriptors variable
in the class. You can begin developing your BeanInfo
class by uncommenting this variable, and providing
the property names and descriptions correlated
with the property setters and getters you want to
expose. Look at the results this has
upon what is shown in the property page
of the Inspector, and its property tool tips,
when an OkCancelBean is selected within some design.
Congratulations, you have made your first BeansInfo
class!
Making a bean from an Applet
You can quickly convert existing Applets into
JavaBeans using the JBuilder Wrap Applet Wizard.
Use Wizards|Wrap Applet
This wizard creates a new bean class, customized for being
wrapped around an existing applet to turn it into a bean.
The new wrapper class gives the applet context to make
it think it is on an HTML page, and surfaces the applet
parameters as beans properties.
The beans on the Sun Applets tab of
the Component Palette are examples of Applets
that have been converted into beans.
Steps:
- Create a new applet, or identify an existing applet, that
you wish to turn into a bean.
- Place the applet into a project, and make sure you successfully
compile it.
- Choose Wizards|Wrap Applet.
- Confirm that it has the right class listed.
- Enter any modifications or default values for the parameters
to be exposed by the bean.
- Click the Finish button.
- You can now deploy the bean, or place it on the Palette, for
use as a real JavaBean.
That's all there is to it!
Making a bean from a Dialog
If you want to make a dialog into a component capable of
being placed onto the JBuilder Component Palette,
similar to the beans on the Dialogs tab of the Palette,
you must turn it into a JavaBean.
In Java 1.1, a Dialog subclass cannot itself
be a bean. This is because beans require parameterless
constructors, whereas a Dialog requires a parent Frame
parameter at contruction time. You cannot work around this
by simply adding a parameterless constructor to your subclass
and ignoring the need for a parent frame.
In Java 1.1, to make a bean out of a dialog, you must
"wrap" the real dialog class with a separate class that
has:
- the real dialog as a subcomponent.
- a parameterless constructor that does not immediately
instantiate the actual dialog.
- a frame property, which can be set to
the desired parent Frame before calling
the show() method.
- a show() method that constructs the
actual dialog, using the value previously set in
the frame property to pass into the constructor
of the actual dialog, and then calls the actual
dialog's show() method.
- property setters that can set default values
into the dialog for the various controls on the dialog
before calling show().
- property getters that can read the user-entered values back
out of the dialog once the user has pressed some button
like OK or Apply.
- a mechanism for indicating which button was pressed
to close or apply the dialog. Perhaps this would
be some sort of methods for setting and getting
some sort of "result" value or descriptor, whose values
can indicate results such as OK, CANCEL, and APPLY, and which can
also indicate a state like "none".
"None" can be useful for external validation code to set back
into the result in order to veto the closing of a dialog.
- event generation mechanisms for generating appropriate
events, such as an aggregated actionPerformed event,
when buttons on the dialog are pressed.
- mechanisms for dealing with validation of user-entered
values, either internal validation in the bean before
any actionPerformed event is generated, or the ability to
have the actionPerformed event vetoed (typically be resetting
the "result" mechansim to indicate "none") by the code using the bean
if external validation fails.
- an implementation of
WindowListener,
added as a listener to the actual dialog, to detect when various Window
events come out of the dialog so that the bean will track changes
in the dialog.
Note that the property setters and getters, and the event
mechanisms, are surfaced by the outer "wrapper" class, but
are typically delegated to the actual Dialog class during
times when it is instantiated.
For examples of dialogs wrapped as beans, see the
borland.jbcl.control.ColorChooser
and
borland.jbcl.control.Message.
Notice that they don't extend
Dialog, but instead these classes wrap and instantiate the actual
dialog class,
borland.jbcl.control.MessageDialog, and
borland.jbcl.control.ColorChooserDialog,
respectively. Those classes in turn extend
borland.jbcl.control.ButtonDialog
for convenient access to a number of useful mechanisms
that you can use for making bean dialogs.
Here are steps for making a bean from a dialog:
- Create and design a subclass of Dialog.
You can use the File|New Dialog wizard to do this,
or you can start with one of the code snippets
from the Dialogs page of the Object Gallery under File|New...
For a dialog intended to be wrapped as a bean, you may
find it quicker to edit your class so that, instead
of extending Dialog, it extends
borland.jbcl.control.ButtonDialog,
because that class contains some predefined code to
make the job easier.
- Create the wrapper class. You can start this class
using the File|New Class Wizard, being sure to turn
on the option to have a default (parameterless) constructor.
(Do not use the New Bean tool in BeansExpress that generates
a bean based on a panel.)
- Add property getters and setters to this class for the
parent frame, and store the value in an internal
instance variable in the wrapper class.
- Add property getters and setters, (the same sets on both the
wrapper class and on the actual dialog class), for any user input
fields in the dialog that need to be preset with
defaults or read back after buttons such as OK or Apply
are pressed. The wrapper class property setters and getters
should work against values cached in wrapper class
variables during times when the actual dialog class is not
instantiated, but delegate directly to the matching property
getters and setters when the actual dialog when it does exist.
See the setValue() and getValue methods in
borland.jbcl.control.ColorChooser
and
borland.jbcl.control.ColorChooserDialog
for an example of how to do this.
- Add methods for setting and getting the "result" mechanism
of the dialog. The result indicates which button was last
pressed, such as OK, Cancel, Apply, or None.
For an example of a mechanism to do this, see the setResult
and getResult() methods in
borland.jbcl.control.ButtonDialog.
- Implement a show() method in the wrapper class
that instantiates the actual dialog, using the value
in the frame property as the parent frame
in the constructor of the actual dialog.
Your show() method should throw an
exception if the frame property
wasn't previously set. After instantiating the
actual dialog, the show() method should
proceed to set the properties in the actual dialog
with values cached in the wrapper by the wrapper's setters
when the real dialog wasn't instantiated.
See the show() methods in
borland.jbcl.control.Message
and
borland.jbcl.control.ColorChooser
for examples.
- Add event generation mechanisms to the actual
dialog class that will aggregate button events
inside the dialog into a single
ActionEvent mechanism for events coming
out of the dialog.
To see one way of doing this, examine the
setButtonSet(), addActionListener(),
and processActionEvent() methods in the
borland.jbcl.control.ButtonDialog
base class of MessageDialog and ColorChooserDialog.
The addActionListener() methods in the
Message and ColorChooser wrapper classes delegate to
addActionListener() in ButtonDialog,
when the dialog is instantiated, or store the listeners in
a cache if the dialog is not yet instantiated.
The show() method in the wrapper class moves not only
properties, but also the cached listener list, into the
real dialog when it is instantiated.
The setButtonSet method in the ButtonDialog base class
sets the ButtonDialog as the ActionListener
for all the buttons, and then, on the dialog's single
actionPerformed method which is called for any of
the button action events, calls processActionEvent
to send the aggregated ActionEvent to the listeners that were
originally added to the wrapper's addActionListener method
(which delegates to the actual addActionListener call
in the actual dialog's ButtonDialog base class).
- You will need to also consider which buttons should set
which result code, which buttons should hide and/or dispose
the dialog, and where validation happens.
For example, user input validation can be performed
inside the bean, controlling whether or not any
aggregated event is generated, or outside the dialog
by the code using the dialog, in which case the outside
code may wish to change the result mechanism back to no-result,
for example to ButtonDialog.NONE, if the dialog entries do not
validate. The event aggregator can decide, based on the
result code value after events return, whether to close
the dialog or not.
- Be sure to close the visible dialog by using a call to
hide() (or equivalently setVisible(false)),
and then perhaps dispose(),
at the point in the code where the dialog is supposed to disappear.
Typically you would do this inside the code of your dialog
class, in response to the OK or Cancel button events, unless
the client code vetos the forwarded events, which it
could do, for example, by setting the result code back to
zero, to indicate "none".
See the processActionEvent() method in
borland.jbcl.control.ButtonDialog
for an example of doing this with vetoable events.
When using one of these bean-wrapped
dialogs, you must set the frame property before
calling show(), because the real Dialog
inside the bean is constructed, using the frame
property as parent, when show() is called.
If you haven't already set the frame property,
calling show() will result in an exception.
If the dialog is modeless, the call to its show()
method returns as soon as the dialog is shown, it does not
wait for the dialog to be closed by the user. Code that uses
a modeless dialog must listen to the aggregated
actionPerformed event, or other events you
may surface, to know when to respond to user action
on the dialog.
If the dialog is modal, you can either use the
same approach using events to detect when the user
has pushed a dialog button, or you can use a simpler
mechanism (if the dialog itself validates the user input
before closing) of just waiting until the return from
the show() method to check the result
code and any property values and act on them. In a modal dialog,
show() does not return until the user closes the dialog.
(Actually, it returns after the dialog code calls hide()
or dispose(), which typically is done in the OK and
Cancel button handlers.
About JavaBeans
What exactly is a JavaBean?
A JavaBean is a collection of one or more Java classes,
often bundled into a single .JAR (Java Archive) file,
that serves as a self-contained, reusable "component".
Anywhere you see the word "component" in the JBuilder
environment or documentation, it is a shorthand or
alternate word for a JavaBean. JBuilder uses
the JavaBeans model for components.
A JavaBean might be a piece of user interface,
or a non-UI component such as a data module or
computation engine.
Any JavaBean can be added to the JBuilder Component
Palette, and from there it can be dropped into
other classes, as a subcomponent, using the JBuilder
designers.
The absolute minimum requirements for a JavaBean
are:
- It must be a public class, named the same
as its .java file name.
- It must have a public parameterless constructor
(no parameters).
Meeting these two requirements is sufficient to allow
your Bean to be placed on the JBuilder Component
Palette and dropped into your design.
To make the component useful, you will need to
give it useful code, an appropriate PME
(Properties, Methods, and Events)
programming interface, and perhaps a user interface.
JBuilder BeansExpress is the
fastest tool for building JavaBeans.
Why do I want a JavaBean?
For more detailed technical information
about JavaBeans, see:
Why do I want a JavaBean?
By packaging your component as a JavaBean, hiding
the implementation details inside the bean and
only exposing public Properties, Methods, and
Events (PME interface), a JavaBean has a number
of advantages, such as:
- It can be used by other developers using a standard published interface.
- It can be placed on the JBuilder component palette.
- Its Properties and Events will be accessible in the Component Inspector.
- It can be deployed in a .JAR file using the Deployment Wizard.
- It can be sold separately as a product.
- It can be updated with minimal impact on testing of other systems.
- A pure-Java component is cross-platform.
What does BeansExpress do for me?
What does BeansExpress do for me?
JBuilder BeansExpress gives you the fastest track to building JavaBeans.
This document gives you an overview of building JavaBeans, including:
- Quick Steps - a fast overview of the steps involved in building beans.
- About BeansExpress - an overview of how to use the BeansExpress samples and tools in JBuilder to build new beans in minimum time.
- BeansExpress tutorial - a walkthrough of building and deploying JavaBeans from scratch.
- About JavaBeans - links to additional information about JavaBeans.