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 Fri, 10 Feb 2006 09:25:24 GMT
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.

Mime
View raw message