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."
Arthur Ryman <ryman@xxxxxxxxxx>
[wtp-dev] Re: API Types that
Inherit from Non-API Types
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
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
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.
05/11/2005 11:04 AM
Jim des Rivieres/Ottawa/IBM@IBMCA
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
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
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.