Jump to: navigation, search

PDE UI Incubator ApiTools Compare Dev

API Comparison Tool – Developer’s docs

Main functionality

The tool helps developers track API changes. It allows:

  • Detect binary incompatible changes
  • Create reports containing all changed (could be used as a base of “What’s New”)
  • Report incorrect bundle versions based on API changes

The tool takes a "source" and creates API snapshot from it. The tool use OSGi bundle(s), RCP product, or Java JAR(s) as a "source".

The snapshot is an XML file that is stored in the file system. Another version of the "source" can be compared to the snapshot to detect API changes.

For example, using this tool Eclipse SDK 3.2 can be compared to the version 3.3 to detect incompatible changes, produce skeletons for "what’s new" reports, and check to see if versions of bundles have been properly incremented.

Additional functionality

The tool supports "exclusion" mechanism that allows known problems to be omitted from the reports. The exclusion files follow the same format as XML API reports and, in fact, are expected to be produced from the reports by users.

The tool can be run both from Eclipse and in a headless mode.

Current status

The tool received a moderate amount of testing and is ready to be used.

Potential developments

At present directory on the file system as used as a repository for API snapshots. This approach is fine for a small workgroup, but something more scalable (like an SQL database) eventually will be needed to store API snapshots

The API description is being extracted from .class file. Alternatively, a module could be added to collect it from JDT model.

Fine-grained rules: A number of places in Eclipse have fine-grained API usage rules. Most common example would be API interfaces. A number of them has text in Javadoc declaring that users should not implement those interfaces. As such, adding methods to those interfaces is not a breaking change from Eclipse view point, but the tool has no way to detect such fine grained restrictions. A possible solution would be usage of new Javadoc tags to provide this information in a standard way.

Technology

Major points:

  • API information is extracted from .class files using custom parser
  • API/non-API determination is done based on OSGi manifest files
  • Detailed XML reports are produced
  • XSLT is used transform reports into readable HTML
  • System was designed in a modular fashion (source, repository, reports are replacable)

At present code is contained in 3 bundles:

  • org.eclipse.pde.api.tools – the "core" functionality
  • org.eclipse.pde.api.tools.ui – UI elements exposing "core" functionality
  • org.eclipse.pde.api.tools.tests – tests

The bundles contain code for both API comparison tool and reference extraction tool.

The classes SnapshotOperationsBundle and SnapshotOperations from the "core" bundle provide access points for the UI and headless invocations. The information on the source code to be processed and processing options is passed via IApiControl structure.

Source code is described via IApiContainer structures that could be used to represent individual OSGi bundles, Java JARs or directories that contain source code. See classes SourceContainerBundle and SourceContainer.

The bundle version uses information contained in the manifest.mf files. To obtain it, it relies on the internal PDEState helper class from PDE Core.

The "core" bundle contains specialized parser for .class files that allows us to extract only information needed by API tools. As the parser bypasses most of the information in the .class files, parsing is rather efficient.

The package "org.eclipse.pde.api.tools.internal.model" contains classes representing various Java constructs in memory (such as methods, fields, classes, and so on).

The two major operations – API snapshot collection and API comparison are performed, respectfully, by the Collector and Comparator classes.

IApiRepository describes an interface to the repository for API snapshots. At present, it only implemented to allow snapshots be stored in a directory on a file system; however, as may other pieces, it is designed to be pluggable.

Results produced by Comparator are stored first as XML reports (see XMLReport class) and then converted into HTML using XSLT (see ComparisonHtmlReport). The approach taken so far is that XML reports are detailed reports; some details can be absent form HTML reports to improve readability.


Links

API Tools API Tool User Guide PDE Incubator - New projects that might be incorporated into PDE in future.