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

[Timothy Deboer <deboer@xxxxxxxxxx>]

Hi,

I don't think you can call that class
API. It's unsafe and there is no good way to document it for the user -
and if you can't isolate the user from internal changes, it's not API.
If there is one thing I learned from Jim, it's that we all have cases like
this in our code, and we already know that something is wrong. Put on the
API goggles that he handed out during his visit :) and take another look.
It may not be obvious at first, but with a little time and effort there's
almost always a way to refactor the code that'll make it much cleaner.

As Jim has stated, we shouldn't be subclassing
from internal classes unless there is no other option. So, the first step
would be to look for other options - delegation, other patterns, etc...
if that fails, then in this case there should be no need to make the internal
class' method final (since people can't extend it anyway), so one possibility
would be to make it a regular method and override it and make it final
in the API class.

Thanks,
Tim deBoer
WebSphere Tools - IBM Canada Ltd.
(905) 413-3503  (tieline 969)
deboer@xxxxxxxxxx

Jeffrey Liu/Toronto/IBM@IBMCA
Sent by: wtp-dev-bounces@xxxxxxxxxxx

05/11/2005 11:12 PM

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

To	"General discussion of project-wide or architectural issues." <wtp-dev@xxxxxxxxxxx>
cc	Michael Elder <mdelder@xxxxxxxxxx>, Jim des Rivieres/Ottawa/IBM@IBMCA
Subject	Re: [wtp-dev] Re: API Types that Inherit from Non-API Types

Hi Jeem, 

Just to echo one of the concern that Michael posted earlier, what about
methods that the subclass cannot override? For example, a public final
method from the non-API super class. In such case, we can't really insulate
our clients from changes to the non-API class. 

Thanks, 

Jeffrey Liu
IBM Rational Software - Performance Analyst
IBM Toronto Lab.
8200 Warden Ave. Markham, Ontario, L6G 1C7
Internal mail: D3/R8V/8200/MKM (D3-268)
T/L: 969 3531
Tel: (905) 413 3531
Fax: (905) 413 4920
jeffliu@xxxxxxxxxx

David M Williams <david_williams@xxxxxxxxxx>
Sent by: wtp-dev-bounces@xxxxxxxxxxx

05/11/2005 08:17 PM

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

To	"General discussion of project-wide or architectural issues." <wtp-dev@xxxxxxxxxxx>
cc	Jim des Rivieres/Ottawa/IBM@IBMCA
Subject	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
_______________________________________________
wtp-dev mailing list
wtp-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/wtp-dev
_______________________________________________
wtp-dev mailing list
wtp-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/wtp-dev