commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Stephen Colebourne" <scolebou...@btopenworld.com>
Subject Re: [Collections] Naming conventions
Date Sat, 15 Jun 2002 17:08:34 GMT
To summarise the discussion so far:

Classes will be created/amended to follow the naming pattern XxxUtils where
Xxx relates to the object being returned by the class. Variations on a theme
(SortedBag as opposed to Bag) will be dealt with in one Util class.

Each Util class will have a number of public static factory methods for
creating collections/objects, and possibly additional methods for
manipulating the collection/object.

Each Util class will implement it's decorators as non-public static nested
classes. If the need arises, they can become full public classes at a later
date. If this occurs, a separate package should be considered (when the need
is identified).

Where the method is a decorator, the naming pattern yyyedXxx will be used,
such as synchronizedMap(Map) or predicatedSet(Set).

SimpleObjectFactory will be renamed to Factory.

ListUtils will be undeprecated.

The resulting changes are:
 CollectionUtils - add decorators
 ListUtils - add decorators, undeprecate
 SetUtils - create with decorators
 MapUtils - add decorators
 BagUtils - create with decorators
 TreeUtils - under consideration
 IteratorUtils - under consideration
 ComparatorUtils - rename methods
 PredicateUtils - separate out decorators
 FactoryUtils - rename methods
 TransformerUtils - under consideration
 LazyCollections - delete with decorators going to ListUtils/MapUtils
 SimpleObjectFactory - rename to Factory
These changes don't break backwards compatability as far as I can see.


Further consideration will be needed of other classes in the API, notably
the Iterator decorators, as to whether they should be deprecated, or have
factory methods on IteratorUtils.

However, I currently like what is outlined above. Any further views? Does it
need a vote? And if not, can we record this discussion in a readme or
something so it is clear to developers as to what the convention is? And
then we can get back to the much more interesting part - coding ;-)

Stephen

----- Original Message -----
From: "Michael A. Smith" <mas@apache.org>
To: "Jakarta Commons Developers List" <commons-dev@jakarta.apache.org>
Sent: Saturday, June 15, 2002 5:15 PM
Subject: Re: [Collections] Naming conventions


> On Sat, 15 Jun 2002, Stephen Colebourne wrote:
> > I thought part of the aim of the Utils was to avoid having top level
> > classes, even if they are package scoped.
>
> yeah, in a way.  They coule also be looked at as convenience methods
> where you only need to import one class name to get all of the
> functionality rather than importing each that you need.
>
> > The problem as I see it is that someone new to the package will come
along
> > and see maybe 60+ classes in the collections package. However, over half
> > could be package scoped with no way to tell. (I reckon most people would
> > scan the class names first, either as java files or javadoc.) By
defining
> > them as static nested classes (package scoped) we avoid the visibility
> > issue. Joshua Bloch's book described it as reducing the 'conceptual
size' of
> > the API.
>
> I wouldn't want all 60+ classes in the collections package, even when
> package private.  To start, I believe adding them as inner classes or
> non-public outer classes in the xUtils.java file would be a good
> starting point (hence they aren't exposed in javadoc or as .java files).
> Then, if a compelling need arises, we can make them public classes, but
> in a separate package (e.g. "org.apache.commons.collections.decorators").
>
> regards,
> michael
>
>
>
> --
> To unsubscribe, e-mail:
<mailto:commons-dev-unsubscribe@jakarta.apache.org>
> For additional commands, e-mail:
<mailto:commons-dev-help@jakarta.apache.org>
>


--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message