Difference between revisions of "PDE/API Tools/Architecture"

From Eclipsepedia

< PDE‎ | API Tools
Jump to: navigation, search
(Getting Started: Code & JUnit Tests)
m (ApiTools Architecture moved to PDE/API Tools/Architecture: better align with the rest of the PDE content on the Eclipse wiki)
(13 intermediate revisions by 4 users not shown)
Line 1: Line 1:
== Goals ==
+
== Architecture ==
  
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:
+
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. An API description will be shipped with each bundle as metadata in a binary build allowing the tooling to understand the API rules of each bundle and report problems for improper use of API and for binary compatibility issues between releases.
  
* Identify binary compatibility issues between two versions of a software component or product.
+
== Components and Profiles ==
* 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 ==
+
API tooling models APIs using the following abstractions.
 
+
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:
 
* '''''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:
Line 22: Line 11:
 
** '''Descriptive Name''' - A human readable name such as "Platform UI".
 
** '''Descriptive Name''' - A human readable name such as "Platform UI".
 
** '''Version''' - Identifies the version of the component. For example, "3.3.0".
 
** '''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).
+
** '''Class Files''' - Original class files (jars, folders, etc), or class file stubs (compressed version with same information). One of the interesting features of API tooling is its ability to produce and process class file stubs (i.e. minimal class files with just member signatures and reference information). The comparison and reference analysis tools can process standard class files or class file stubs. The stubs allow “API components” to be produced that are smaller than the original code intended for distribution. The class file stubs can be used as libraries to compile against, but not run.
 
** '''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 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.
 
** '''Required API Components''' - Defines all components required by a component in terms of symbolic names and compatible version ranges.
Line 35: Line 24:
 
** '''Version''' - For example, "3.3.0"
 
** '''Version''' - For example, "3.3.0"
  
API tooling provides the following engines, analyzers, and tools that operate on the API components.
+
== Code Analysis ==
 +
 
 +
API tooling provides the following engines, analyzers 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.
 
* '''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.
+
* '''Delta Engine''' - Compares two versions of the same class file building a hierarchical delta of the differences between to the two files. The delta can then be analyzed for binary compatibility and to determine what changes (if any) affect bundle version numbers and @since tags.
* '''Javadoc Scanner''' - Scans Java source for special javadoc restriction tags to annotate a component's API decription.
+
* '''Search Engine''' - Searches a scoped set of class files for specific kinds of references that match API usage and visiblity restrictions. For example, among other things the builder provided by API tooling uses the search engine to locate instantiations of classes that are not intended to be instantiated. However, the search engine allows for more general searches such as all references to methods that match a regular expression or are contained in a certain package.
* '''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).
+
* '''Javadoc Scanner''' - Scans Java source for special API restriction tags to annotate a component's API decription.
 
+
* '''Manifest Reader''' - Analyzes 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 ==
+
 
+
<h4>Getting the Source Code</h4>
+
 
+
The source code for this implementation is available from the '''dev.eclipse.org''' CVS server in the '''/cvsroot/eclipse''' respository (<code>:pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse</code>). You need to check out three projects from the '''manifest_tooling''' branch.
+
 
+
# Add the CVS server to your repositories view.
+
# Expand the server node, select the 'Branches' element in the tree and select "Refresh Branches..." from the context menu.
+
# In "Refresh Branches" dialog, select (check) the "pde-incubator" project.
+
# Press "Finish". When prompted with "Tags not found for some modules" press "Search Deeply".
+
# The "manifest_tooling" branch should now appear in the view. Expand the path "pde-incubator/api-tooling/plugins".
+
# Check out the these projects:
+
## org.eclipse.pde.api.tools
+
## org.eclipse.pde.api.tools.ui
+
## org.eclipse.pde.api.tools.tests
+
 
+
<h4>Rununing the JUnit Tests</h4>
+
 
+
The JUnit tests run as standard JUnit tests (i.e. not JUnit plug-in tests). However, the tests require two VM arguments:
+
 
+
# -DrequiredBundles={path to directory containing standard Eclipse plug-ins}
+
# -Dee.file={path to an .ee file}
+
 
+
For example, <code>-DrequiredBundles=c:\sdk20071031-0010\eclipse\plugins -Dee.file=c:\jdk1.5.0_10\bin\j2se1-5.ee</code>.
+
  
The required bundles are used by the test suite to resolve any standard required bunldes in the test bunldes. 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:
+
== API Javadoc Tags ==
  
<pre>
+
Special Javadoc tags are used to annotate code with API information. The Javadoc tags are intended to replace existing 'component.xml' files (which have to be maintained manually). The tooling defines a fixed set of restrictions that can be assocaited with an extensible set of javadoc tags. The restrictions currently supported are:
-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
+
</pre>
+
  
The tests can be run individually, or you can run them all from the APIToolsTestSuite class.
+
# @noreference - Indicates that other bundles must not reference this member by name. I.e., the member is internal.  This tag is intended to be used very rarely when a public class wants to restrict access to one of its members, but is not intended for general usage. This tag is ignored on all other members except for method declarations and non-final field declarations.
 +
# @noimplement - Indicates that other bundles must not implement this interface. This tag is ignored for all types except for interfaces.
 +
# @noextend - Indicates that other bundles must not extend the class or interface it appears on. This tag is ignored for all members that are not interfaces or classes.
 +
# @noinstantiate - Indicates that other bundles must not create instances of this class. This tag is ignored for all other types that are not classes.
 +
# @nooverride - Indicates that other bundles must not extend (re-implement with a call to the overridden parent) or re-implement (with no call to the overridden parent) this method. This tag is ignored for all other members except method declarations.

Revision as of 17:24, 26 July 2008

Contents

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. An API description will be shipped with each bundle as metadata in a binary build allowing the tooling to understand the API rules of each bundle and report problems for improper use of API and for binary compatibility issues between releases.

Components and Profiles

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). One of the interesting features of API tooling is its ability to produce and process class file stubs (i.e. minimal class files with just member signatures and reference information). The comparison and reference analysis tools can process standard class files or class file stubs. The stubs allow “API components” to be produced that are smaller than the original code intended for distribution. The class file stubs can be used as libraries to compile against, but not run.
    • 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"

Code Analysis

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

  • 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. The delta can then be analyzed for binary compatibility and to determine what changes (if any) affect bundle version numbers and @since tags.
  • Search Engine - Searches a scoped set of class files for specific kinds of references that match API usage and visiblity restrictions. For example, among other things the builder provided by API tooling uses the search engine to locate instantiations of classes that are not intended to be instantiated. However, the search engine allows for more general searches such as all references to methods that match a regular expression or are contained in a certain package.
  • Javadoc Scanner - Scans Java source for special API restriction tags to annotate a component's API decription.
  • Manifest Reader - Analyzes 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).

API Javadoc Tags

Special Javadoc tags are used to annotate code with API information. The Javadoc tags are intended to replace existing 'component.xml' files (which have to be maintained manually). The tooling defines a fixed set of restrictions that can be assocaited with an extensible set of javadoc tags. The restrictions currently supported are:

  1. @noreference - Indicates that other bundles must not reference this member by name. I.e., the member is internal. This tag is intended to be used very rarely when a public class wants to restrict access to one of its members, but is not intended for general usage. This tag is ignored on all other members except for method declarations and non-final field declarations.
  2. @noimplement - Indicates that other bundles must not implement this interface. This tag is ignored for all types except for interfaces.
  3. @noextend - Indicates that other bundles must not extend the class or interface it appears on. This tag is ignored for all members that are not interfaces or classes.
  4. @noinstantiate - Indicates that other bundles must not create instances of this class. This tag is ignored for all other types that are not classes.
  5. @nooverride - Indicates that other bundles must not extend (re-implement with a call to the overridden parent) or re-implement (with no call to the overridden parent) this method. This tag is ignored for all other members except method declarations.