API Tools 3.5M4 New and Noteworthy

API tooling now supports two restrictions on interfaces - @noimplement and @noextend. This allows an interface to be extended when it is not to be implemented directly. For example, a client may be permitted to subclass an existing implementation of a @noimplement interface and extend the base interface with extra function.

Component owners should decide where to add @noextend tags on existing interfaces, as this was previously implicit. To maintain the API contracts specified in 3.4, @noextend tags can be added to all interfaces specified as @noimplement. In some cases the @noextend restriction can be omitted, as clients that extend and implement a @noimplement interface will still be flagged with errors. However, if you would like to reserve the right to add constants to an API interface in the future, you must add the @noextend tag. This is because adding a field to an interface is binary incompatible if clients can extend or implement an interface (see Evolving API Interfaces).

You can now be alerted to breaking API changes even if you have incremented the major version of your plug-in. The first time you change a plug-in's API in an incompatible way, problems inform you to increment the major version of your plug-in. Once you increment the major version of your plug-in, API tooling allows additional breaking API changes without warning. Use the new preference Report API breakage even if authorized by major version increment to enable this feature (on the Plug-in Development > API Errors/Warnings preference page, on the top of the API Compatibility tab). When this preference is enabled you must use API problem filters to selectively permit incompatible API changes.

API tooling now warns you when you accesses code in a system library that is not part of a plug-in's required execution environment. For example, if your plug-in's target environment is J2SE-1.3, but you are developing against a J2SE-1.5 JRE, it can be easy to unintentionally reference types and methods that only exist in J2SE-1.4 or J2SE-1.5. Such references are now flagged with problems. You can adjust the severity of this problem via the Invalid references in system libraries option on the API Use tab of the Plug-in Development > API Errors/Warnings preference page.

API tooling creates warnings for problem filters that are no longer needed. API problem filters often become stale because they are used to filter known incompatibilities between two specific releases. A quick fix is available to remove stale filters.

Ant tasks to perform API analysis and generate simple HTML reports are now available. These are the same Ant tasks used in the Eclipse SDK build. Documentation for each task is available in the Reference section of the Plug-in Development Environment Guide.