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

[Darin Wright <Darin_Wright@xxxxxxxxxx>]

Jeff McAffer wrote on 10/01/2007 09:47:35 PM:

> 
> Darin Wright wrote on 10/01/2007 09:14:46 PM:
> > 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).
> 
> Can this be done by inference if you know the internal/external 
> boundary of the API unit?  For example, if a method returns a type 
> that it does not import then it is likely a type from itself and if 
> the method is API, the return type should be API.  This may involve 
> some additional boundary information but it likely greatly reduces 
> the reference information needed. 

An oversight on my part - we'll be keeping return types, argument types, 
and supertypes as part of the class file stubs (we need those, because 
they are part of the signatures we'll be comparing). So yes, we should be 
able to infer types as internal/external to the unit and then use the API 
description (rules for the unit) to determine if the type is 
public/private.

> 
> > > 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".
> 
> Embedding the prereqs in the API Units is similar to snapshoting. 
> The challenge here is that the resultant API Unit is now 
> representative of a particular configuration of prerequisites.  If, 
> for example, your system has a different version of Foo (a prereq) 
> then the analysis of Bar (the dependent) is useless.  The other 
> issue is duplication.

True, having a static API configuration is not desirable. I was trying to 
avoid the game of managing pre-reqs :-) In the Eclipse/bundle world, the 
notion of pre-reqs is well defined. In other realms (pure Java Apps), the 
notion of pre-reqs may not be so well defined. 

> Every Eclipse API Unit will end up with stubs
> for the basic Runtime and UI types. 

Yes - my hope was that the duplication would be small. But, as pointed 
out, built-in static pre-reqs are not desirable.

Darin