You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by "Jack, Paul" <pj...@sfaf.org> on 2002/06/12 19:24:05 UTC
RE: [Collections] Naming conventions [was ComparableComparator -
nulls OK]
I think this is definitely a step in the right direction,
but that the ultimate strategy you've outlined is still
a little confusing.
Basically, we currently have two categories of decorator
classes:
1. Things like ComparatorUtils, that provide a variety
of decorator functionality for the same interface;
2. Things like LazyCollections, that provide the same
decorator functionality for a variety of interfaces.
In your strategy, we're still using two naming conventions
for decorators. This seems confusing to me.
I'd rather standardize on one approach to our decorator
classes, and treat them all as #1 above. In my ideal
world, we'd have these classes:
Collections -- provides decorators for Collection
Predicates -- provides decorators for Predicate
Comparators -- provides decorators for Comparator
and so on. Collections would contain decorators for
subinterfaces of Collection as well. That does mean
that Collections would contain about twenty methods,
but they'd all be polymorphic variations on the same
themes, so I think the API would still be easy to
absorb and use. java.util.Arrays contains 55 methods
but they're all variations on the same 5 themes, and
I consider the class to be quite useful.
Alas, there is a naming collision with java.util.Collections,
so my ideal world is just a dream. We'd have to come up with
another convention for the decorator class names.
But do you see what I'm getting at here?
-Paul
> -----Original Message-----
> From: Stephen Colebourne [mailto:scolebourne@eurobell.co.uk]
> Sent: Tuesday, June 11, 2002 4:20 PM
> To: Jakarta Commons Developers List
> Subject: [Collections] Naming conventions [was ComparableComparator -
> nulls OK]
>
>
> 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>
--
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]
Posted by Stephen Colebourne <sc...@eurobell.co.uk>.
Good argument, and logical. However the 'Collections' class could have 6 or
more groups of decorators if the dreams become reality. Maybe this isn't a
problem, but I wouldn't want that class to contain all the static nested
classes (for maintainability)
There is another factor - the classes don't just contain decorators.
FactoryUtils/PredicateUtils (current names) create Factory/Predicate objects
not decorate them.
Some possibilities:
- CollectionUtils
ie. add to existing class, probably should merge in ListUtils too - this
seems quite a big change. And MapUtils doesn't fit well (its rather a
strange group of methods)
- Decorators
- CollectionDecorators
- DecoratedCollections
- DecoratorUtils
these emphasise the role of the resultant classes, but how is the source
laid out
- SynchronizedCollections, PredicatedCollections, ... as I originally
proposed
these emphasise the particular decorator, and fit well with managable source
units
Deciding where the source will go is another factor in this. Nice can of
worms!
Stephen
----- Original Message -----
From: Jack, Paul <pj...@sfaf.org>
To: 'Jakarta Commons Developers List' <co...@jakarta.apache.org>
Sent: Wednesday, June 12, 2002 6:24 PM
Subject: RE: [Collections] Naming conventions [was ComparableComparator -
nulls OK]
> I think this is definitely a step in the right direction,
> but that the ultimate strategy you've outlined is still
> a little confusing.
>
> Basically, we currently have two categories of decorator
> classes:
>
> 1. Things like ComparatorUtils, that provide a variety
> of decorator functionality for the same interface;
> 2. Things like LazyCollections, that provide the same
> decorator functionality for a variety of interfaces.
>
> In your strategy, we're still using two naming conventions
> for decorators. This seems confusing to me.
>
> I'd rather standardize on one approach to our decorator
> classes, and treat them all as #1 above. In my ideal
> world, we'd have these classes:
>
> Collections -- provides decorators for Collection
> Predicates -- provides decorators for Predicate
> Comparators -- provides decorators for Comparator
>
> and so on. Collections would contain decorators for
> subinterfaces of Collection as well. That does mean
> that Collections would contain about twenty methods,
> but they'd all be polymorphic variations on the same
> themes, so I think the API would still be easy to
> absorb and use. java.util.Arrays contains 55 methods
> but they're all variations on the same 5 themes, and
> I consider the class to be quite useful.
>
> Alas, there is a naming collision with java.util.Collections,
> so my ideal world is just a dream. We'd have to come up with
> another convention for the decorator class names.
>
> But do you see what I'm getting at here?
>
> -Paul
>
> > -----Original Message-----
> > From: Stephen Colebourne [mailto:scolebourne@eurobell.co.uk]
> > Sent: Tuesday, June 11, 2002 4:20 PM
> > To: Jakarta Commons Developers List
> > Subject: [Collections] Naming conventions [was ComparableComparator -
> > nulls OK]
> >
> >
> > 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>
>
> --
> 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>