Setting Up a Tool for Integration

A user-defined tool can be set up any time after VisualAge for Java has been installed. After the tool has been set up, the tool becomes visible from within the IDE once the IDE has been restarted.

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

  1. Create a subdirectory for the tool, called the base directory.
  2. Copy all application classes, resource files, and HTML help 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 Tool

Create a subdirectory from the ide/tools directory. This will be the base directory for the tool. The subdirectory name should be based on the tool's 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 tool
com.dingbat.widgets com-dingbat-widgets
abc.enterprise.databuilder abc-enterprise-databuilder

Unique base directory names distinguish integrated tools from each other.

Copy all Tool Files into the Base Directory

Copy all class files and resource files into the base directory, ensuring the appropriate subdirectory structure is maintained. You can build the tool itself in the IDE and export the class files to the tool base directory.

In addition, copy any tool documentation files (HTML) into the base directory.

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=<tool_name>
Version=<tool_version>
Help-Item=<menu_item_text>,<HTML_filename>
Menu-Group=<menu_group_text>
Menu-Items=<menu_item_group>[;...]
	<menu_item_group>=<menu_item_text>,<start_class>,<context_type>
Quick-Start-Group=<Quick_Start_category>
Quick-Start-Items=<Quick_Start_group>[;...]
	<Quick_Start_group>=<Quick_Start_text>,<start_class>

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 tool 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 tool.
 
Help-Item (optional)
Identifies a Help menu entry with the supplied menu text, linking to the main HTML file for the tool. The URL for the file is relative to the tool's base directory.
 
Menu-Group (optional)
Indicates that all menu items are to be placed in a submenu, and specifies the name of the submenu.
 
Menu-Items (optional)
Lists one or more menu items. Each menu item includes the text appearing on the menu, the class to be invoked when the menu item is selected, and an optional context type. The context type must be one of "-P" (project), "-p" (package), "-c" (class). If a context type is provided, the menu item is accessible from the Selection menu when that context has been selected. If no context type is provided, the menu item represents a general workspace action (accessible from Workspace > Tools). Each start_class must be the fully-qualified class name.
 
Quick-Start-Group (optional)
Indicates that all Quick Start entries are to be placed under the specified Quick Start category. If multiple tools specify the same Quick_Start_category, they appear in the same Quick Start category. If no category is specified, all Quick Start item entries are automatically placed in a default tools Quick Start category.
 
Quick-Start-Items (optional)
Lists one or more Quick Start items. Each item includes the text displayed in the Quick Start window, and the class to be invoked when the item is selected. Each start_class must be the fully-qualified class name.

A tool can be invoked from both the Tools menu and the Quick Start window.

Examples of Control Files

All examples below assume that the directory ide\tools\com-whammo exists, and includes all required files.

Example 1. Menu Integration

Name = Whammo Formatter
Version = 2.0
Menu-Items = Whammo Formatter,com.whammo.WStart1,

Example 2. Menu Group and Help Integration

Name = Whammo Formatter
Version = 2.0
Menu-Group = Whammo
Menu-Items = Run All,com.whammo.WStart1, ; Run on Selected Classes,com.whammo.WStart2,-c
Help-Item = Whammo Formatter,index.html

Example 3. QuickStart Integration

Name = Whammo Formatter
Version = 2.0
Quick-Start-Items = Run All,com.whammo.WStart1; Configure,com.whammo.WStartConfig

Example 4. QuickStart Group and Help Integration

Name = Whammo Formatter
Version = 2.0
Quick-Start-Group = Whammo
Quick-Start-Items = Run All,com.whammo.WStart1; Configure,com.whammo.WStartConfig
Help-Item = Whammo Formatter,index.html

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 Tool Integrator 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 Tool Integrator to recognize tool updates.


External Tool Integration


Running the Tool from Within the IDE
Updating and Removing Integrated Tools and Classes