Migrating methods in Collections

[Doug Lea]

On 12/24/2015 01:14 PM, Brian Goetz wrote:
> Teasing apart the differences: ...
>   - Methods that use null to signal absence (Map.get(), Queue.poll()).

First, notice the convention of using "At" in value-friendly
method names. Not always pretty, but easier to remember.
(And for the moment, just a challenge for anyone to come up
with something better.)

For Map, this convention helps with the issue that we'd prefer
to use Optional vs boxing but must allow boxing for Map.get():

interface AnyMap<K,V> { // ...
     Optional<V> at(K key);
     V at(K key, V defaultValue);
}
interface Map<K,V> extends AnyMap<K,V> { // ...
     V get(Object key);
     V getOrDefault(Object key, V defaultValue);
}

For Queue, there's no good reason for having an Optional-returning
method in addition to added default-returning version, so:

interface AnyQueue<E> extends AnyCollection<E> {
     E remove();
     E element();
     E poll(E defaultValue);
     E peek(E defaultValue);
}

interface Queue<E> extends AnyQueue<E> {
     E poll();
     E peek();
}

Deque is messier but similar:

interface AnyDeque<E> extends AnyQueue<E> {
     void addFirst(E e);
     void addLast(E e);
     boolean offerFirst(E e);
     boolean offerLast(E e);
     E removeFirst();
     E removeLast();
     E getFirst();
     E getLast();
     void push(E e);
     E pop();
     E pollFirst(E defaultValue);
     E pollLast(E defaultValue);
     E peekFirst(E defaultValue);
     E peekLast(E defaultValue);
     boolean removeFirstOccurrence(E e);
     boolean removeLastOccurrence(E e);
}

interface Deque<E> extends AnyDeque<E>, Queue<E> {
     E pollFirst();
     E pollLast();
     E peekFirst();
     E peekLast();
     boolean removeFirstOccurrence(Object o);
     boolean removeLastOccurrence(Object o);
     Iterator<E> descendingIterator();
}