[Collections] Naming conventions [was ComparableComparator - nulls OK]

[Stephen Colebourne <sc...@eurobell.co.uk>]

Hi all,
Seeing as the collections package seems to be growing very quickly, and some
of the original classes were perhaps not named or grouped perfectly, I was
thinking that we might take this opportunity to agree some naming
conventions. I know, yawn, yawn, but anyway...

Here are the existing or potential decorator/wrapper class groups for
collections:
* Predicate (block entry into a collection, currently in PredicateUtils)
* Lazy (creates elements on demand, currently in LazyCollections)
* Unmodifiable (tbd)
* Synchronized (tbd)
* Event generators (tbd, not sure if decorators)
* Filter (tbd, return size etc. based on filter, ie. predicate)

Here are the existing or potential class groups for non-collections:
* Predicate (common predicates, currently in PredicateUtils)
* Factory (common factories, currently FactoryUtils)
* Comparator (common comparators, currently ComparatorUtils)
* Transform (tbd)
* Closure (tbd)
* Iterator (tbd)

Here are the collection assistant classes:
* CollectionUtils (utils for Collection)
* ListUtils (utils for List)
* MapUtils (utils for Map)

Sun's example is one class Collections with all of the above in, but that
isn't practical for us. It would be too big. I also believe that a single
WrapperUtils would also be too big. Thus I propose the following structure
(where xxx varies):

* XxxedCollections - for decorators, implemented as inner classes - thus
PredicatedCollections (renamed from PredicateUtils),  FilteredCollections,
SynchronizedCollections, etc.

* Xxxs - for non-collections, implemented as inner classes - thus
Comparators (renamed from ComparatorUtils),  Factories (renamed from
FactoryUtils), Predicates (renamed from PredicateUtils), etc.

* XxxUtils - for assistants to the collections themselves (ie.no change to
current naming)

Within the XxxedCollections classes, I propose following the Sun convention
for method names:
synchronizedMap(Map) on SynchronizedCollections
unmodifiableMap(Map) on UnmodifiableCollections
predicatedMap(Map) on PredicatedCollections
filteredMap(Map) on FilteredCollections
etc.

Within the Xxxs non-collections classes, I propose similar:
nullFirstComparator(Comparator)  on Comparators
instanceofPredicate(Class) on Predicates
etc.

If we do this right, some of the current top level classes (eg.iterators)
could be deprecated and become merged into a factory style class, to the
benefit of the interface size.

Well thats my input (sorry for the long email!). We could really do with an
agreement on this ;-) Note all these changes can be made as none affect
released classes.

Stephen


----- Original Message -----
From: Jonathan Carlson <jo...@yahoo.com>
> > We already have predicate wrappers and lazy wrappers;
> > the JDK puts all of its wrappers in one monolithic class;
> > what do people think of having just one giant
> > WrapperUtils?
>
> I would encourage the use of the term "Decorator" instead
> of "Wrapper".  The more concise we can be with language,
> the better IMHO (Assuming everything that util class would
> only add decorators. If it starts also doing Adapters and
> such then a less concise term like wrapper is better).  :-)
>
> Jonathan
>
>
> --- "Jack, Paul" <pj...@sfaf.org> wrote:
> > Actually, that's a good point.  There are some other
> > considerations behind the long convention...
> >
> > Technically it's possible for a collection to implement
> > both Set and Bag (getCount() would always return 1 or 0;
> > uniqueSet would return an unmodifiable view of itself)...
> >
> > I'm not saying such an implementation would be useful;
> > but it is legal.  If such a SetBag existed, then these
> > methods become ambiguous:
> >
> > Set predicate(Set, Predicate)
> > Bag predicate(Bag, Predicate)
> >
> > Which method does the compiler pick when I invoke
> > PredicateUtils.predicate(new SetBag(), pred)?
> >
> > You can force one method or the other using an explicit
> > cast, but it seems cleaner to have altogether distinct
> > method signatures.
> >
> > Not really much of a consideration given our current
> > API -- like I said, SetBag would be pretty pointless --
> > but it's conceivable that there may be future Collection
> > interfaces that can be implemented simultaneously.
> >
> > Also, if we wanted to be completely strict, then we'd
> > use "predicatedSet" instead of "predicateSet" -- the
> > JDK wrappers are all specified with an adjective.
> >
> > Also, in another thread, somebody raised the issue of
> > providing unmodifiable wrappers for Bag, SortedBag,
> > Iterator and ListIterator.  And MultiMap.  I'd also like
> > to see synchronized wrappers for Bag, SortedBag,
> > MultiMap.
> > We already have predicate wrappers and lazy wrappers;
> > the JDK puts all of its wrappers in one monolithic class;
> > what do people think of having just one giant
> > WrapperUtils?
> > It could contain all the predicate, lazy, future
> > unmodifiable and synchronized wrappers.  (I think it
> > would
> > still make sense to organize the source into multiple
> > files; but the public API would be just one class).
> >
> > -Paul
> >
> >
> >
> > > -----Original Message-----
> > > From: Michal Plechawski
> > [mailto:Michal.Plechawski@empolis.pl]
> > > Sent: Tuesday, June 11, 2002 5:18 AM
> > > To: Jakarta Commons Developers List; Stephen Colebourne
> > > Subject: Re: [Collections] ComparableComparator - nulls
> > OK
> > >
> > >
> > > Hello,
> > >
> > > > > What do you think of
> > > > >     Set predicate(Set set, Predicate predicate)
> > > > > ?  Is that too nondescript?
> > > >
> > > > Actually, there is another factor involved. The
> > > java.utils.Collections class
> > > > uses the long form, eg.
> > > > Collections.unmodifiableMap(Map);
> > > >
> > > > Thus I would prefer the long form. We could agree to
> > differ
> > > from Sun
> > > > however, in which case I would submit a patch to the
> > Predicate
> > > code.
> > >
> > > IMHO Sun has just one argument for leaving the
> > "Map"-like suffix.
> > > It gives a possiblity of all the following to coexist:
> > >
> > >   List unmodifiableList(List l)
> > >   Set unmodifiableSet(Set s)
> > >   Set unmodifiableSet(List l)
> > >
> > > However, I do not see this as a strong argument. But
> > mimicring
> > > the Sun's conventions should be a good idea.
> > >
> > > Michal
> > >
> > >
> > > --
> > > To unsubscribe, e-mail:
> > > <ma...@jakarta.apache.org>
> > > For additional commands, e-mail:
> > > <ma...@jakarta.apache.org>
> > >
> >
> > --
> > To unsubscribe, e-mail:
> > <ma...@jakarta.apache.org>
> > For additional commands, e-mail:
> > <ma...@jakarta.apache.org>
> >
>
>
> =====
> Jonathan Carlson
> joncrlsn@users.sf.net
> Minneapolis, Minnesota
>
> __________________________________________________
> Do You Yahoo!?
> Yahoo! - Official partner of 2002 FIFA World Cup
> http://fifaworldcup.yahoo.com
>
> --
> To unsubscribe, e-mail:
<ma...@jakarta.apache.org>
> For additional commands, e-mail:
<ma...@jakarta.apache.org>
>
>


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: [Collections] Naming conventions [was ComparableComparator - nulls OK]

["Michael A. Smith" <ma...@apache.org>]

On Wed, 12 Jun 2002, Stephen Colebourne wrote:
> If we do this right, some of the current top level classes (eg.iterators)
> could be deprecated and become merged into a factory style class, to the
> benefit of the interface size.
> 
> Well thats my input (sorry for the long email!). We could really do with an
> agreement on this ;-) Note all these changes can be made as none affect
> released classes.

I was a bit unsure that such a reorganization would not affect released
classes, mainly because I had forgotten what was in the 2.0 release and
what has been added since then.  To help figure that out, I went through
all the classes and added @since tags for all the released classes.  I
didn't have enough minutes this evening to figure out what the
compability impact really would be though.

Btw, no apologies needed for the long email.  You've expressed a lot of
great ideas; ones which I hope we will be able to implement so users
will have an easier time using the code that we provide.

regards,
michael


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>