JavaBeans components

Before you begin creating your own components, you should understand what a JavaBeans component is. This chapter explains JavaBeans components, including:


What is a component?

A component is an object that can be used and tested as a unit, independent of the context in which the component is eventually used. The internal implementation of a component is completely hidden from the user.

JavaBeans components comply with the JavaBeans specification (at http://splash.javasoft.com/beans/), 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:

The component user's view of a component

To component users, a component is a self-contained, very specialized object that can be used for a specific purpose. It can also be used more than once and in more than one place within an applet or application. The component user expects few restrictions on how the component can be used. In a visual environment such as JBuilder, the user selects the component from the Component Palette and drops it into the application or applet.

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.

The component writer's view of a component

For a component writer, a component can do or be anything you can create in code, as long as it fits the JavaBeans specification. This manual explains how to write components that comply with the specification and work in JBuilder.

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 that it fits well in the JBuilder environment and so you can use them in other visual tools that support the JavaBeans standard.

The JavaBeans view of a component

At the simplest level, a component is any Java class that conforms to the JavaBeans component model. If a class follows the JavaBeans rules, it can work with JBuilder's visual design tools. A JavaBean has these characteristics:

Kinds of components

Because components can be almost any part of an object-oriented program, the terminology used to talk about them is often complex and confusing. In the JBuilder documentation we use several terms for components; sometimes the definitions of the terms overlap:

These component categories are discussed in greater detail below.

UI and non-UI components

All components are either UI (user interface) components or non-UI components. A UI component can draw something on the screen, becoming part of the user interface of the application. Buttons, text boxes, checkboxes, labels, and image components are all UI components. Whether the component actually shows something on the screen at runtime is unimportant. It is simply the component's ability to paint to the screen that classifies a component as a UI component.

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.

Menu components

Menu components are a special case. They are UI components, but they appear on the Component Tree, not the UI Designer. Once you drop them in your applet or application, double-click the component in the Component Tree to display the Menu Designer. Using the Menu Designer, you can visually build the menus for your application.

Composite components

JBuilder's JavaBeans controls use a model-view architecture. Besides the controls represented on the JBuilder Component Palette, JBCL provides a collection of models (data containers), views (the core of composite components), item painters (objects that display the data), item editors (objects that permit data values to be changed), and view managers (objects that select item painters and editors). You can use them in building your own components.

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 JBuilder's controls are composite components.

Controls

UI components are often referred to as controls. In fact, on JBuilder's Component Palette is a tab labeled "Controls". These controls are complete UI components, able to become part of the user interface of an application.

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 requirements of the JavaBeans component model

The JavaBeans component model specification was developed as a coordinated effort between Borland, Sun, and others to establish a platform-neutral component model API. JBuilder recognizes components that conform to the JavaBeans specification and incorporates them into its integrated development environment. To effectively create JavaBeans components within JBuilder's environment, you must understand how components conform to and can extend the JavaBeans specification.

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://splash.javasoft.com/beans/.

The following are the most significant requirements for components:

In addition to these requirements, the JavaBeans specification at http://splash.javasoft.com/beans/ provides guidelines to help you to write well-designed components that interact well with other Java components.


The parts of a component

Designed to work with visual design tools like JBuilder, components typically have public properties, methods, and events available to component users.

Component properties

Properties allow the component user to change the state of a component. They provide the illusion of setting or reading the value of a variable in the component while hiding the internal implementation. By creating a property, the component writer can allow access to the state of the component without exposing the underlying data structure.

Using properties in components has a number of advantages:

A property must have appropriately named accessor methods defined in the component. It need not have a class data member 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.

Component methods

Component methods encapsulate the behavior of the component. They are standard Java methods which can be called from other components. Component methods are available at runtime only.

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. Do not include the data type of arguments in the method name. Instead name methods and arguments so that the method signature provides a complete but non-redundant description of the action. For example, void paste(Image) tells you everything you need to use this paste() method. By contrast, void pasteImage(Image) is redundant and visually confusing.

Component events

Events allow components to receive input and feedback from the user at runtime. They connect occurrences in a component (such as mouse actions, keystrokes, and property state changes) with the code written by component users (event listeners). The JavaBeans specification defines rules that allow components to both generate and respond to events within a program. A component that generates events is a source component; a component that responds to event occurrences is a listener.

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:


Introducing the JavaBeans Component Library

JBuilder comes with a set of predefined components called the JavaBeans Component Library (JBCL), which follow the JavaBeans model. JBCL contains six packages:

The control package

The control package contains complete UI components, including controls, dialogs, and containers. Most of JBCL's UI components are located here. Many JBCL controls have an AWT parallel component that, at first glance, appears to provide identical functionality. There are important differences, however. Many JBCL If your program would benefit from these advantages, you should choose a JBCL control. Alternately, if you are writing a very light-weight 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

The dataset package

The dataset package contains non-UI components that provide database connectivity. These components work together with JBuilder's data-aware UI controls to allow visual development of database applications.

The layout package

The layout package contains layout manager and constraint classes. When you choose a container from the Component Palette, it has a default layout. If the layout isn't what you want, you can specify another layout as the value of the layout property using the Component Inspector.

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.

The model package

The model package contains model interfaces and classes for building composite components. JBCL's model-view architecture separates user-interface and background behavior from information about the data itself and screen rendering.

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 util package

The util, or utility, package contains classes and interfaces of general utility, such as interfaces containing groups of constants.

The view package

The view package contains all the views used by the JBCL control package. It also contains a few views that don't have a direct control counterpart. For example, HeaderView and ColumnView are both used in the GridControl and both are in the view package.

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 and image and a string for each data item in the model, you could use a CompositeItemPainter, which is constructed with one ImageItemPainter and one TextItemPainter.