harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Geir Magnusson Jr <g...@pobox.com>
Subject Re: Location for API extensions
Date Mon, 13 Feb 2006 14:56:26 GMT
Yes, I thought I indicated I got that in my previous message :)

George Harley wrote:
> 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 
> themselves.
> 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,
> George
> 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)
>>>>>>>> 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 such
>>>>>>>> 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 some 
>>>>>>>>> procedure
>>>>>>>>> for moving a class to utilities package and we need to
>>>>>>>>> developers
>>>>>>>>> about class capabilities.
>>>>>>>> Moving it to a 'utilities' package should be as simple as
>>>>>>>> it a
>>>>>>>> non-internal package name; and the notification is javadoc
of those
>>>>>>>> non-internal types.
>>>>>>>> If people agree I'll write something for the website along
>>>>>>>> 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