harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From George Harley <george.c.har...@googlemail.com>
Subject Re: Location for API extensions
Date Mon, 13 Feb 2006 14:39:44 GMT
Hi Geir,

I think that what Tim means is that we have to guard against *other 
modules* having dependencies on internal APIs that are likely to change. 
For instance, suppose ModuleA has a class MyThing in the 
org.apache.harmony.modulea.internal.foo package that has been developed 
with the intention of only being used by types in ModuleA. Placing class 
MyThing in an "internal" package sends a very strong signal out that 
this class should not be used outside of this module. It could be that 
the class is prone to a lot of changes ; or perhaps the ModuleA 
developers have agreed that at some point in the near future they will 
replace the class with a new type. Either way, it is a "domestic" issue 
that is for the developers of ModuleA to discuss and sort out among 

If a developer of *ModuleB* imports 
org.apache.harmony.modulea.internal.foo.MyThing into their code then 
they now run the risk of breaking ModuleB every time the ModuleA team 
make changes which is pretty disastrous. And such breakages occur more 
often than one would imagine - hence the appearance of things like this 
: http://www.alphaworks.ibm.com/tech/aus .

That situation could be avoided by the ModuleB developer(s) respecting 
the "internal" part of the package that they are thinking of importing. 
If tooling can be used to enforce the rule of not using *other modules'* 
internal classes then all the better.

Sorry if this is stating the obvious.

Best regards,

Geir Magnusson Jr wrote:
> Tim Ellison wrote:
>> The problem is that once you release a module with a particular internal
>> API into the wild you need to ensure that other modules that depend upon
>> it are not broken by your internal API changes.  
> But aren't they internal?
>> In general, unless you
>> control the make-up of the runtime you will not know whether you are
>> breaking other modules (or to put it another way, you can check that you
>> don't break other modules for a given build but other people may be
>> combining different versions of the modules).  With runtime support you
>> can have multiple versions of a module simultaneously, without runtime
>> support you must retain binary compatibility.  In practice this simply
>> means knowing which changes are allowed, and which require a new
>> internal API.
>> Regards,
>> Tim
>>> On 2/13/06, Tim Ellison <t.p.ellison@gmail.com> wrote:
>>>> I've put a first cut of the proposed package naming convention on the
>>>> website:
>>>> http://incubator.apache.org/harmony/subcomponents/classlibrary/pkgnaming.html

>>>> Regards,
>>>> Tim
>>>> Leo Simons wrote:
>>>>> On Fri, Feb 10, 2006 at 12:52:09PM +0300, Anton Avtamonov wrote:
>>>>>>> As I wrote elsewhere, I propose that packages whose naming 
>>>>>>> convention is:
>>>>>>>        org.apache.harmony.<modulename>.<something>
>>>>>>> represent internal APIs.  All visible (public/protected) types

>>>>>>> in those
>>>>>>> packages can be used by class library developers from any 
>>>>>>> module, and
>>>>>>> such developers can expect the API to be evolved in a compatible

>>>>>>> way.
>>>>>>> Module developers should not rely on the stability of anything

>>>>>>> starting:
>>>>>>>        org.apache.harmony.<modulename>.internal
>>>>>>> and are strongly discouraged from referencing visible types in
>>>>>>> packages since these are type internal module implementation

>>>>>>> code (and
>>>>>>> when we turn on OSGi runtime checks the imports from other 
>>>>>>> modules will
>>>>>>> fail).
>>>>>>>> From other hand if we are talking about using these useful

>>>>>>>> classes only
>>>>>>>> inside Harmony then it's probably a good idea. But we need
>>>>>>>> procedure
>>>>>>>> for moving a class to utilities package and we need to notify

>>>>>>>> developers
>>>>>>>> about class capabilities.
>>>>>>> Moving it to a 'utilities' package should be as simple as making

>>>>>>> it a
>>>>>>> non-internal package name; and the notification is javadoc of
>>>>>>> non-internal types.
>>>>>>> If people agree I'll write something for the website along these

>>>>>>> lines,
>>>>>>> if not we can continue to debate it on the list.
>>>>> +1 (to the website thing, though debate obviously is fine too :-D).
>>>>> I personally think that it is a good idea to seperate out 
>>>>> non-J2SE-specific
>>>>> non-Harmony-specific stuff as much as possible. I also think it is 
>>>>> a good idea
>>>>> to evaluate very carefully on a case-by-case basis whether it 
>>>>> makes sense to
>>>>> have that kind of code live under the "harmony" banner -- 
>>>>> experience has shown
>>>>> that breaking out "true" utility stuff can help result in wider 
>>>>> usage of that
>>>>> stuff which tends to result in more bugfixes, better code, etc.
>>>>> For example (and I'm being really naive here) I can imagine that 
>>>>> java.util
>>>>> could be built on top of jakarta-commons-collections, or that 
>>>>> java.util.logging
>>>>> could be built on top of log4j (now that'd be cool).
>>>>> But this is just me imagining stuff that might be possible in the 
>>>>> future. For
>>>>> now it doesn't make sense to worry or think about this too much - 
>>>>> we'll see
>>>>> what kind of ties between harmony and something like 
>>>>> jakarta-commons (or
>>>>> whatever other part of the open source java space we're on about 
>>>>> here) is
>>>>> possible as the issue comes up.
>>>>> cheers!
>>>>> Leo
>>>> -- 
>>>> Tim Ellison (t.p.ellison@gmail.com)
>>>> IBM Java technology centre, UK.

View raw message