Re: [pde-dev] PDE API Tools API definition

[Oleg Besedin <obesedin@xxxxxxxxxx>]

Hi Elizabeth,
For OSGi bundles the definition
of APIs is taken from the approach used throughout Eclipse and described
among other places here: http://www.eclipse.org/articles/article.php?file=Article-API-Use/index.html
("How to tell API from non-API" section in particular).

The API tools mostly follow API definitions
outlined in that article. One thing that is evolved since that article
was written is the wide-spread adoption of OSGi model. As a result, API
tools use OSGi manifest to determine API packages (and don't use Javadoc
presence for this purpose). All packages exported in manifest files are
deemed to be API packages unless they have "x-internal" or "x-friends"
qualifiers.

In order to reduce number of false positives
during API comparison:
- addition of new elements (methods,
fields, and such) to non-final classes is not treated as an API breach
- addition of new elements to interfaces
can be configured by a user to be treated as an API breakage or not

For non-bundles (Java JARs and
such) it assumes that all packages are APIs unless they have ".internal"
in the package name.

Programmatically, definition of an API
package is pluggable and can be easily replaced. From a user perspective,
I don't think that API definitions should be changeable. By its very nature
API is a contract among multiple parties; one participant should not be
able to change contract by himself. 

To allow for "special cases"
API comparison tool has an exclusion mechanism - users can select specific
API breaches not to appear on the report. The exclusions are specific,
i.e., "removal of method ABC from class XYZ is OK". The vision
for this is that exclusion mechanism will be superseded with Javadoc processing
(http://wiki.eclipse.org/index.php/API_Javadoc_tags).

(Another possible development is the
introduction of "SPI" - Service Provider Interfaces. This would
be an API that is not guaranteed to stay the same in future releases. )

This is a good question and I'll add
this information to the Wiki page for API tools.

Sincerely,
Oleg Besedin

Elizabeth B Silberg <silberg@xxxxxxxxxx>
Sent by: pde-dev-bounces@xxxxxxxxxxx

07/10/2007 09:53 PM

Please respond to
"Eclipse PDE general developers list." <pde-dev@xxxxxxxxxxx>

To	pde-dev@xxxxxxxxxxx
cc
Subject	[pde-dev] PDE API Tools API definition

How is API defined in the PDE API Tools (http://wiki.eclipse.org/index.php/PDE_UI_Incubator_ApiTools)?
 Is it configurable or built into the code?  

Additionally, if the rules are set, what are they (i.e., what is considered
API to the PDE API Tools)? 

Thanks, 
Elizabeth 
_______________________________________________
pde-dev mailing list
pde-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/pde-dev