6407460: provide Collections helper methods for new interfaces in JDK 1.6

[David Schlosnagle]

Hello core-lib-devs,

The recent discussions around Objects.nonNull prompted me to create a
patch (attached) to add the methods below to java.util.Collections for
consistency with existing methods. According to the Annotated Outline
of Collections Framework [1] [2], the unmodifiable<Interface> methods
for some of the newer Collection types (Queue, Deque, NavigableSet,
NavigableMap) seem to be missing, and the empty<Interface> methods for
many new and old interfaces (SortedSet, NavigableSet, Queue, Deque,
SortedMap, NavigableMap) that would also be nice to have.

In some of my projects, I could really benefit from having these
additional Collections.empty* and Collections.unmodifiable* helper
methods to simplify my code. In many cases these are places where
internally a null collection is used to allow for lazy initialization,
but the externally exposed APIs would always return an empty or
unmodifiable collection via a simple toUnmodifiable utility method
(where to include those in the JDK is probably a whole separate
argument). Previously the interfaces exposed in my APIs were often
List, Map, or Set, but more recently I've also been using SortedMap
and SortedSet where applicable, so I've felt a little pain for not
having all of the expected methods in Collections. There are of course
libraries such as Guava that also provide the majority of these (and
much more), but I think it would be nice to have this in the JDK.

There seems to have been some discussion and bug IDs related to some
of these methods over the past few years [3] [4] [5] [6], but I'm
curious if this is something that would be considered for adding to
the Java API, and if so would it be for JDK 1.7 or 1.8 seeing as how
Mark indicated 1.7 was feature complete? I look forward to everyone's
feedback.

+    public static <E> SortedSet<E> emptySortedSet()
+    public static <E> NavigableSet<E> emptyNavigableSet()
+    public static <E> Queue<E> emptyQueue()
+    public static <E> Deque<E> emptyDeque()
+    public static <K, V> SortedMap<K, V> emptySortedMap()
+    public static <K, V> NavigableMap<K, V> emptyNavigableMap()
+    public static <E> NavigableSet<E>
unmodifiableNavigableSet(NavigableSet<E> s)
+    public static <E> Iterator<E> unmodifiableIterator(Iterator<?
extends E> it)
+    public static <E> ListIterator<E>
unmodifiableListIterator(ListIterator<? extends E> it)
+    public static <E> Queue<E> unmodifiableQueue(Queue<? extends E> q)
+    public static <E> Deque<E> unmodifiableDeque(Deque<E> q)
+    public static <K, V> NavigableMap<K, V>
unmodifiableNavigableMap(NavigableMap<K, ? extends V> m)

Here's a little summary of what versions of the JDK contain the
various empty and unmodifiable methods, and which are covered by this
patch:

Interface               empty*  unmodifiable*
----------------------  ------  -------------
Collection              n/a     1.2+
Set                     1.5+    1.2+
List                    1.5+    1.2+
Queue                   patch   patch
Deque                   patch   patch
Map                     1.5+    1.2+
SortedSet               patch   1.2+
SortedMap               patch   1.2+
NavigableSet            patch   patch
NavigableMap            patch   patch
BlockingQueue           ?       ?
TransferQueue           ?       ?
BlockingDeque           ?       ?
ConcurrentMap           ?       ?
ConcurrentNavigableMap  ?       ?
Iterator                1.7+    patch
ListIterator            1.7+    patch

I've updated a few of the jtreg tests as initial sanity checks, but if
this patch were to be considered I'd want to expand those a bit more.
I haven't yet addressed the missing synchronized<Interface> (Queue,
Deque, NavigableSet, NavigableMap), checked<Interface> (Queue, Deque,
NavigableSet, NavigableMap), singleton<Interface> (SortedSet,
NavigableSet, Queue, Deque, SortedMap, NavigableMap) methods. Also, I
haven't created analogous methods for any of the java.util.concurrent
interfaces as I'm not sure that these methods necessarily make sense
for those types.

- Dave

P.S. I submitted a signed OCA to sun_ca at sun.com earlier today, but I'm
assuming it will take a while to be added to
https://sca.dev.java.net/CA_signatories.htm since it is a holiday
weekend here in the USA.

References:
[1]: http://download.oracle.com/javase/6/docs/technotes/guides/collections/reference.html
[2]: http://download.java.net/jdk7/docs/technotes/guides/collections/reference.html
[3]: 4834905: Support read-only Iterator, i.e., without remove():
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4834905
[4]: 5030930: JDK1.5 The method Collections.unmodifiableQueue(Queue<?
extends T>) is missing:
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5030930
[5]: 6407460: (coll) provide Collections helper methods for new
interfaces in JDK 1.6:
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6407460
[6]: How about Collections.emptySorted[Set|Map] ?:
http://markmail.org/message/6u23eysno2mt6ia4
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 6407460.patch
Type: application/octet-stream
Size: 50928 bytes
Desc: not available
URL: <http://mail.openjdk.java.net/pipermail/core-libs-dev/attachments/20110116/c6149ca9/6407460.patch>