Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [wtp-dev] Re: API Types that Inherit from Non-API Types


If anyone is collecting (good) examples of doing this, I think the base Eclipse
Job extending InternalJob is one such case. Here, I believe, they do this
so all clients extend the public "Job" but the infrastructure can still do "internal" things
with "InternalJob".  This is probably a rare case, and not sure its in the same
league as those Arthur is asking about. Just thought I'd document it in this thread
for those interested in the "theory" of such patterns.




Jim des Rivieres <Jim_des_Rivieres@xxxxxxxxxx>
Sent by: wtp-dev-bounces@xxxxxxxxxxx

05/11/2005 03:03 PM

Please respond to
"General discussion of project-wide or architectural issues."

To
Arthur Ryman <ryman@xxxxxxxxxx>
cc
wtp-dev@xxxxxxxxxxx
Subject
[wtp-dev] Re: API Types that Inherit from Non-API Types





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/

_______________________________________________
wtp-dev mailing list
wtp-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/wtp-dev


Back to the top