Standardize how to create instances of JDK 5 collections

[GoogleCodeExporter]

First I'll list the specific changes I propose to make, then provide the
full justification below.

Drop:

1. Lists.newArrayListWithCapacity(int)
2. Lists.newLinkedList(Iterator)
3. Lists.newLinkedList(E...)
4. Sets.newLinkedHashSet(Iterator)
5. Sets.newLinkedHashSet(E...)

Add:

1. Lists.newCopyOnWriteArrayList()
2. Lists.newCopyOnWriteArrayList(Iterable)
3. Sets.newCopyOnWriteArraySet()
4. Sets.newCopyOnWriteArraySet(Iterable)
5. Maps.newTreeMap(Map)
6. Maps.newConcurrentHashMap(Map)
7. Maps.newEnumMap(Map)

------

With the lone exception of EnumSet, JDK collections lack useful static
creation methods like

  ArrayList.newInstance()
  ArrayList.newInstance(Iterable)
  etc.

These are important to have for a few reasons:

1. Provided copy constructors require Collection, not permitting Iterable,
varargs, etc.

2. The language spec failed to provide type inference for constructors in
the same way it does for static methods.

We are providing these in our classes called Lists, Sets, and Maps.  (Still
no support for Queues, but I'll file that separately.)  The problem is that
we are wildly inconsistent in what we choose to provide and not to provide.

I propose that we follow these conventions:

For each major interface type, there is one clearly dominant implementation
(ArrayList, HashSet, and HashMap). For these implementations, we should
provide the full complement of creation methods.  For Collection types
these are

1. No parameters
2. Iterable
3. Iterator
4. Varargs/array
5. With sizing parameters

For Map these are

1. No parameters
2. Map
3. With sizing parameters

Then there are the sorted types, which likewise have their dominant
implementations TreeSet and TreeMap.

For TreeSet we should have

1. No parameters
2. Iterable
3. Iterator
4. Varargs/array
5. With comparator
6+:  open issue. should *all* be repeated with comparator? none, or
something in between?

and for TreeMap

1. No parameters
2. Map (copy constructor)
3. With comparator
4. open issue: with both?

Then there are the secondary implementations:

sequential:  LinkedList, LinkedHashSet, LinkedHashMap
concurrent: CopyOnWriteArrayList, CopyOnWriteArraySet, ConcurrentHashMap
enum: EnumSet, EnumMap (but EnumSet doesn't need our help)
weird: IdentityHashMap

For these, I suggest that we provide only the basics.

1. No parameters
2. Iterable/Map copy-constructor (and not even that for IHM)

These would not have the Iterator and varargs forms, and the caller can
make use of Iterators.addAll(), Collections.addAll() and/or Arrays.asList()
to get this functionality.

These would also not have tuning parameters (though I am considering making
an exception for ConcurrentHashMap).

Original issue reported on code.google.com by kevin...@gmail.com on 31 Oct 2007 at 8:26

[GoogleCodeExporter]

Original comment by kevin...@gmail.com on 27 May 2008 at 6:31

• Added labels: 1.0

[GoogleCodeExporter]

Original comment by kevin...@gmail.com on 17 Mar 2009 at 5:10

• Changed state: Fixed