[Contents] [Previous] [Next] [Index]

## Chapter 4
Using Java Objects as Components

This document describes how to use Java objects as Netscape ONE components when building applications in Visual JavaScript (VJS). You import Java objects into the VJS palette as components, and use the components to build applications.

Java objects that can be used as components in VJS include:

- Existing Java applets
- Applets implemented as JavaBeans
- Java objects created using the JavaScript new operator (i.e., LiveConnect objects)

This document includes the following sections:

- Using Java Objects
- Using Existing Applets
- Creating and Using JavaBeans Components
- Using the Built-in Database Components

## Using Java Objects

Each type of Java object has advantages for incorporation into a VJS application. For example, the advantage to using an existing Java applet is that you can incorporate many such applets into VJS applications without modification.

The advantage to using an applet implemented as a JavaBeans component is that it includes a `BeanInfo` class that describes the applet's properties, methods, and events. VJS uses `BeanInfo` class information to display information about the object at design time. If an applet does not provide optional `BeanInfo` information, VJS supports automatic introspection to determine metainformation about the applet. Providing this information enables developers to integrate the Java object into applications more easily.

Finally, for hidden components, those without user interfaces, the JavaScript `new` operator provides a way to use components implemented in Java, including JavaBeans, that are described using JavaScript Bean (JSB) files. Creating a JavaScript component using JSB files is described in Creating JavaScript Components. The JSB file structure and the syntax of its tags is described in JSB File Structure Reference.

## Using Existing Applets

Most applets written with JDK 1.1 can be used without modification in VJS. You can embed an applet in a VJS page by:

- importing pages from an existing web site.

- creating an applet tag manually.

Some applets you intend to use as hidden components in VJS may require minor modification to ensure that the applet does not use JavaScript or JSB reserved words as variable or object names.

### Importing Pages

For explicit directions on importing and installing a page containing an applet into VJS, see the VJS Developer's Guide. The page can be local or remote. VJS reads the HTML page and adds any directly referenced files to the current VJS project file. Files added to the project include the `CLASS` file specified in the `CODE` attribute of the `<APPLET>` tags that appear on the page.

> NOTE: If an applet depends on other `CLASS` or support files that are not directly referenced on the HTML page, these files are not automatically imported. You must repeat the import command for each of these extra files, and you must set the `<APPLET>` tag's `FILEREFS` attribute to list these files. `FILEREFS` is a quoted string consisting of a comma-delimited list of files. As the applet component is used in applications and deployed, VJS uses the list of files to ensure that the applet's support files are also used and deployed. §

After import, you can edit the `FILEREFS` attribute directly, if necessary. Ordinarily you should not need to edit the attribute, but sometimes, such as when working with graphics files, you may want to change the file list.

### Creating an Applet Tag by Hand

Instead of importing a page containing an applet into a VJS project, you can create an applet tag by hand. In this case, you must import the applet's `CLASS` file into the project. If the applet also depends on other `CLASS` or support files, you must repeat the import command for each of these extra files, and you must set the `<APPLET>` tag's `FILEREFS` attribute to list these files. `FILEREFS` is a quoted string consisting of a comma-delimited list of files. As the applet component is used in applications and deployed, VJS uses the list of files to ensure that the applet's support files are also used and deployed.

## Creating and Using JavaBeans Components

JavaBeans is a component architecture model, based on the Sun Microsystems JavaBeans specification. The model describes a component as a related set of Java classes, including a `BeanInfo` class that describes the properties, methods, and events associated with the component. This section of this document explains how to incorporate a JavaBeans component into a VJS project, but it does not describe the actual implementation of a JavaBeans component. The JavaBeans specification can be found at http://splash.javasoft.com/beans. VJS supports JavaBeans components developed with JDK 1.1.

> NOTE: Because the most widely used browsers do not fully support JDK 1.1 and AWT 1.1, it's best to develop applications that do not depend on features specific only to JDK 1.1 and AWT 1.1. Instead, build applications to comply with JDK 1.0.2 and AWT 1.0 functionality.

A JavaBeans component usually provide a `BeanInfo` to permit inspection. If the `BeanInfo` `getEventSetDescriptors`, `getPropertyDescriptors`, or `getMethodDescriptors` methods returns `null`, VJS uses automatic introspection to determine this metadata. Reflection is also employed to find `set` and `get` methods in accordance with the JavaBeans naming conventions if a property descriptor does not provide this information.

> NOTE: Web browsers do not support embedding of serialized JavaBeans in a page. Navigator and Communicator, however, do permit placing JavaBeans properties in `<PARAM>` tags inside `<APPLET>` and `<OBJECT>` tags.

Some JavaBean components you intend to use as hidden components in VJS may require minor modification to ensure that they do not use JavaScript or JSB reserved words as variable or object names.

### Adding a JavaBeans Component to VJS

To use a JavaBeans component to build VJS applications, follow these steps:

1. Package the JavaBeans component and all of its supporting files into a JAR file. To create a JAR file, see Packaging a Component. VJS supports both compressed and uncompressed JAR files.

2. Import the JAR file containing the JavaBeans component to a VJS palette. Importing the component to the palette creates an `<APPLET>` tag with a `FILEREFS` attribute referring to all the files in the JAR. This ensures that supporting files are deployed with the component. For explicit directions on importing and installing components, see the VJS Developer's Guide.

> NOTE: After import, you can edit the `FILEREFS` attribute directly, if necessary. Ordinarily you should not need to edit the attribute, but sometimes, such as when working with graphics files, you may want to change the file list.

### Working with Bean Customizers

If a JavaBeans component defines a customizer interface, then when you import the bean into VJS as a component, VJS instantiates its own copy of the customizer. This enables you to edit component properties in the VJS Inspector using the custom interface defined by the customizer. When you open the VJS Inspector, it brings up the custom interface.

Edits you make in the VJS inspector are automatically passed back to the JavaBeans customizer class, and VJS itself is updated to reflect the changes.

### Using a Hidden JavaBean Component

You can implement a VJS application that uses hidden JavaBeans components. A hidden component is one that is not exposed at all in the application's run time interface, and that is not directly accessed in application code, or that is only partly exposed and accessed.

To use a hidden JavaBean component that has no run time interface:

1. Put the JavaBean component and its support files in a JAR file.

2. Install the JAR file into the VJS palette.

During the installation process, VJS automatically creates a JavaScript Bean (JSB) file that "wraps" the JavaScript component. This script is based on both the component's `BeanInfo` and introspection, which are used to determine the component's properties, events, and methods.

The JSB file that is created defines a script that loads the component at run time; VJS also installs a script icon on the palette for the component. At design time, you can drag the component to a page. If you attempt to view the component's properties, events, and methods in the Inspector, the Inspector displays only the script that is called to load the actual component at run time.

> NOTE: Icon images are not transferred from the JavaBeans component during script creation, nor is it possible to use a customizer with a hidden component. The help URL, however, is copied from the `BeanInfo` to the JSB, so component help can be displayed from the palette.

### Augmenting a Java Bean

To use a JavaBeans component and add additional functionality to it, create a JavaScript Bean (JSB) file that "wraps" the component. In the JSB, you must implement JavaScript functions that parallel the JavaBeans component's properties, methods, and events that you want to expose, and you must also implement additional properties, methods, and events that you want to use to enhance the Java Bean functionality. The JSB instantiates a Java object to access the JavaBeans component functions. Java objects properties, methods, and events that are not implemented in the JSB remain hidden from the user at design and run times.

For example, the following code fragment illustrates how a VJS application might use the `netscape.javascript.adapters.PropertyChangeAdapter` class to access and change Java object properties:

    function JavaCursor2_java_beans_PropertyChange(oEvent)
    {
       if (oEvent.getPropertyName() == "Product")
       {
          document.JavaDummyCursor2_form._Product.value
             = oEvent.getNewValue();
       }
       ...
    }
    ...
    JavaDummyCursor2_java_beans_PropertyChange.onChange =
       JavaDummyCursor2_java_beans_PropertyChange;
    JavaDummyCursor2PropertyChangeAdapter = new
    Packages.netscape.javascript.adapters.PropertyChangeAdapter
       (JavaDummyCursor2_java_beans_PropertyChange);
    JavaDummyCursor2.addPropertyChangeListener(JavaDummyCursor2PropertyChangeAdapter);

> NOTE: When you wrap a Java object in a JSB, you should make sure that the attributes of any properties and methods used in the JSB do not duplicate JavaScript and JSB reserved words. For example, do not define a property named `SRC` in the JSB because it will conflict with the `<JSB_CONSTRUCTOR>` `SRC` attribute.

## Using the Built-in Database Components

VJS provides a set of simple JavaBeans components that deliver database functionality. These components, and any third-party components that interact with them, use two standard interfaces: the `Row` interface, and the `Table` interface. These interfaces use standard JavaBeans conventions. They are designed to work with the JavaBeans `PropertyChange` mechanisms. These interfaces define a protocol that is bidirectional, It enables Java and JavaScript components that implement the interfaces to be connected on an HTML page using VJS.

The `Row` interface is used to define and transfer a set of name and value pairs, such as one row of a database table. This interface could be used, for example, to connect a cursor object with a form object that displays one row of data at a time. The interface has two parts: one to specify the number of columns, their names and their types; and another to manage the changing and transferring of data.

The `Table` interface is used by two components to exchange an entire collection of data. For example, a cursor and a spreadsheet component could use the `Table` interface to exchange data.

These interfaces, and various components that implement them (`JavaDummyCursor`, `JavaForm`, `DummyCursor`, `TableApplet` and `ClientCursor`) are provided as examples in the CDK `samples` directory.

> NOTE: There are not different interfaces for data providers and data consumers. The same interface is used to send and receive data. This reduces the number of interfaces, adapters and support classes in the system.

### Data Contexts

Even though the same interface is used for receiving and sending data, the `Row` and `Table` interfaces behave differently depending on their roles. In addition to the sender and receiver roles, each of these interfaces acts in a data context, either as a consumer of data, or a provider of data. Data context refers to the number and names of available columns, the number of rows, the current row, and the numbering of those rows. If two components are connected using the `Row` or `Table` event, one provides the data context, and the other consumes it.

For example, assume that a cursor is connected to a spreadsheet component, and that the spreadsheet component is also connected to a form component. The cursor is the data-context provider, and the spreadsheet is the data-context consumer. By connecting to the cursor, the spreadsheet inherits its data context, which it in turn provides to the form. Note that the spreadsheet is both a consumer and provider, and that a component's role in terms of data context has nothing to do with the direction of the data transfer.

### Support Classes

Two Java classes, `RowSupport` and `TableSupport` are provided as support for the `Row` and `Table` interface components. These classes make it easy to implement the `Row` and `Table` interfaces in a JavaBeans component. The classes are similar in nature to JavaBeans adapters, but have slightly different uses.

These classes are generic support classes that are used by the `JavaDummyCursor` and `JavaForm` examples. Like the `PropertyChangeSupport` class in the Bean Developer's Kit (BDK), they can be used as members to which `Row` and `Table` methods may be delegated. It is also possible to extend these classes, provided, of course, that the JavaBeans does not already extend some other class.

An additional use of these classes is to server as helper objects for JavaScript components. In order to connect to Java objects, the `DummyCursor` JavaScript object employs an instance of `RowSupport` (created by using the JavaScript `new` operator) to hold its current row's data, and to manage the event interactions with Java objects. Without such an object, this a connection would not be possible.

[Contents] [Previous] [Next] [Index]

Last Updated: 11/20/97 13:56:35

Copyright © 1997 Netscape Communications Corporation