Running the Tool from within the IDE

Once integrated, a user-defined tool that resides on the file system can be launched in two ways. In each case, the main() method for the application is called.

  1. From the IDE Tools menu. The tool can have a single menu entry off the Tools menu, or a submenu that contains several menu entries. Each menu entry is associated with a Java application that resides in the base directory of the tool.
  2. From the Quick Start window. The tool can have an entry under its own category, or be placed under the default tools Quick Start category.

The tool is launched via a mechanism that emulates a Java interpreter command. Imagine that the class is launched by a command with the following syntax:

java <class_name> [selection_group]

where:

class_name
The name of the application class file, which must contain a main() method.
selection_group
The selection context with the appropriate switch, if there is a selection context. See below for details.

Selection Context and Selection Group

An application may have been set up such that it can only be launched when a specific program element type is selected. The group of items that are currently selected is called the selection context. The selection context can be either one or more projects, one or more packages, or one or more classes. The names of the selected program elements are passed as parameters to the application's main() method, as well as a switch indicating the program element type.

The invocation switches are:

-P (for Projects)
-p (for Packages)
-c (for Classes)

From the selection context, the Tool Integrator constructs a selection group. For example, if the selection context includes two packages, myPack1 and myPack2, the selection group is '-P "myPack1" "myPack2"'. Items in the selection context may contain spaces because the command creates a single string from the name of the selected item. For example, if the projects "Banking Facility" and "Java Class Libraries" have been selected, the selection group is '-P "Banking Facility" "Java Class Libraries"'. Default package names are passed as they appear in the IDE. For example, the Animator class that is in the default package for Sun JDK Animator would be passed as "Default package for Sun JDK Animator.Animator".

Each invocation of a tool passes a single selection context to the application. The same tool can support multiple selection contexts for different invocations.

You are responsible for handling all input parameters passed to the tool as a result of launching the tool with a selection context. You are also responsible for managing any restrictions on the selection context, and to deal with any exceptions that result from handling the input parameters.

Limitation: do not try to concurrently execute two or more tools that use the same classes, where one tool loads the classes from the workspace and the other tool loads the classes from the file system. This may be a typical scenario for tools that generate code against a set of runtime libraries and also use the same set of libraries during tool execution. The libraries must be added to the workspace in order for the generated code to be usable. The tool could have also included the same libraries in the tool installation directory tree for its own execution. This limitation manifests itself as an exception in one or more of the executing programs. Depending on the nature of the code, this is typically either an exception indicating a class could not be found, or a cast exception. Simply terminate the offending programs and run the actions sequentially. See the Release Notes for more details.


External Tool Integration


Setting Up a Tool for Integration
Updating and Removing Integrated Tools and Classes