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
