Overview of the Tool Integrator API

Warning: Only experienced programmers should attempt to use the VisualAge for Java Tool Integrator API.  This API is ideally suited for use by ISVs.

The VisualAge for Java Tool Integrator API provides a powerful Java class library for programmatically managing code and data from within the IDE. While a programmer can use the IDE SmartGuides, menus, and other user interface facilities to work with code, this API lets you manage the environment programmatically.

The API provides methods to perform the following tasks:

Why would you use the Tool Integrator API? Consider this scenario: you are developing an application in VisualAge for Java that requires a high degree of interaction with the file system. You need to export your code to the file system to properly test it. Using the conventional IDE user interface, you would use the Export SmartGuide to deploy the class files. With the Tool Integrator API, you can write a tool that encapsulates all the user interface steps into a single class execution.

Package Overview

The API consists of a project called "IBM IDE Utility class libraries". When VisualAge for Java is installed, this project is only in the repository. You must add it to the workspace to work with the classes. The project contains two packages:

Usage Notes

Code that uses the Tool Integrator API must be executed from within the IDE. There is no supported mechanism for getting to this API from outside the IDE, although tools that execute in a separate process can still make use of the API by writing a request handler that runs within the IDE. The request handler could be structured as a long-running tool extension. Examples include an RMI server or an http server with servlets that communicates with the external process through some private request/response protocol, calling the Tool Integrator API to handle the requests.

When developing code in the IDE that uses the Tool Integrator API, ensure that the classpath properties for the class include "IBM IDE Utility local implementation" in the "Extra directories path" list. The classes can be found in <prod dir>\ide\project_resources\IBM IDE Utility local implementation. Once completed tool classes are deployed, the API classes are automatically included on the classpath of each executing tool action.

The tools can store tool-specific data within VisualAge for Java. Any serializable Java object can be tool data.

tool options
tool data associated with a tool key. Data is unique to each user workspace.
program element data
tool data associated with a program element (project/package/class/interface) that resides in the workspace. Data is unique to each user workspace.
shared data
tool data associated with a program element. Data is stored in the repository, so it can be shared in a team environment.

All three of these facilities are intended to be used to store relatively modest amounts of information. It is not intended to be used as a mass storage mechanism. Although the API does not impose any limits on data size, storing large data objects (especially shared data) can lead to performance degradation.

Access to both the workspace and repository is provided at a granularity level of project, package, class, or interface. With the exception of basic code-builder support, no API is provided to manipulate individual methods. Common Java facilities, such as introspection, can be used to access information at the method level.

To begin using the API, begin with the ToolEnv class, a bootstrap class used by a tool to gain access to the API services. ToolEnv.connectToWorkspace() returns a reference to a concrete implementation of the workspace. A repository is obtained from the workspace by calling one of the Workspace.getRepository() methods.

The classes and API are split in terms of code relating to the workspace and elements relating to the repository. The workspace includes projects, packages and types that have been added from the repository. All such program elements have corresponding editions in the repository. Thus, an API object representing a workspace project/package/type is distinct from the API object representing its corresponding edition in the repository. The relationship a workspace object has with other workspace objects is different than with repository objects. In the workspace, a project can include many packages, while a package can only belong to one project. In the repository, a project edition can include many package editions, and a package edition can belong to many project editions.

The repository can be directly queried for names of project and package editions. If a project or package name is supplied, the repository can also be queried for the corresponding list of the project or package editions.


External Tool Integration
External Class Integration


Example: Using the Tool Integrator API to Associate Data with a Package


Package com.ibm.ivj.util.base
Package com.ibm.ivj.util.builders