JavaBeans components comply with the JavaBeans specification (at http://www.javasoft.com/beans/docs/spec.html), which contains the design goals, rules, and naming standards for a JavaBeans component. Any discussion of components in JBuilder refers to JavaBeans components. A JavaBean, or simply a bean, is a JavaBeans component.
Components are the building blocks of JBuilder applications. Although many components represent visible parts of a user interface, components can also represent nonvisual elements in a program, such as timers and databases.
There are three ways to view components:
Before you attempt to write components, we strongly recommend that you become familiar with the existing components in JBuilder. If you adopt the model-view architecture used by the JBCL components, you'll be using a flexible and powerful style of component writing.
Defining the limits of component writing is much like defining the limits of programming. We can't tell you every kind of component you can create, any more than we can tell you all the programs you can write. What we can do is tell you how to write your code so it fits well in the JBuilder environment and so you can use them in other visual tools that support the JavaBeans standard.
These component categories are discussed in greater detail below.
UI components must always extend some class that is capable of drawing to the screen. Ultimately, they all descend from java.awt.Component. Usually you should extend an existing component to be certain that you implement all the methods that the JavaBeans model requires.
Non-UI components, in contrast, can extend any appropriate class. They must simply obey the basic rules for components: they have a public parameterless constructor and properly named and constructed accessor methods for properties and events they surface at design time.
Non-UI components provide encapsulated functionality to the user interface, generally by interacting with UI components. They have no ability to paint anything to the screen. At design time, non-UI components appear in the Component Tree, rather than in the UI Designer. Users select the non-UI component in the Component Tree to manipulate the component's properties and events.
The Database component is an example of a non-UI component. It becomes a part of an application, but is never visible to the user of the application. The Database component, like all non-UI components, never draws anything on the screen.
When you work with a non-UI component, you can drop them on the UI Designer or the Component Tree, but they appear the Component Tree only, not on the UI Designer.
The purpose of the model-view architecture is to separate the representation of data from the model itself and allow for multiple views of the same data. Components that instantiate these model-view classes to perform their work are often referred to as composite components. Most of the JBCL controls on JBuilder's Component Palette are composite components.
Some of JBuilder's standard components have the term "control" as a part of their names (for example, TreeControl in borland.jbcl.control). These composite components are so named to distinguish them from the model-view classes that have similar names. In most cases, the class with "control" in its name is the complete component that can be used to design visually, and which has been developed from the view component of the same name. The "view" is the corresponding view class of the control, and it is used for developing original composite components. For example, the TreeControl is based on the TreeView class.
See also:
Overview of component writing
Understanding model-view architecture
The JavaBeans component model is a specification for how to code components. Components that comply with this specification work in JBuilder's visual environment. JBuilder parses the component code and makes its properties and events available in the Component Inspector. The complete component model specification is available in the JavaBeans specification at http://www.javasoft.com/beans/docs/spec.html.
These are the most significant requirements for JavaBeans; you will find more detailed information in the sections that follow :
public FtpRequestDialog();
Property accessor methods must have a specific signature. The read method must take no parameters and return an object of the type identical to the property type. For boolean properties the read method begins with the word "is"; for all other properties the read method begins with the word "get".
The write (or set) method must take a single parameter identical to the property type and return void. For example, the component property background (which contains the state of the component's background color) would have accessor methods with the following signatures:
public Color getBackground(); public void setBackground(Color color);Properties can have multiple write accessor methods, but they must have one with the signature shown here. Any overloaded methods are simply component methods for programmatic access to the property. They do not appear in the Component Inspector.
To read more about the details of property specification, see Creating properties.
public void add<event>Listener(<event>Listener <listener>) throws TooMayListeners;The add listener method for multicast events is the same, except that it does not throw the TooManyListenersException:
public void add<event>Listener (<event>Listener <listener>);Both unicast and multicast use the same form of the remove listener method:
public void remove<event>Listener(<event>Listener <listener>);
For example, the following is a declaration for an addSelectionListener() method:
public void addSelectionListener(VectorSelectionListener listener)When a container calls addSelectionListener(), the container is registered with the source component that defines the method as a listener of vector-model selection events.
Events and event registration methods are explained in more depth in Working with events.
In addition to these requirements, the JavaBeans specification at http://www.javasoft.com/beans/docs/spec.html provides guidelines to help you to write well-designed components that interact well with other Java components.
If the component you are writing fails to follow the JavaBeans specification and is therefore not a valid JavaBean, it appears as a red square within the UI Designer. If you see a red square in place of your component, examine the component's source code to discover why it isn't a valid bean. Or you can use BeanDoctor to help you find the problem. For more information about BeanDoctor, see Creating JavaBeans with BeansExpress.
Using properties in components has a number of advantages:
Properties take advantage of the full power of JBuilder's UI Designer. The component user can change the state of a component (by setting a property value) and immediately see the effects of that change on the program. By default, all of a component's public properties are available to other components, but you can control design-time access to component properties by using the optional BeanInfo interface to specify which properties should be exposed.
You can include complex functionality in a property's accessor methods. Component users need never know about the details; they only make the setProperty() or getProperty() method call. A property that looks like a simple number can actually be a lengthy calculation or a lookup in a database. Your component users don't have to deal with that complexity.
You can have the accessor method notify other objects or call other methods whenever a property is set or read. The accessor method can encapsulate all kinds of complex behavior for a component; all the component user needs to know is how to make a method call.
A property must have appropriately named accessor methods defined in the component. It need not have a class data member (or field) associated with it, as sometimes there isn't a one-to-one relation between a component class data member and a given component property. For example, the following code fragment defines a component property called shadowColor:
public class MyComponent extends BevelPanel { private int redValue; private int greenValue; private int blueValue; public int getShadowColor() { return redValue | greenValue | blueValue; } public void setShadowColor(int color) { redValue = color & 0xff0000; // class data members greenValue = color & 0x00FF00; blueValue = color & 0x0000FF; } }Although MyComponent has no actual class data member named shadowColor, the property is correctly defined because of the two accessor methods, getShadowColor() and setShadowColor(). These methods write and read three variables and calculate a value for the property. Although it's common for a component property to set a variable with the same name as the property itself, it is not required. The component property must merely have correctly declared property accessor methods for the property to be valid.
Creating properties explains how to add properties to your components.
There are few restrictions on what component methods can do, but you should make every effort to ensure that your methods are as intuitive as possible. Name your methods so that the purpose of the method is obvious. Avoid preconditions on method use. If you must have preconditions on a method call, build in tests to validate that conditions are met and provide exception handling for situations where a method call is inappropriate.
Take care in the naming of methods to make your components easier to use. Choose the shortest descriptive name. Avoid abbreviating method names. Remember, too, that methods are actions. If you find yourself creating many methods that have no verbs in their names, consider creating properties instead.
If a component's code complies with the JavaBeans rules, JBuilder recognizes the component's events and displays them in the Component Inspector.
Event source components have registration methods, which are similar in naming patterns to the accessor methods of properties. Working with events explains how to add standard event sets or event sets you define yourself.
Standard Java events are grouped on listener interfaces (and, in some cases, on source interfaces). These are the standard event sets and their events:
If your program would benefit from these advantages, you should choose a JBCL control. Alternately, if you are writing a very lightweight program, such as an applet with a single specific use for a user-interface component, you might prefer the AWT component because of its smaller download requirements.
See also:
Understanding model-view architecture
As you add components to the container, JBuilder creates constraints objects to manage their layout constraints, based upon the layout manager of the container.
For details on how to work with layout managers, see Using layout managers.
There are four types of models in JBCL:
JBCL has interfaces for each of these models. In every case, the interface named "Model", as in VectorModel, provides read-only access to the data. For each model, JBCL also has a "WritableModel" interface that extends the read-only interface and adds write access to the data. For example, MatrixModel is an interface that provides read-only access to tabular data while WritableMatrixModel provides read-write access to that same type of data.
The model package also contains two view manager interfaces and classes.
See also:
Understanding model-view architecture
The view package also contains several item painters and item editors. Some of these are used by JBCL controls and others are provided for your convenience. Some of the item painters and editors are wrappers. For example, if you want to display an image and a string for each data item in the model, you could use a CompositeItemPainter and set it up with a nested ImageItemPainter and a nested TextItemPainter.
The sql.dataset package includes the following types of functionality:
Connection | Login to remote data servers through JDBC, and handling of connection events |
Providing | Obtaining data from the remote database through SQL statements or stored procedures |
Resolving | Updating of data from the local DataSet back to the original source of the data |
At first, these JBCL components can seem quite complex. After you understand the model, view, painter, and editor parts of a component, you will see that they have their own simplicity and elegance. You can customize such a composite component by modifying one or more of the parts and plug it into place. Using the new model-view component architecture, you have many options available to you to customize the component, your component can display and edit any type of data, and viewing large amounts of data is very fast.
To read more about the model-view component architecture, see Understanding model-view component architecture. Then read Writing a composite component, which describes how the ListControl component was written, preparing you to write your own model-view components.
A goal of the AWT was to preserve the look-and-feel of each platform it ran on, yet to maintain a platform-independent API. The designers of the AWT created an API that could be used on all platforms, but the implementations of the API were platform-specific. These platform-specific implementations are called peers.
Previously, when you wanted to create a new component, you had to subclass java.awt.Canvas or java.awt.Panel. All JBCL components used one of the AWT classes, so if you built your applications using JBCL components, you were still subclassing one of these two classes. Components that extend these classes own their own native, opaque windows. These native windows, the peers, exist along with the components you are creating. In essence, creating one component using this peer model consumes the resources of two.
Java classes that have a native window are heavyweight, because they make additional demands the on operating system. They are also opaque so that a window onscreen covers any other windows behind it; you can't "see through" such windows.
Lightweight components extend java.awt.Component and java.awt.Container classes instead. The result is that these components no longer have native windows associated with them. Because they don't require native data structures or peer classes, they are indeed "lighter" in their consumption of resources. Also, lightweight components need not be opaque. They can have transparent parts if their paint() methods do not render these areas.
All of JBuilder's JBCL components are now lightweight; they extend com.sun.java.swing.JComponent, which extends java.awt.Container. If you used the JBCL components on Component Palette in a previous version of JBuilder, you don't need to make any changes to your code.