harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tim Ellison <t.p.elli...@gmail.com>
Subject Re: Location for API extensions
Date Thu, 09 Feb 2006 11:40:33 GMT
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.

Mime
View raw message