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

Consider the following situation: you want to attach reminders to yourself about packages that you write in the IDE.  You can use the Tool Integrator API to write a tool that lets you input text, associate it with a package, and retrieve the text.

This hypothetical tool, called TextReminder, can be launched against a package.  It presents a simple dialog with a text area for inputting your comments, and buttons for applying and canceling changes.

When data is associated with a workspace object (in this example, a package), it must be uniquely identified by a key, which is a java.lang.String object.  This allows multiple tools to store information associated with the same workspace object.  For simplicity, we suggest you use the fully qualified tool name as the key.

Note: Any data associated with an IDE object must implement the Serializable interface.  In this example, we use String, which does implement Serializable.

The class for the tool does the following things:

  1. Takes the fully qualified name of the selected package as a parameter, -p packagename.
  2. Gets a workspace object by using the ToolEnv.connectToWorkspace() method.
  3. Retrieves the Package object for the given package name by using the Workspace.loadedPackageNamed() method.
  4. Checks to see if the package has a text comment associated with it by using the Package.testToolWorkspaceData() method, passing in the key "TextReminder".   This method returns a boolean indicating whether any data is associated with the package for this tool.
  5. If data does exist, retrieves it using the Package.getToolWorkspaceData() method, with the key as a parameter.  This returns a ToolData object.
  6. The ToolData object consists of the key and the text.  The tool extracts the text by using the ToolData.getData() method, which returns a Serializable object.  In this case, since we are storing and retrieving String objects, cast the returned object to a String.
  7. Outputs the String to the dialog.
  8. When changes have been made to the output text, the tool writes the text back to the ToolData object by using ToolData.setData().  Then it applies changes to the package object by using Package.setToolWorkspaceData().
  9. If you want remove any associated data (so that Package.testToolWorkspaceData() returns false), use Package.clearToolWorkspaceData().

The resulting class might look like this:

private static String key = "TextReminder";
public static void main(String[] args) {
  boolean saveTheComment = true;
  boolean deleteTheComment = false;
  String pkgName = args[1];
  try {
    Workspace theWS = ToolEnv.connectToWorkspace();
    Package pkg = theWS.loadedPackageNamed(pkgName);
    ToolData toolData = null;
    String userComment = new String();
    if (pkg.testToolWorkspaceData(key)) { 
      toolData = pkg.getToolWorkspaceData(key);
      userComment = (String)toolData.getData();
    }
    else 
      toolData = new ToolData(key,userComment);
  // Code that allows the user to view/edit 
  // the comment omitted.
    if (saveTheComment) { // likely dependent on button click
      toolData.setData(userComment);
      pkg.setToolWorkspaceData(toolData);
    }
    else if (deleteTheComment) 	// likely dependent on button click
      pkg.clearToolWorkspaceData(key);
    // otherwise the user is not modifying the comment.
    }
 catch(Exception ex) { }
}

Preparation before Testing the Example

To test the example in the IDE before deploying it, you need to ensure that the execution classpath in the IDE has been properly set up, and that an execution context is passed to main() during test execution.

To set up the classpath:

  1. Open the Properties dialog on the class, and on the Class Path page, select the Project path checkbox and then press Compute Now.
  2. Select the Extra directories path checkbox and then select Edit. From the dialog, select Add Directory... and then select ide\project_resources\IBM IDE Utility local implementation.

To set up a test invocation context, open the Properties dialog on the class, and on the Program page, enter the command-line arguments expected by the main() method. For example "-p my.package".


Overview of the Tool Integrator API
External Tool Integration
External Class Integration


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