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 (:pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse). You need to check out three projects from the manifest_tooling branch.

1. Add the CVS server to your repositories view.
2. Expand the server node, select the 'Branches' element in the tree and select "Refresh Branches..." from the context menu.
3. In "Refresh Branches" dialog, select (check) the "pde-incubator" project.
4. Press "Finish". When prompted with "Tags not found for some modules" press "Search Deeply".
5. The "manifest_tooling" branch should now appear in the view. Expand the path "pde-incubator/api-tooling/plugins".
6. Check out the these projects:
   1. org.eclipse.pde.api.tools
   2. org.eclipse.pde.api.tools.ui
   3. org.eclipse.pde.api.tools.tests

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.