[wtp-dev] Re: API Types that Inherit from Non-API Types

[Jim des Rivieres <Jim_des_Rivieres@xxxxxxxxxx>]

Arthur,

I concur on both points:
(a) API methods should not have internal types as parameters, return 
types, or exceptions. Such methods would be unuseable by any client that's 
playing it by the book.

(b) In general, API classes should not inherit from internal classes or 
interfaces. As you point out, API classes would inherit public and 
protected methods from the internal supertype, making them API methods as 
well. These are problematic because the javadoc spec for these methods 
would never be published (javadoc is on run only on API packages), and 
because they are an accident waiting to happen (developer changes methods 
on the internal class and indirectly changes API methods on subclass). 
This dangerous pattern is used in one place in the Eclipse Platform (
o.e.core.resources.IncrementalProjectBuilder) for considerations I can no 
longer recall; in that case, the API class explicitly overrides all public 
and protected methods inherited from the internal class; this ensures that 
the methods do get publishable javadoc, and gives a bit of insulation 
against inadvertent changes to the API.

---jim




Arthur Ryman/Toronto/IBM 
05/11/2005 11:04 AM

To
wtp-dev@xxxxxxxxxxx
cc
Jim des Rivieres/Ottawa/IBM@IBMCA
Subject
API Types that Inherit from Non-API Types





The API scanning reports now flag refrerences to non-API types as errors. 
Clearly, an API method must not have non-API types as arguments, return 
value or exceptions. However, inheriting from non-API types need further 
examination.

In general, an API class should hide its implementation, so only inherit 
from non-API types when necessary. If you do so, then the API must assume 
ownership of all inherited public and protected methods since these are 
visible to clients. The API class must shield clients from changes to the 
non-API class. For example, if the non-API class removes a public or 
protected method, then the API class must add it to avoid breaking 
clients.

The PMC discussed this topic on Tuesday and arrived at the above policy. 
If you have other thoughts, please express them now.

By cc, I am asking Jeem to give us the official Eclipse position on this 
topic, or to help us formulate a position if none currently exists.

Arthur Ryman,
Rational Desktop Tools Development

phone: +1-905-413-3077, TL 969-3077
assistant: +1-905-413-2411, TL 969-2411
fax: +1-905-413-4920, TL 969-4920
mobile: +1-416-939-5063, text: 4169395063@xxxxxxx
intranet: http://labweb.torolab.ibm.com/DRY6/