You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@harmony.apache.org by Anton Avtamonov <an...@gmail.com> on 2006/02/09 08:52:49 UTC
Location for API extensions
We have agreed on org.apache.harmony package as a root package for
private implementation stuff. As I understand the major part of the
functionality located there is some kind of utility stuff used from
different places (packages) and therefore moved out from the API tree.
Besides, it also can contain some 'default' implementations when
public API represents interfaces only.
It looks for me that in general we can divide all such stuff into 2 categories:
- utility methods appeared due to package visibility or other
reasons, 'default' implementations, etc. This category (in general) is
not likely to be interesting for the users of harmony platform
- classes, which are referenced from API, but have stand-alone value,
which is not accessible from public API. Such classes, in fact, extend
the standard API and may be useful for the harmony users. I believe
such functionality exists in almost any module; their authors know
what is valuable.
What I propose is to identify such functionlity and separate it from
the 'hidden' utility stuff. Let's have some additinal root
(harmony.extensions say) specially intended to keep 'java-harmony'
improvements. What do you think?
--
Anton Avtamonov,
Intel Middleware Products Division
Re: Location for API extensions
Posted by Tim Ellison <t....@gmail.com>.
Alexey Petrenko wrote:
>>> But there are a lot of questions. For example what structure and
>>> content should such library have. What classes used in Harmony modules we
>>> should include and what classes we should not include. It's obvious that
>>> library which simply consists of classes used by different developers in
>>> different places will look like trash can but not like useful library.
>> Agreed. I think the package naming convention goes a long way to
>> structuring the code properly to make the usability interesting.
> Yep. But I'm trying to say that creating tolls library is probably
> different project with different goals.
I agree. We have enough work in the project as scoped already ;-)
>> 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.
> We also should remember that using classes from different modules
> create additional dependencies between modules and this will decrease
> modularity. And developers should document such dependencies anyway.
> So probably we need do create "utilities" or "harmonyutilities" module
> and put all useful for other modules classes into this package.
No objection if it gets to that point, but let's not create it prematurely.
Regards,
Tim
--
Tim Ellison (t.p.ellison@gmail.com)
IBM Java technology centre, UK.
Re: Location for API extensions
Posted by Alexey Petrenko <al...@gmail.com>.
> > But there are a lot of questions. For example what structure and
> > content should such library have. What classes used in Harmony modules we
> > should include and what classes we should not include. It's obvious that
> > library which simply consists of classes used by different developers in
> > different places will look like trash can but not like useful library.
> Agreed. I think the package naming convention goes a long way to
> structuring the code properly to make the usability interesting.
Yep. But I'm trying to say that creating tolls library is probably
different project with different goals.
> 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.
We also should remember that using classes from different modules
create additional dependencies between modules and this will decrease
modularity. And developers should document such dependencies anyway.
So probably we need do create "utilities" or "harmonyutilities" module
and put all useful for other modules classes into this package.
--
Alexey A. Petrenko
Intel Middleware Products Division
Re: Location for API extensions
Posted by Geir Magnusson Jr <ge...@pobox.com>.
Leo Simons wrote:
>
>
> 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.
Certainly something to consider. Only issue is one of necessary control
- we need to have a set of behaviors driven by spec/tck reasons that a
general purpose package wouldn't care about.
>
> 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).
Well, Commons Collections depends on java.util :)
>
> 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.
Yep..
>
> cheers!
>
> Leo
>
>
Re: Location for API extensions
Posted by Richard Liang <ri...@gmail.com>.
Hello Tim,
+1. It's excellent.
Richard Liang
China Software Development Lab, IBM
Tim Ellison 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 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 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 those
>>>> 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
>>
>>
>>
>
>
Re: Location for API extensions
Posted by Geir Magnusson Jr <ge...@pobox.com>.
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....@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 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 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 those
>>>>>>>> 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.
>>>>>
>>>
>>
>
>
Re: Location for API extensions
Posted by George Harley <ge...@googlemail.com>.
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....@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 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 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 those
>>>>>>> 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.
>>>>
>>
>
Re: Location for API extensions
Posted by Tim Ellison <t....@gmail.com>.
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?
I'm confusing things ;-) There are two 'internals'. Internal to a
specific module's implementation (org.apache.harmony.internal.*) and
internal to Harmony i.e. not part of the Java-spec but a useful utility
to share with other modules.
These are the two categories in Anton's original note.
A module can mess with it's internals as much as it pleases; but the
utilities it shares with other module's should be managed.
Regards,
Tim
>> 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....@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 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 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 those
>>>>>>> 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.
>>>>
>>
>
--
Tim Ellison (t.p.ellison@gmail.com)
IBM Java technology centre, UK.
Re: Location for API extensions
Posted by Geir Magnusson Jr <ge...@pobox.com>.
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....@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 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 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 those
>>>>>> 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.
>>>
>
Re: Location for API extensions
Posted by Tim Ellison <t....@gmail.com>.
Mikhail Loenko wrote:
> Looks very good!
>
> I have two comments/questions.
>
> 1. I thought we agreed that *some* tests should be in the same package as
> implementations. How this fits together with a special package name for tests?
Sure, if you need helpers that reside in the same package to get package
visibility, then so be it -- I was only trying to describe the
org.apache.harmony packages;
i.e. we would have
src/
test/
java/
org.apache.harmony.security.tests.*
java.security.*
> 2. Does not it sound too strict: "module developers who modify code that is not
> in an internal package must do so in a manner that ensures Java binary
> compatibility"? How about "... should avoid breaking Java binary compatibility
> and must check that the change does not break other modules"
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. 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....@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 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 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 those
>>>>> 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.
>>
>
--
Tim Ellison (t.p.ellison@gmail.com)
IBM Java technology centre, UK.
Re: Location for API extensions
Posted by Tim Ellison <t....@gmail.com>.
Anton Avtamonov wrote:
> Hi Tim,
>
> Lemme join to Mikhail's words: very good! Thank you!
> I'm sure it will simplify the contribution process. Of course, we have
> committers who control the process, no doubts; however for me (and I
> think not for me only) it is much simplier to have the guideline of
> what structure is expected.
I appreciate your efforts to get the code right before contribution.
I'm very pragmatic though, and would rather have functional code that
solves people's problems ahead of pretty layout! I expect that we will
migrate towards compliance with our own guidelines over a period of time
<g>.
> Could we call *anything_alse* somehow :-)? Personally I would prefer
> *external* as opposite to *internal*, but I expect nobody will agree.
I disagree ;-) (just to prove you right).
IMHO besides being esthetically pleasing it makes it easy to catch
references to internal code.
> Let's me also support Mikhail in his comments:
>
> On 2/13/06, Mikhail Loenko <ml...@gmail.com> wrote:
>> Looks very good!
>>
>> I have two comments/questions.
>>
>> 1. I thought we agreed that *some* tests should be in the same package as
>> implementations. How this fits together with a special package name for tests?
>
> Yeah, looks like it will cause visibility problems, won't it?
Sorry, I think this is a simple misunderstanding -- the guidelines are
only for the org.apache.harmony packages.
>> 2. Does not it sound too strict: "module developers who modify code that is not
>> in an internal package must do so in a manner that ensures Java binary
>> compatibility"? How about "... should avoid breaking Java binary compatibility
>> and must check that the change does not break other modules"
>
> Also agree. In general, binary compatibility should be supported,
> however it could be very complicated to eastablish proper interfaces
> from the beginning...
If you are unsure what to expose, then make everything internal until
there is a need to make it visible to other module developers. These
interfaces/dependencies likely already exist within the code so this
only makes them explicit not more difficult.
> Btw, is it right that the module contributor himself can decide what
> to put into functionality available for other modules?
Sure, but if I'm writing jar support in ARCHIVE and I need some
internal-API to help me implement, ooh say, signature verification from
SECURITY then I know where to come :-)
Regards,
Tim
--
Tim Ellison (t.p.ellison@gmail.com)
IBM Java technology centre, UK.
Re: Location for API extensions
Posted by Anton Avtamonov <an...@gmail.com>.
Hi Tim,
Lemme join to Mikhail's words: very good! Thank you!
I'm sure it will simplify the contribution process. Of course, we have
committers who control the process, no doubts; however for me (and I
think not for me only) it is much simplier to have the guideline of
what structure is expected.
Could we call *anything_alse* somehow :-)? Personally I would prefer
*external* as opposite to *internal*, but I expect nobody will agree.
Let's me also support Mikhail in his comments:
On 2/13/06, Mikhail Loenko <ml...@gmail.com> wrote:
> Looks very good!
>
> I have two comments/questions.
>
> 1. I thought we agreed that *some* tests should be in the same package as
> implementations. How this fits together with a special package name for tests?
Yeah, looks like it will cause visibility problems, won't it?
>
>
> 2. Does not it sound too strict: "module developers who modify code that is not
> in an internal package must do so in a manner that ensures Java binary
> compatibility"? How about "... should avoid breaking Java binary compatibility
> and must check that the change does not break other modules"
Also agree. In general, binary compatibility should be supported,
however it could be very complicated to eastablish proper interfaces
from the beginning...
Btw, is it right that the module contributor himself can decide what
to put into functionality available for other modules?
--
Anton Avtamonov,
Intel Middleware Products Division
Re: Location for API extensions
Posted by Mikhail Loenko <ml...@gmail.com>.
Looks very good!
I have two comments/questions.
1. I thought we agreed that *some* tests should be in the same package as
implementations. How this fits together with a special package name for tests?
2. Does not it sound too strict: "module developers who modify code that is not
in an internal package must do so in a manner that ensures Java binary
compatibility"? How about "... should avoid breaking Java binary compatibility
and must check that the change does not break other modules"
Thanks,
Mikhail Loenko
Intel Middleware Products Division
On 2/13/06, Tim Ellison <t....@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 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 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 those
> >>> 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.
>
Re: Location for API extensions
Posted by Geir Magnusson Jr <ge...@pobox.com>.
Tim Ellison wrote:
> Geir Magnusson Jr wrote:
>> I don't like "tests" for obvious reasons that we've discussed before.
>
> remind me
package visibility
>
>> I do like "examples" as that's clear to people.
>>
>> "internal" is interesting, because we already have mechanisms in Java to
>> do this, so I don't see the point.
>
> huh? what?
>
>> It's also really unnatural to me to
>> do this in a package scheme. I wish I could be clearer on why this
>> sets my teeth on edge, but I can't, so I'll think about it a bit more...
>
> just so we understand one another...
>
> - our end users may use:
> java.<whatever> and friends (as defined by spec.) from
> any module
Sure
>
> - developers of a given module may use:
> java.<whatever> and friends from any module
> org.apache.harmony.* (but not 'internal') from any module
> org.apache.harmony.internal.* from this module
>
I see - so you can have public o.a.h.<woogie>.i.Foo that no one should
touch except for <woogie> classes...
geir
> This 'visibility of packages' is not part of the Java language.
>
> Regards,
> Tim
>
>> Tim Ellison 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 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 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 those
>>>>>> 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
>>>>
>>>>
>
Re: Location for API extensions
Posted by Tim Ellison <t....@gmail.com>.
Geir Magnusson Jr wrote:
> I don't like "tests" for obvious reasons that we've discussed before.
remind me
> I do like "examples" as that's clear to people.
>
> "internal" is interesting, because we already have mechanisms in Java to
> do this, so I don't see the point.
huh? what?
> It's also really unnatural to me to
> do this in a package scheme. I wish I could be clearer on why this
> sets my teeth on edge, but I can't, so I'll think about it a bit more...
just so we understand one another...
- our end users may use:
java.<whatever> and friends (as defined by spec.) from
any module
- developers of a given module may use:
java.<whatever> and friends from any module
org.apache.harmony.* (but not 'internal') from any module
org.apache.harmony.internal.* from this module
This 'visibility of packages' is not part of the Java language.
Regards,
Tim
> Tim Ellison 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 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 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 those
>>>>> 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.
Re: Location for API extensions
Posted by Geir Magnusson Jr <ge...@pobox.com>.
I don't like "tests" for obvious reasons that we've discussed before.
I do like "examples" as that's clear to people.
"internal" is interesting, because we already have mechanisms in Java to
do this, so I don't see the point. It's also really unnatural to me to
do this in a package scheme. I wish I could be clearer on why this
sets my teeth on edge, but I can't, so I'll think about it a bit more...
geir
Tim Ellison 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 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 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 those
>>>> 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
>>
>>
>
Re: Location for API extensions
Posted by Tim Ellison <t....@gmail.com>.
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 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 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 those
>>> 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.
Re: Location for API extensions
Posted by Leo Simons <ma...@leosimons.com>.
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 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 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 those
> > 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
Re: Location for API extensions
Posted by Anton Avtamonov <an...@gmail.com>.
>
> 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 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 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 those
> 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.
>
>
> Regards,
> Tim
>
Agree. Thank you.
--
Anton Avtamonov,
Intel Middleware Products Division
Re: Location for API extensions
Posted by Tim Ellison <t....@gmail.com>.
Alexey Petrenko wrote:
> As it said before it is not a good idea to positioning any Harmony classes
> as "extension for the standard API".
>
> However we can think about creating some standalone utilities library.
That's fair. In the first instance I expect that these will be
well-defined internal API that are mostly of interest to class library
developers themselves, but give our modular structure, such internal
APIs need to be managed as carefully as any end-user API or else we will
end up breaking component compatibility unnecessarily.
> But there are a lot of questions. For example what structure and
> content should such library have. What classes used in Harmony modules we
> should include and what classes we should not include. It's obvious that
> library which simply consists of classes used by different developers in
> different places will look like trash can but not like useful library.
Agreed. I think the package naming convention goes a long way to
structuring the code properly to make the usability interesting.
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 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 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 those
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.
Regards,
Tim
--
Tim Ellison (t.p.ellison@gmail.com)
IBM Java technology centre, UK.
Re: Location for API extensions
Posted by Alexey Petrenko <al...@gmail.com>.
> > 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 notify developers
> > about class capabilities.
> I think the key to get this started is to identify some set of
> functionality to focus on...
Agreed.
--
Alexey A. Petrenko
Intel Middleware Products Division
Re: Location for API extensions
Posted by Geir Magnusson Jr <ge...@pobox.com>.
Alexey Petrenko wrote:
> As it said before it is not a good idea to positioning any Harmony classes
> as "extension for the standard API".
>
> However we can think about creating some standalone utilities library.
>
> But there are a lot of questions. For example what structure and
> content should such library have. What classes used in Harmony modules we
> should include and what classes we should not include. It's obvious that
> library which simply consists of classes used by different developers in
> different places will look like trash can but not like useful library.
Right.
>
> 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 notify developers
> about class capabilities.
I think the key to get this started is to identify some set of
functionality to focus on...
geir
>
> --
> Alexey A. Petrenko
> Intel Middleware Products Division
Re: Location for API extensions
Posted by Alexey Petrenko <al...@gmail.com>.
As it said before it is not a good idea to positioning any Harmony classes
as "extension for the standard API".
However we can think about creating some standalone utilities library.
But there are a lot of questions. For example what structure and
content should such library have. What classes used in Harmony modules we
should include and what classes we should not include. It's obvious that
library which simply consists of classes used by different developers in
different places will look like trash can but not like useful library.
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 notify developers
about class capabilities.
--
Alexey A. Petrenko
Intel Middleware Products Division
Re: Location for API extensions
Posted by Geir Magnusson Jr <ge...@pobox.com>.
Anton Avtamonov wrote:
> We have agreed on org.apache.harmony package as a root package for
> private implementation stuff.
Only because we're the Apache Harmony project :)
> As I understand the major part of the
> functionality located there is some kind of utility stuff used from
> different places (packages) and therefore moved out from the API tree.
> Besides, it also can contain some 'default' implementations when
> public API represents interfaces only.
>
> It looks for me that in general we can divide all such stuff into 2 categories:
> - utility methods appeared due to package visibility or other
> reasons, 'default' implementations, etc. This category (in general) is
> not likely to be interesting for the users of harmony platform
> - classes, which are referenced from API, but have stand-alone value,
> which is not accessible from public API. Such classes, in fact, extend
> the standard API and may be useful for the harmony users. I believe
> such functionality exists in almost any module; their authors know
> what is valuable.
Be careful how you put that. What do you mean by "extend the standard API"?
>
> What I propose is to identify such functionlity and separate it from
> the 'hidden' utility stuff. Let's have some additinal root
> (harmony.extensions say) specially intended to keep 'java-harmony'
> improvements. What do you think?
Can you give an example of what you have in mind?
geir
Re: Location for API extensions
Posted by Anton Avtamonov <an...@gmail.com>.
> I have an example. Security2 has implementation of ASN.1 that is internal
> stuff but has its own value. And it has a document for developers
> who might use that internal stuff jre-independent.
Thank you, Mikhail.
I wanted to give some example from sequrity module, but was not sure
since I'm really not an expert in this area. Thank you for doing that.
As I told initially, nobody said we are going to develop something
specially to extend API, but if some functionality was created anyway
(as part of API development) why not to share it with others? All
these classes will be included into harmony anyway; the only question
is how to locate them to clearly define what might have a value and
what is internal implementation only.
Talking about the structure of such 'utility libraries' (ok, I see
nobody like the word 'extension' :-) ) I think (thanks to Tim) that
eclipse approach looks promising...
--
Anton Avtamonov,
Intel Middleware Products Division
Re: Location for API extensions
Posted by Mikhail Loenko <ml...@gmail.com>.
Agreed
And if we have some internal classes that users could benefit from
then we may provide usage examples or even tools that utilize those classes.
I have an example. Security2 has implementation of ASN.1 that is internal
stuff but has its own value. And it has a document for developers
who might use that internal stuff jre-independent.
Thanks,
Mikhail Loenko
Intel Middleware Products Division
On 2/10/06, Geir Magnusson Jr <ge...@pobox.com> wrote:
>
>
> Matt Benson wrote:
> > --- Geir Magnusson Jr <ge...@pobox.com> wrote:
> >
> >>
> >> Anton Avtamonov wrote:
> >>> Besides, such approach ties them to Harmony if
> >> they found such
> >>> extensions (funtionality, included into packages
> >> of 'public access')
> >>> useful :-)
> >> We actually don't want to tie anyone into Harmony
> >> other than because
> >> we're free, fast, stable, etc.
> >>
> >> This project *may* at some point offer packages that
> >> are not part of
> >> J2SE (for example, if we had built a nice logging
> >> implementation that
> >> was resuable), but that would clearly be separate
> >
> > AND JRE-INDEPENDENT
>
> Indeed. Right. Exactly.
>
> geir
>
> >
> >> parts of the project,
> >> and not to be confused with Harmony the J2SE
> >> Implementation.
> >>
> >
> > -$0.02 -Matt
> >
> >> geir
> >>
> >>
> >
> >
> > __________________________________________________
> > Do You Yahoo!?
> > Tired of spam? Yahoo! Mail has the best spam protection around
> > http://mail.yahoo.com
> >
> >
>
Re: Location for API extensions
Posted by Geir Magnusson Jr <ge...@pobox.com>.
Matt Benson wrote:
> --- Geir Magnusson Jr <ge...@pobox.com> wrote:
>
>>
>> Anton Avtamonov wrote:
>>> Besides, such approach ties them to Harmony if
>> they found such
>>> extensions (funtionality, included into packages
>> of 'public access')
>>> useful :-)
>> We actually don't want to tie anyone into Harmony
>> other than because
>> we're free, fast, stable, etc.
>>
>> This project *may* at some point offer packages that
>> are not part of
>> J2SE (for example, if we had built a nice logging
>> implementation that
>> was resuable), but that would clearly be separate
>
> AND JRE-INDEPENDENT
Indeed. Right. Exactly.
geir
>
>> parts of the project,
>> and not to be confused with Harmony the J2SE
>> Implementation.
>>
>
> -$0.02 -Matt
>
>> geir
>>
>>
>
>
> __________________________________________________
> Do You Yahoo!?
> Tired of spam? Yahoo! Mail has the best spam protection around
> http://mail.yahoo.com
>
>
Re: Location for API extensions
Posted by Matt Benson <gu...@yahoo.com>.
--- Geir Magnusson Jr <ge...@pobox.com> wrote:
>
>
> Anton Avtamonov wrote:
> > Besides, such approach ties them to Harmony if
> they found such
> > extensions (funtionality, included into packages
> of 'public access')
> > useful :-)
>
> We actually don't want to tie anyone into Harmony
> other than because
> we're free, fast, stable, etc.
>
> This project *may* at some point offer packages that
> are not part of
> J2SE (for example, if we had built a nice logging
> implementation that
> was resuable), but that would clearly be separate
AND JRE-INDEPENDENT
> parts of the project,
> and not to be confused with Harmony the J2SE
> Implementation.
>
-$0.02 -Matt
> geir
>
>
__________________________________________________
Do You Yahoo!?
Tired of spam? Yahoo! Mail has the best spam protection around
http://mail.yahoo.com
Re: Location for API extensions
Posted by Geir Magnusson Jr <ge...@pobox.com>.
Anton Avtamonov wrote:
> Besides, such approach ties them to Harmony if they found such
> extensions (funtionality, included into packages of 'public access')
> useful :-)
We actually don't want to tie anyone into Harmony other than because
we're free, fast, stable, etc.
This project *may* at some point offer packages that are not part of
J2SE (for example, if we had built a nice logging implementation that
was resuable), but that would clearly be separate parts of the project,
and not to be confused with Harmony the J2SE Implementation.
geir
Re: Location for API extensions
Posted by Anton Avtamonov <an...@gmail.com>.
> > org.apache.harmony
> > root of all package names
> >
> > org.apache.harmony.<modulename>
> > separates module namespaces
> >
> > org.apache.harmony.<modulename>.<something>
> > types whose API will be carefully managed. Other modules
> > can use these types in their impl.
> >
> > org.apache.harmony.<modulename>.internal
> > types reserved for use only within the module impl. Other
> > modules should not use these types as they may change.
> >
> > org.apache.harmony.<modulename>.tests
> > module's tests
>
> Ugh :)
>
> >
> > org.apache.harmony.<modulename>.examples
> > module's examples (if we have any!)
> >
Yes! That it very similar (at least conceptually) to what I meant. The
idea is to distinguish what others (I mean not only harmony developers
of course, but our users who will write their java applications basing
on harmony classes) can and what shouldn't use.
Besides, such approach ties them to Harmony if they found such
extensions (funtionality, included into packages of 'public access')
useful :-)
Talking about naming convension eclipse approach sounds very
atrractive since lots of people are familiar with and get used it...
--
Anton Avtamonov,
Intel Middleware Products Division
Re: Location for API extensions
Posted by Geir Magnusson Jr <ge...@pobox.com>.
Tim Ellison wrote:
> Anton Avtamonov wrote:
>> We have agreed on org.apache.harmony package as a root package for
>> private implementation stuff. As I understand the major part of the
>> functionality located there is some kind of utility stuff used from
>> different places (packages) and therefore moved out from the API tree.
>> Besides, it also can contain some 'default' implementations when
>> public API represents interfaces only.
>
> yes.
>
>> It looks for me that in general we can divide all such stuff into 2 categories:
>> - utility methods appeared due to package visibility or other
>> reasons, 'default' implementations, etc. This category (in general) is
>> not likely to be interesting for the users of harmony platform
>
> Yes, as you say, these are typically impl classes behind public API.
>
>> - classes, which are referenced from API, but have stand-alone value,
>> which is not accessible from public API. Such classes, in fact, extend
>> the standard API and may be useful for the harmony users. I believe
>> such functionality exists in almost any module; their authors know
>> what is valuable.
>
> Yes, I would call these 'internal' APIs. There are a few sub-systems
> that are generally useful to class library implementers.
>
>> What I propose is to identify such functionlity and separate it from
>> the 'hidden' utility stuff. Let's have some additinal root
>> (harmony.extensions say) specially intended to keep 'java-harmony'
>> improvements. What do you think?
>
> I think having a package naming convention for it is good, it gives a
> clear indication of the expected 'scope' of API users which is necessary
> to understand when you migrate internal APIs. (I'm not keen on the name
> 'extensions' tho')
>
> Eclipse has quite a simple and intuitive package naming convention:
> http://dev.eclipse.org/naming.html
>
> If we do a similar thing that would produce:
>
> org.apache.harmony
> root of all package names
>
> org.apache.harmony.<modulename>
> separates module namespaces
>
> org.apache.harmony.<modulename>.<something>
> types whose API will be carefully managed. Other modules
> can use these types in their impl.
>
> org.apache.harmony.<modulename>.internal
> types reserved for use only within the module impl. Other
> modules should not use these types as they may change.
>
> org.apache.harmony.<modulename>.tests
> module's tests
Ugh :)
>
> org.apache.harmony.<modulename>.examples
> module's examples (if we have any!)
>
> The componentization runtime can enforce the package visibility rules
> through the JAR manifest, even allowing 'friend' relationships etc. See
> an example of this in the NIO manifest, who only allows LUNI to see the
> com.ibm.io.nio package [1].
>
> [1]
> http://svn.apache.org/viewcvs.cgi/incubator/harmony/enhanced/classlib/trunk/modules/nio/META-INF/MANIFEST.MF?view=markup
>
> Regards,
> Tim
>
Re: Location for API extensions
Posted by Tim Ellison <t....@gmail.com>.
Anton Avtamonov wrote:
> We have agreed on org.apache.harmony package as a root package for
> private implementation stuff. As I understand the major part of the
> functionality located there is some kind of utility stuff used from
> different places (packages) and therefore moved out from the API tree.
> Besides, it also can contain some 'default' implementations when
> public API represents interfaces only.
yes.
> It looks for me that in general we can divide all such stuff into 2 categories:
> - utility methods appeared due to package visibility or other
> reasons, 'default' implementations, etc. This category (in general) is
> not likely to be interesting for the users of harmony platform
Yes, as you say, these are typically impl classes behind public API.
> - classes, which are referenced from API, but have stand-alone value,
> which is not accessible from public API. Such classes, in fact, extend
> the standard API and may be useful for the harmony users. I believe
> such functionality exists in almost any module; their authors know
> what is valuable.
Yes, I would call these 'internal' APIs. There are a few sub-systems
that are generally useful to class library implementers.
> What I propose is to identify such functionlity and separate it from
> the 'hidden' utility stuff. Let's have some additinal root
> (harmony.extensions say) specially intended to keep 'java-harmony'
> improvements. What do you think?
I think having a package naming convention for it is good, it gives a
clear indication of the expected 'scope' of API users which is necessary
to understand when you migrate internal APIs. (I'm not keen on the name
'extensions' tho')
Eclipse has quite a simple and intuitive package naming convention:
http://dev.eclipse.org/naming.html
If we do a similar thing that would produce:
org.apache.harmony
root of all package names
org.apache.harmony.<modulename>
separates module namespaces
org.apache.harmony.<modulename>.<something>
types whose API will be carefully managed. Other modules
can use these types in their impl.
org.apache.harmony.<modulename>.internal
types reserved for use only within the module impl. Other
modules should not use these types as they may change.
org.apache.harmony.<modulename>.tests
module's tests
org.apache.harmony.<modulename>.examples
module's examples (if we have any!)
The componentization runtime can enforce the package visibility rules
through the JAR manifest, even allowing 'friend' relationships etc. See
an example of this in the NIO manifest, who only allows LUNI to see the
com.ibm.io.nio package [1].
[1]
http://svn.apache.org/viewcvs.cgi/incubator/harmony/enhanced/classlib/trunk/modules/nio/META-INF/MANIFEST.MF?view=markup
Regards,
Tim
--
Tim Ellison (t.p.ellison@gmail.com)
IBM Java technology centre, UK.