PDE/API Tools/Architecture

Goals

API tooling will assist developers in API maintenance by reporting API defects such as binary incompatibilities, incorrect plug-in version numbers, missing or incorrect @since tags, and usage of non-API code between plug-ins. The tooling will be integrated in the Eclipse SDK and will be used in the automated build process. Specifically, the tooling is designed to do the following:

• Identify binary compatibility issues between two versions of a software component or product.
• Update version numbers for plug-ins (bundles) based on the Eclipse versioning scheme.
• Update @since tags for newly added classes, interfaces, methods, etc.
• Provide new javadoc tags and code assist to annotate types with special restrictions:
  • @nosubclass - This class is not intended to be subclassed.
  • @noinstantiate - This class is not intended to be instantiated.
  • @noimplement - This interface is not intended to be implemented by clients.
  • @noreference - This type is not intended to be referenced by clients.
• Leverage existing information (in MANIFEST.MF) to define the visibility of packages between bundles.
• Identify usage of non-API code between plug-ins.

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).

Getting Started

Getting the Source Code

The source code for this implementation is available from the dev.eclipse.org CVS server in the /cvsroot/eclipse respository. You need to check out three projects from HEAD. There is a team project set file to assist you with this.

1. Add the CVS server to your repositories view (:pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse).
2. Expand the server and "HEAD" elements in the tree.
3. Navigate to the "pde-incubator/api-tooling/plugins" folder.
4. Check out the the org.eclipse.pde.api.tools.releng project.
5. In your Package Explorer, select the projectSet.psf file in the root folder of the "org.eclipse.api.tools.releng project".
6. Select File > Import. On the first page of the import wizard select Team > Team Project Set and press "Next".
7. On the second page of the wizard, the "org.eclipse.pde.api.tools.releng\projectSet.psf" should already be specified as the file to import. If not, choose it. Press "Finish".

The PDE API Tools projects and tests will be added to your workspace.

Rununing the JUnit Tests

The JUnit tests run as standard JUnit tests (i.e. not JUnit plug-in tests). However, the tests require two VM arguments:

1. -DrequiredBundles={path to directory containing standard Eclipse plug-ins}
2. -Dee.file={path to an .ee file}

For example, -DrequiredBundles=c:\sdk20071031-0010\eclipse\plugins -Dee.file=c:\jdk1.5.0_10\bin\j2se1-5.ee.

The required bundles are used as a pool when resolving required bunldes for test bunldes in the suite. The .ee file describes the execution environment required by API profiles in the test suite. Our tests require a J2SE-1.5 profile. A sample .ee file has the following contents:

-Djava.home=${ee.home}\..
-Dee.bootclasspath=..\jre\lib\rt.jar;..\jre\lib\jsse.jar;..\jre\lib\jce.jar;..\jre\lib\charsets.jar
-Dee.language.level=1.5
-Dee.class.library.level=J2SE-1.5

The tests can be run individually, or you can run them all from the APIToolsTestSuite class.