Table of Contents

1.0 Update to "Setting up class libraries or beans for integration" task file
2.0 Update to "Setting up a tool for integration" task file

1.0 Update to "Setting up class libraries or beans for integration"

The following information replaces the "Setting up class libraries or beans for integration" section in the task information for the External Tool Integration component of VisualAge for Java.

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 Integrated Development Environment once the Integrated Development Environment is restarted, and the features have been added to the workspace

The steps to set up features for integration into the Integrated Development Environment are as follows. 

1. Create a subdirectory for the feature. This subdirectory is called the base directory.
2. In the Workbench, create a project that contains the classes and associated resource files for the feature. Version the project and export the project to the base directory.
3. Create a control file in the base directory that provides the Integrated Development Environment with details about the integration. 
4. Create additional control files in the base directory for other supported languages (optional). 
5. Restart the IDE and add the feature to the Workbench.

The following sections provides details about these steps.

Step 1. Create a base directory for the feature
Create the base directory for the feature like this:

X:\IBMVJava\ide\features\base_directory

where X: is the drive where VisualAge for Java is installed. 

The base directory name should be based on the complete package prefix for the class. 

When naming the base directory, replace the periods (.) in the package name with 
dashes (-). The following table shows two examples.

Each base directory can contain multiple packages. Unique base directory names distinguish features from each other.

Step 2. Create, version and export a project
Use the VisualAge for Java Workbench to create a project for the packages, classes, and resource files for the feature.

To add a project and its associated files to the workspace, perform the following steps:

1. Click the Projects tab in the Workbench. 
2. Click Selected > Add > Project. 
3. Use the Add Project SmartGuide to create the project. Name the project exactly as you 
   want it to appear in the user's workspace after the feature is installed. 
4. To add a package, right-click the project you created, and from the pop-up menu click 
   Add > Package. Use the Package SmartGuide to create the package. 
5. To add classes, right-click the package you created, and from the pop-up menu click
   Add > Class. Use the Add Class SmartGuide to create the classes. Alternatively, you can import code from outside VisualAge for Java using the Import SmartGuide. To open the SmartGuide, right-click the package you created, and from the pop-up menu click Import.
6. To add resource files to the project, click the Resources tab in the Workbench, and add the necessary resources to the project. 

After you finish developing the feature, version the project by doing the following:

1. Click the Projects tab in the Workbench. 
2. Right-click the project you created, and from the pop-up menu click Manage > Version. 

Once the project is versioned, export the project and its resources as a repository to the base directory for the feature by performing the following steps:

1. Click the Projects tab in the Workbench. 
2. Right-click the project you created, and from the pop-up menu click Export. 
3. In the Export SmartGuide, select Repository and click Next. 
4. In the Export to another repository page, select Local repository and in the Repository name entry field, type the following:
   X:\IBMVJava\ide\features\base_directory\projects.dat
   
   where X: is the directory where VisualAge for Java is installed, and base_directory is the name of the base directory for the feature.

The project and its resources are exported as follows:

X:\IBMVJava\ide\features\base_directory\projects.dat

X:\IBMVJava\ide\features\base_directory\projects.dat.pr\your_project\time_stamp\
your_resources

where your_project is the name of the project you exported, time_stamp date and time the project was versioned project, and your_resources are the resource files associated with the project.

Step 3. 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

Step 4. 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 Integrated Development Environment 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. In addition, a-f characters in \uxxxx format should be uppercased.

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 Integrated Development Environment to recognize feature updates.

Step 5. Restart the IDE and add the feature to the workspace
When the Integrated Development Environment starts, your feature is automatically integrated into the Integrated Development Environment as follows: 

All Java projects in the projects.dat file, and resources in the projects.dat.pr directory 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.$$$ so that the Integrated Development Environment will not encounter this problem every time it starts. As well, the Integrated Development Environment produces an error message that appears in the Log window. 

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. 

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

1. In the Workbench, select F2 to open the Quick Start window. 
2. Select Features > Add Feature and click OK. 
3. From the selection dialog, select the feature you would like to add to the workspace and then select OK. 
4. 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.
5. You can also add the feature from the Visual Composition Editor palette: 
   1. From the beans palette pull down menu, select Available... 
   2. In the selection dialog, select the feature to be added and then click OK.
   3. After a feature has been added, it can be deleted through the Quick Start window using Features > Delete Feature.

2.0 Update to "Setting up a tool for integration" help file

The following information replaces the "Action-Items (optional)" section of "Setting up a tool for integration" help file.

Action-Items (optional)

Overrides the default operation that occurs when the user selects the Open menu item or double-clicks on a resource file shown in the Resource page of the Project Browser. The entry includes the following:

• The menu operation name, such as OPEN. The menu operation name must be in uppercase, and must be in English, even in control files for other supported languages.
• The start_class to be invoked when the menu item is selected. Each start_class must be the fully-qualified class name. 
• A context type.