Requirements for A Tool for Checking API Usage in Eclipse-based Components

Jim des Rivieres
Last updated Dec. 10, 2004

This document lists the general requirements for a tool for checking API usage in Eclipse-based components and products.

1. The Problem

The context is the same as the current API Usage Scanner tool. That is, we need a tool for checking Eclipse-based products that will help in identifying inappropriate use of APIs and non-APIs. We want tools to be able to check Eclipse-based plug-ins and products for obvious cases of where plug-ins are not playing by the rules. The open-ended, heterougeous, and heavily componentized nature of Eclipse are what make it somewhat different from checking more monolithic applications.

Eclipse is based on the notion of a plug-in. Products end up being a collection of plug-ins, collected from diverse development efforts spanning open source projects, multiple IBM teams, and third-party tool vendors. Set of these plug-ins are often bundled into various "platforms" (e.g., Eclipse Platform, IBM Eclipse SDK), and assembled into product stacks or families (IBM RAD, WBIT). Component-based software is easier to develop, maintain, and evolve when the inter-component coupling is well understood and well managed. This is done by having each component offer its services through a well-defined API that serves are the sole interface between it and other components. To the extent that all inter-component coupling abides by the contracts spelled out in the API specifications, replacing one component by a different version supporting the same API contracts will work the same way. Moreover, component APIs can be evolved in compatible ways to meet changing requirements, without invalidating previously working configurations. However, when inter-component coupling does not follow the terms of the API contracts, replacing a component by a different version supporting the same API contracts may break some previously-working configurations. This is a destabilizing factor that decreases robustness, increases maintenance costs, and inhibits component growth.

In component-based software, the premium is on all inter-component coupling being through the components API and in accord with all API contracts. Although the Java language has some features for controlling visibility that are enforced at compile-time (e.g., private fields and methods cannot be referenced from outside the code of the class itself), there are many constraints restrictions that the Java language cannot express (e.g., that a particular public class is internal rather than API, or that a particular interface must not be implemented outside its own component). Detection of inappropriate inter-component coupling is most useful when the component is under development; after a problematic component has shipped in a product, the information can at least be useful in managing the problem (although not solving it).

The problem we are addressing is helping development teams to manage inter-component coupling in Eclipse-based components. In particular, we aim to do this by providing an automatic tool that can detect obvious cases where one component is more tightly coupled to another component that it should be.

2. General Requirements

The tool should meet the following general requirements:

  1. Tool will be used for checking Eclipse components.
    The notion of a "component" in Eclipse is not formally defined. Rather, a component is a loosely-defined grouping of a small number of plug-ins and/or plug-in fragments that are designed and maintained as a unit, generally by a small team of developers. For instance, the Eclipse Platform itself is made of a number of components each with between 1 and 5 plug-ins. The Java code for each plug-in is housed in one or more JARs (this relationship is formalized and captured in the plug-in's mainfest). Whereas coupling within a component in intended to be tight/intimate, all coupling between components is intended to be mediated through well-defined Java-based APIs. The primary use of the tool will be used for checking collections of Eclipse components to see whether the inter-component couplings are in line with the component APIs. the Java code in the various plug-ins.
  2. Helpful to component developers.
    Component developers (and development teams) are the primary customers of this tool. The tool should be designed to meet their needs. Their main need for such a tool is helping manage inter-component dependencies to ensure that they do not accidentally exceed the bounds of the component APIs. Early detection of problems means they can be addressed while the component is still under development. So the tool should detect and report cases of illegitimate couplings from component A to component B are not covered by B's API, the most common mistake being A referencing one of B's internal classes. A secondary need is to detect and report legitimate API couplings components, as an aid for planning and impact assessment.
  3. Modular, component-based input.
    Eclipse components to be checked will be fed to the tool. Since the notion of component and API are not formally specified in Eclipse, the tool will also need to be fed some a description of each component capturing things like the set of plug-ins that comprise the component, and the rules for separating component API from component internals and for distinguishing legitimate from illegitimate API usage. Component owners should create and maintain the component descriptions for their individual components (although it should also be easy to furnish an after-market component description  for a component that does not come with its own). Each component description should be in a file that the component owner can easily maintain. Component description files should be in a well-specified XML-based format so that they could be read or generated by other tools. A set of relevant component description files would be fed to the tool whenever checking components.
  4. Performant and scalable. 
    The tool should be amenable to checking large numbers of Eclipse components. We already have instances for Eclipse-based products with 1500 plug-ins. The tool should make it easy to check anything from a single component, to a group of components that form a "platform" of some ilk, to an entire product distribution. The components may be a heterogeneous mix of product-specific, open source, or third party. The tool should deal gracefully with incompleteness, so that it is possible to check a component without necessarily having complete information about other components. The tool should be reasonably fast, with speed proportional to the number of components being checked.
  5. Modular, component-based output.
    The tool should produce modular, component-based reports. The outputs should be in a well-specified XML-based format so that they could be post-processed for populating databases, generating web pages, printing reports, etc.
  6. Fully-automatic operation.
    The tool should be suitable for inclusion in automated build processes that build the components, or repackage components into larger aggregations. In other words, something without a GUI that can be run from the command line, or from an Ant build file.
  7. Open source.
    The tool itself should be open source, so that it can be used by development teams working on open source Eclipse components, which includes those at eclipse.org.

References