PDE/API Tools/Architecture

Architecture

Similar to the way we develop and ship plug-ins (bundles), we want to be able to develop and ship API information. This information can then be used by the integrated API tooling or by the build process to report API defects. The developers of a plug-in will be responsible for maintaining associated API information. API tooling models APIs using the following abstractions.

• API Component - Describes the API of a software component. In our case a software component is a plug-in or bundle but the concept could be extended to other constructs such as a Java project. An API component has the following attributes:
  • Symbolic Name - For example, plug-in identifier.
  • Descriptive Name - A human readable name such as "Platform UI".
  • Version - Identifies the version of the component. For example, "3.3.0".
  • Class Files - Original class files (jars, folders, etc), or class file stubs (compressed version with same information).
  • Required Execution Environment - Defines the execution environment required by the component for building and running. Execution environments are defined by standard OSGi profiles such as J2SE-1.4, CDC-1.1/Foundation-1.1, etc.
  • Required API Components - Defines all components required by a component in terms of symbolic names and compatible version ranges.
  • API Description - Defines visibility of elements within the component as API, SPI, private, or private permissable. Defines restrictions of elements within the component as not to be subclassed, instantiated, implemented or referenced.

• API Profile - A collection of related API components that can be compared with another profile. For example, all of the API components of the plug-ins in an Eclipse SDK. An API profile has the following attributes:
  • API Components - The components contained in the profile.
  • Execution Environment - The execution environment required by the profile for building and running.
  • Symbolic Name - For example, "eclipse.sdk"
  • Descriptive Name - For example, "Eurpoa"
  • Version - For example, "3.3.0"

API tooling provides the following engines, analyzers, and tools that operate on the API components.

• Converter - Generates class file stubs from original class files. The stubs contain all member signature information and may optionally contain all original reference and line information. Stubs are typically smaller than original class files intended to reduce download and analysis time.
• Reference Scanner - Scans a class file compiling all references a class file makes to other class files.
• Delta Engine - Compares two versions of the same class file building a hierarchical delta of the differences between to the two files.
• Javadoc Scanner - Scans Java source for special javadoc restriction tags to annotate a component's API decription.
• Manifest Reader - Reads a bunlde's MANIFEST.MF to annotate a component's package level API description. For example, annotates exported packages as API or private with exceptions for specific components (friends).