Re: [pde-dev] [apitools] representing API

[Darin Wright <Darin_Wright@xxxxxxxxxx>]

> 
> Then we revisited something Darin had suggested a while ago, why not
> just use the classfiles themselves?  Initially this approach was 
> rejected because of a) the bulk and b) the issues people will have 
> with publishing their actual binaries just to support API usage 
> scanning.  In reconsidering this we hit upon the idea of essentially
> stripping all the irrelevent (for our purposes) information from the
> class files and producing "API stub" class files that contain, in 
> their full-featured form, 
> 1) API signatures 
> 2) all external references (where external is relative to some 
> packaging notion defined by the context.  e.g., bundles in the OSGi 
context) 

I think we may also need to keep references within the "API unit" as well. 
This would allow us to detect leakage of non-public types into a public 
API (for example, return types, argument types, and supertypes).

> 3) usage information (e.g., is a reference a result of a field 
> reference, method call, class ref, ...) 
> 4) line number information (where the reference is occurs) 
> 5) supertype and interface information 
> 

In order to peform API breakage analysis the complete API of each type is 
required - i.e. inherited members are required. Since supertypes may 
originate in other "API units" (bundles, etc.), we either need to 
introduce dependencies between the "API units" or ensure that a unit has 
all API information present. For example, if a method is added or removed 
from a public type, we need to determine where in the type hierarchy the 
method was added or removed to know where the breakage occured (i.e. in 
which "API unit").

I think we should experiment with keeping a "library of required types" 
with each "API unit" - that way each unit could be analyzed by itself, and 
we would not require other "prerequsite units". I would suggest that we 
generate stubs for each external required type as well, and package them 
in some "library" folder within the "API unit". If the "library stubs" 
turn out to be too large, we could then consider dependencies between "API 
units".

Darin Wright