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

[Rémi Forax]

Hi David,

On 01/27/2011 06:27 PM, Brian Goetz wrote:
> 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.

I think you can reduce the number of empty* methods given that
Deque inherits form Queue and NavigableMap inherits from SortedMap.

Also you forget some wildcards in unmodifiableDeque and
unmodifiableNavigableMap.

Rémi

>
> 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