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

[Brian Goetz]

Overall these look like good additions.  I haven't reviewed the code in 
detail but a quick sanity check suggests that this is a good direction. 
  There's definitely some more work needed on the testing (for example, 
testing that the contents of x and unmodifiable(x) are identical, 
testing that the unmodifiable collection reflects changes in the 
underlying mutable collection, testing the sortedSet/navigableSet 
methods for empty{Sorted,Navigable}Set, etc).

As to the concurrent collection interfaces, I don't think they're 
strictly needed, but they do make sense.  The methods added by 
ConcurrentMap over Map are all mutative, so immutableMap(concurrentMap) 
should produce the desired behavior but not necessarily the desired 
contract.

On 1/16/2011 6:42 PM, David Schlosnagle wrote:
> 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