Setting Up Class Libraries or Beans for Integration

An external class library or set of beans can be set up any time after VisualAge for Java has been installed. In VisualAge for Java, the external class libraries or beans are also called features. After features have been set up, they become visible within the IDE once the IDE has been restarted.

The high-level steps to set up classes for IDE integration are:

  1. Create a subdirectory for the classes, called the base directory.
  2. Copy all related files into the base directory.
  3. Create a control file that provides the IDE with details on the integration.
  4. Create additional control files for other supported languages. (optional)

Create a Subdirectory for the Feature

Create a subdirectory from the ide/features directory. This will be the base directory for the feature. The subdirectory name should be based on the classes' complete package prefix. When naming the subdirectory, replace the periods (.) in the package name with dashes (-). The following table shows two examples.

Complete package prefix Base directory for class library
com.dingbat.widgets com-dingbat-widgets
abc.enterprise.databuilder abc-enterprise-databuilder

Unique base directory names distinguish features from each other.

Copy Related Files to the Base Directory

Two files are required to enable the Feature Integrator facility: projects.dat and default.ini.

The file projects.dat is a VisualAge for Java Version 2.0 repository that must contains Java projects. Only one versioned edition of each project can be included in the repository. You can create this file by importing the classes into an existing IDE project and then exporting the project as a repository (.dat) file. This ensures that the class data available at load time is compiled. Given bytecodes, the IDE can perform optimizations that reduce footprint and increase performance for importing and loading.

The file default.ini is the control file, and is described in the following section.

Resource files associated with the feature can be optionally provided. Follow these steps when providing resource files:

  1. Create a subdirectory called project_resources under the feature base directory.
  2. Under the project_resources directory, create a subdirectory for each project in the feature, with the same name as the project. The resource files should be copied under each project subdirectory, provided as expected by the referencing Java code.

When the feature is integrated with the IDE, all subdirectories of project_resources are copied into ide/project_resources, overwriting any project resource files that have the same names.

Create a Control File

Create a control file, named default.ini, and copy it into the base directory. The control file provides integration information to the IDE. This file must be a flat ASCII file, cannot include blank lines, and must follow this format:

Name=<feature_name>
Version=<feature_version>
Help-Item=<menu_text>,<HTML_filename>
Palette-Items=<category_group>[;...]
	<category_group>=<category_name>,<class_name>[,<class_name>...]
Prereq-Features=<base_directory>[< base_directory>]

Parameter values cannot be delimited by quotation marks. In addition, commas (,) and semi-colons (;) cannot be used except when delimiting parameter values, as specified in the syntax above. Only the Name and Version entries are mandatory; all other entries are optional.

Name
Identifies the integrated feature by name. The name can be any sequence of alphanumeric characters and punctuation (except commas, semi-colons, and colons), and should not exceed 40 characters in length.
 
Version
Specifies the released version of the feature. Feature versions should not be confused with the versioned edition names of projects and packages in the repository file, as there is no relationship between them.
Help-Item (optional)
Identifies a Help menu entry with the supplied menu text, linking to the main HTML file for the feature. The URL for the file is relative to the feature's base directory.
Palette-Items (optional)
Lists bean categories and their corresponding beans that will be added to the Visual Composition Editor beans palette. Beans in the same category should be separated by commas, while each category should be separated by a semi-colon (;).
 
Prereq-Features (optional)
Specifies one or more features that are prerequisites of this feature. A prerequisite feature is specified by its base directory name. Prerequisite features are loaded when this feature is loaded. After the feature has been unloaded, however, prerequisite features must be unloaded separately.

Examples of Control Files

Example 1. Class Library Integration with Help

Name = Factory API
Version = 3.0
Help-Item = Factory API, index.html

Example 2. Class Library Integration with Help and One Palette Category

Name = Factory API
Version = 3.0
Help-Item = Factory Beans, beans.html
Palette-Items = Factory, com.factory.Generator1,com.factory.Generator2

Example 3. Class Library Integration with Help and Two Palette Categories

Name = Factory API
Version = 3.0
Help-Item = Factory Beans, beans.html
Palette-Items = Factory1, com.factory.Generator1,com.factory.Generator2; Factory2, com.factory.Mulcher1, com.factory.Mulcher2

Create Control Files for Other Supported Languages (optional)

Create a control file for each language you want to support, and place these files into the base directory. To name these control files, follow the Java naming convention for locale support: <language>[_<country>].ini. For example, en_GB.ini would be the name of the British English control file, and fr.ini would be the name of the French control file.

When determining which control file to use, the IDE follows this sequence, using <language> and <country> values for the default locale:

  1. Find the file <language>_<country>.ini
  2. Find the file <language>.ini
  3. Find the file default.ini

All control files must be in flat ASCII format, although parameter values can use non-ASCII Unicode values with \uxxxx notation.

Even if language-specific control files are supplied, a default.ini file must always be supplied. As well, only a change in the timestamp of default.ini can trigger the IDE to recognize feature updates.

Feature Setup at IDE Startup

  1. All Java projects in the feature's projects.dat file are copied to the repository.

    If a problem occurs in either copying the feature to the repository or adding it to the workspace, the feature's default.ini is renamed to default.$$$ in order that the IDE will not encounter this problem every time it starts. As well, an error message is produced.
  2. If the feature includes a project_resources directory, all subdirectories of this directory are copied to ide/project_resources. Any existing files in ide/project_resources with the same name are overwritten, so take care when naming your resource files.
  3. Information from the default.ini is saved in the workspace registry of installed features.

If a feature is successfully installed, all feature files still remain on the file system. This way, the feature can be easily re-loaded if the workspace needs to be changed or is corrupted.

Adding a Feature to the Workspace and Visual Composition Editor Palette

Once a feature has been successfully integrated, you must still add it to the workspace in order to use it.

  1. From the IDE, select F2 to bring up the Quick Start window.
  2. Select Features > Add Feature and select OK.
  3. From the selection dialog, select the feature you would like to add to the workspace and then select OK.

The feature is now added to the workspace and any beans specified in a control file Palette-Items entry appear on the Visual Composition Editor palette.

You can also add the feature from the Visual Composition Editor palette:

  1. From the palette pulldown, select Available...
  2. From the selection dialog, select the Feature to be added and then select OK.

After a feature has been added, it can be deleted through the Quick Start window.


External Class Integration


Setting Up a Class or Bean for Integration
Updating and Removing Integrated Tools and Classes