PDE/API Tools/User Guide
API tooling has recently been integrated into the Eclipse SDK and lives in the PDE project. This guide shows developers how to set up and use API tooling features in daily development scenarios.
API Tooling Setup
API tooling provides a builder that reports API usage and binary compatibility errors in the workspace. You must configure bundles/projects that you want API tooling to report errors on and you must define an API profile that can be used as a baseline (i.e. workspace projects are compared to the baseline in order to report binary compatibility errors, missing @since tags, incorrect version numbers, etc.).
Define an API Baseline
An API baseline defines the state you want to compare your development workspace bundles against for the purposes of binary compatibility, bundle version numbers, and @since tags. For example, if you are developing bundles for Eclipse 3.4, you will use Eclipse 3.3 as your baseline.
API profiles are managed on the Plug-in Development > API Profiles preference page. Here you can create, edit, and delete API profiles. You can select one profile as the 'default' profile - this is the profile that will be used as the baseline.
Use the Add Profile... button to open a wizard to define a profile. Any Eclipse SDK can be used as a profile simply by giving it a name and specifying the root location of the plug-ins.
Note: Currently, Eclipse builds do not contain API description metadata that assists API tooling. This information will be added to builds sometime during the 3.4 development cycle. An SDK can be used as a profile/baseline without the metadata, although some problems may not be detected when this information is missing. For example, if you are implementing an interface that originates from a binary required plug-in, API tooling cannot verify that the interface is allowed to implemented unless the API description metadata is present.
Configure Bundles for API Tooling
API tooling provides a builder that analyzes bundles and reports API errors. You need to configure existing projects to use the builder (this effectively adds the "API Tooling" nature to your project). As well, you need to describe the API of your bundle. Special API Javadoc tags can be placed on classes, interfaces, and methods to describe their API (@noimplement, @noinstantiate, @noextend). You can use content assist to insert tags with appropriate comments.
Note: API tooling can insert Javadoc tags into source code based on existing component.xml files.
Using the PDE Tools > API Tooling Setup... action to configure your projects.
A dialog appears allowing you to select projects you want to setup for API tooling.
Note: By default, component.xml files are deleted from your workspace after corresponding Javadoc tags are inserted into source code. There is a checkbox to disable this option. You can also preview the text changes that will be made, by clicking 'next'.
After pressing finish, Javadoc tags will be inserted and the API Tooling nature (and builder) will be added to your projects. API problems will now appear in the workspace where appropriate. You should manually examine your source code after tags have been inserted to ensure correctness.
Once your projects have been configured for API tooling and an API baseline has been selected, API problems will be created during project builds (auto and full builds).
The tooling breaks down the types of problems reported into one of three categories:
- Usage Problems - restricted code is being called by unauthorized plugins
- Binary Incompatibilities - changes between versions are not binary compatible
- Version Problems - plugin versions or code versions (@since tags) not correct
Adjusting Problem Severities
Similar to the way you can set compiler problem severities (error vs. warning vs. ignore), API tooling provides an API Errors/Warnings preference page that allows you to configure API problem severities. You can configure the problem severities on a per project basis as well, by using the API Errors/Warnings property page for a project, available from the Properties... action.
Filtering Known Problems
Sometimes you will have API problems that are "known problems" or are "approved" API breakages. API tooling has support to allow you to filter these problems from your workspace.
You can add a filter for a specific api problem using the Eclipse 'quickfix' mechanism on any api problem marker.
Once a filter has been added you can edit / remove it from the 'Api Problem Filters' project property page.