Java collections framework: Interfaces

In previous article, we had an brief overview of the Java collections framework. Collections framework consists of Collection interfaces, Implementation classes, Algorithms, Infrastructure interfaces, and Array Utilities. In this article we will try to look deeper into the collection interfaces.

Collection Interfaces

Collection interfaces can be divided into two groups. First group of interfaces are the descendants of java.util.Collection interface, while the second group is based on java.util.Map interface.

1) java.util.Collection

• It is the root interface of the collections framework. Some implementations allow duplicate and others don't. Similarly, some implementations are ordered, and others are unordered.
• There is no direct implementation class provided by Java JDK for this interface. Instead, implementations are provided for more specific child interfaces like java.util.List, java.util.Set, etc.
• The main use case of Collection interface is to pass it and use it where very general functionalities are required. This also gives a great flexibility. Being a root interface it can be used as a reference type for different types of collections.
• For an user-defined unordered collection that can contain duplicates, we can directly implement this interface.
• It inherits from Iterable interface.
• Some of the important methods

--> size() : returns number of elements in the collection.

--> isEmpty() : returns true if collection doesn't contain any element.

--> contains(Object o) : returns true if collection contains the specified element i.e. condition (o==null ? e==null : o.equals(e)) must return true for at least one element e in the collection. This method can throw ClassCastException (if the type of specified element o is incompatible with the collection), or can also throw NullPointerException (is the specified element o is null & collection doesn't permit null elements).

--> iterator() : returns an iterator over the elements of the collection. The order in which we get the elements from this iterator depends on the implementation class.

--> toArray() : returns an array containing all the elements of the collection.

--> add(E e) : adds the element e in the collection. If the collection is changed, the method returns true. The implementation classes can restrict the type of elements allowed to be added in this collection. If the element is not allowed to be added then the method can throw an exception. Exceptions thrown by this method are UnsupportedOperationException (if add operation itself is not allowed for that implementation), ClassCastException (is the specified element type is not allowed), NullPointerException (if null is not allowed and the specified element is null), IllegalArgumentException (is some property of the specified element is not allowed), IllegalStateException (if element can't be added this time due to insertion restrictions).

--> remove(Object o) : removes a single instance of the specified element such that (o==null ? e==null : o.equals(e)). Method returns true if the specified element is found and removed successfully. This method throws ClassCastException, NullPointerException and UnsupportedOperationException.

--> clear() : removes all the elements from the collection. Throws UnsupportedOperationException.

--> stream() : returns a sequential Stream with the given collection as its source.

--> parallelStream() : returns a parallel Stream with the given collection as its source. Implementation of this method can also return a sequential stream.

2) java.util.Set

• Set based collections can't contain duplicate elements i.e. no pair of two elements e1 and e2 present in the Set can have e1.equals(e2) as true.
• It can have at most one null element. Some implementations prohibit null elements even once.
• It inherits from Iterable & Collection interface.
• Some important methods

--> size()

--> isEmpty()

--> contains(Object o)

--> iterator()

--> toArray()

--> add(E e) : Adds the provided element e, if its not already present (i.e. (e==null ? e2==null : e.euals(e2))), otherwise if the element is already present the Set is left unchanged, and false is returned. Exceptions thrown by this method are UnsupportedOperationException (if add operation itself is not allowed for that implementation), ClassCastException (is the specified element type is not allowed), NullPointerException (if null is not allowed and the specified element is null), IllegalArgumentException (is some property of the specified element is not allowed)

--> remove(Object o) : removes the specified object if it is present and returns true.

--> addAll(Collection c) : adds all the elements of the specified collection (if they are not already present)

--> clear()

3) java.util.SortedSet

• If a Set needs to further provide ordering on its element. The ordering is either provided using natural sorting order of the elements, or using a Comparator provided during creation of the SortedSet.
• All the elements inserted must implement Comparable interface (required for natural sorting).
• Ordering maintained by SortedSet, must be consistent with equals (to correctly implement Set interface). SortedSet performs element comparison using either compareTo or compare method, while Set interface is defined based on equals method. So, to be consistent two elements defined equal by equals method, must also be equal based on the compareTo/compare method.
• It inherits from Iterable, Set & Collection interface.
• Some important methods :

--> comparator() : returns comparator used to order the elements. null is returned if the set uses the natural sorting.

--> subset(E fromElement, E toElement) : returns SortedSet with elements from fromElement(inclusive) and toElement(exclusive). If fromElement and toElement are equal, returned SortedSet is empty. The returned Set is backed by the original SortedSet, so any changes in the SortedSet will be reflected in the returned Set. Throws ClassCastException, NullPointerException, and IllegalArgumentException(if fromElement is greater than the toElement)

--> headset(E toElement) : returns SortedSet with elements strictly less than toElement.The returned Set is backed by the original SortedSet, so any changes in the SortedSet will be reflected in the returned Set. Throws ClassCastException, NullPointerException, and IllegalArgumentException

--> tailSet(E fromElement) : returns SortedSet with elements greater than or equal to fromElement. The returned Set is backed by the original SortedSet, so any changes in the SortedSet will be reflected in the returned Set. Throws ClassCastException, NullPointerException, and IllegalArgumentException.

--> first() : returns the lowest element in the set.

--> last() : returns the highest element in the set.

4) java.util.List

• To represent ordered collection (sequence). Allows to access/search elements by using their index/position, and also gives more precise control over the element insertion position.
• Typically allow duplicate elements.
• The Lists follow zero based indexing.
• List interface provides a special iterator, called ListIterator, that allows both element insertion and replacement, and even allows bi-directional access to the elements.
• It inherits from Iterable, & Collection interface.
• Some important methods :

--> size()

--> isEmpty()

--> contains(Object o)

--> iterator()

--> toArray()

--> add(E e) : appends the element to the end of the list. Throws UnsupportedOperationException, ClassCastException, NullPointerException, IllegalArgumentException

--> remove(object o) : removes the first occurrence of the specified element from the list.

--> sort(Comparator c) : sorts the list based on the provided Comparator. if null is provided as Comparator, natural sorting order is used. Modifies the original list itself.

--> clear()

--> get(int index) : returns the element at the specified position. Throws IndexOutOfBoundsException.

--> set(int index, E element) : replaces the element at the specified position in this list with the specified element. Throws UnsupportedOperationException, ClassCastException, NullPointerException, IllegalArgumentException, IndexoutOfBoundsException

--> add(int index, E element) : inserts the specified element at the specified position. Shifts the element currently at that position and other subsequent elements to the right. Throws UnsupportedOperationException, ClassCastException, NullPointerException, IllegalArgumentException, IndexoutOfBoundsException

--> remove(int index) : removes the element at the specified position. Shifts subsequent elements to the left. Also returns the element that was removed. Throws UnsupportedOperationException,and IndexoutOfBoundsException.

--> indexOf(Object o) : returns the index of the first occurrence of the specified element, or -1 if element is not found. Throws ClassCastException, NullPointerException.

--> lastIndexof(Object o) : returns the index of the last occurrence of the specified element, or -1 if element is not found. Throws ClassCastException, NullPointerException.

--> listIterator()

--> subList(int fromIndex, int toIndex) : returns a list, containing a portion of the original list between fromIndex(inclusive), and toIndex(exclusive). If fromIndex and toIndex are equal an empty list is returned. The returned List is backed by the original List, so any non-structural changes in the original list will be reflected in the returned List.

5) java.util.Queue

• Queues can be used for holding elements before they are processed.
• Apart from the basic Collection operations, they also provide additional insertion, removal, and inspection operations. It provides these method in two configurations. Firstly, those which throw an exception if operation fails, while the others, returns null/false.

For insertion, add(e) method throws exception on failure, while offer(e) method returns false.

Similarly, for removal and inspection, remove() & element() methods throw exception, while poll() and peek() methods return null.

• Queues typically order elements in FIFO manner, but some implementations like priority queues order either based on the Comparator, or natural sorting order of elements. Similarly stacks order in LIFO order.
• inherits from Iterable, & Collection interface.
• Some methods :

--> add(E e) : Inserts the specified element into this queue and returns true. Throws IllegalStateException if no space is currently available. Also throws ClassCastException, NullPointerException, and IllegalArgumentException.

--> offer(E e) : Inserts the specified element into this queue. Doesn't throw an exception, instead returns false if operation fails due to capacity restrictions. But still throws ClassCastException, NullPointerException, and IllegalArgumentException.

--> remove() : Retrieves and removes the head of the queue. Throws NoSuchElementException, is queue is empty.

--> poll() : Retrieves and removes the head of the queue, or returns null if the queue is empty.

--> element() : Retrieves, but does not remove, the head of this queue. Throws NoSuchElementException, is queue is empty.

--> peek() : Retrieves, but does not remove, the head of this queue, or returns null if this queue is empty.

6) java.util.Deque

• Queue that supports element insertion, removal and inspection from both ends.
• Similar to Queues, they also provide two types of methods, one which throw exception on operation failure, while others, don't throw exception and return null/false.
• It inherits from Iterable, Queue, and Collection interfaces.
• can be used both as FIFO queue and LIFO stacks.
• Some methods :

--> addFirst(E e) : Inserts the specified element at the front of this deque and throws IllegalStateException if no space is available.

--> addLast(E e) : Inserts the specified element at the end of this deque and throws IllegalStateException if no space is available.

--> offerFirst(E e) : Inserts the specified element at the front of this deque, and returns false if no space is available.

--> offerLast(E e) : Inserts the specified element at the end of this deque, and returns false if no space is available.

--> removeFirst() : Retrieves and removes the first element of this deque. throws NoSuchElementException if this deque is empty.

--> removeLast() : Retrieves and removes the last element of this deque. throws NoSuchElementException if this deque is empty.

--> pollFirst() : Retrieves and removes the first element of this deque, or returns null if this deque is empty.

--> pollLast() : Retrieves and removes the last element of this deque, or returns null if this deque is empty.

--> getFirst() : Retrieves, but does not remove, the first element of this deque. throws NoSuchElementException if this deque is empty.

--> getLast() : Retrieves, but does not remove, the last element of this deque. throws NoSuchElementException if this deque is empty.

--> peekFirst() : Retrieves, but does not remove, the first element of this deque, or returns null if this deque is empty.

--> peekLast() : Retrieves, but does not remove, the last element of this deque, or returns null if this deque is empty.

--> push(E e) : Pushes an element onto the stack represented by this deque (in other words, at the head of this deque). throws IllegalStateException if no space is available. This method is equivalent to addFirst(E e) method.

--> pop() : Pops an element from the stack represented by this deque. In other words, removes and returns the first element of this deque. throws NoSuchElementException if this deque is empty. This method is equivalent to removeFirst().

Map based interfaces

1) java.util.Map

• Maps can be used to represent an object that maps keys to values.
• duplicate keys are not allowed in a Map. Also, each key can map to at most one value.
• Map interface provides methods to view the map's content as set of keys, collection of values, or set of key-value mappings.
• some methods :

--> size() : returns the number of key-value entries.

--> isEmpty() : returns true if map doesn't contain any entry (key-value)

--> containsKey(Object key) : returns true if map contains the specified key. Throws CassCastException, and NullPointerException

--> containsValue(Object value) : returns true if the map contains one or more keys which are mapped to the given value. Throws ClassCastException, and NullPointerException.

--> get(Object key) : returns the value which is mapped to the specified key, or null if the map doesn't contain any mapping for the given key. Throw ClassCastException, and NullPointerException.

****** If this map permits null values, then a return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.

--> put(K key, V vaue) : Associates the specified value with the specified key. If the map already had the key, then the old value will be replaced. This method returns the old associated value, or null if there was no old mapping. Throws ClassCastExeption, NullPointerException, and IllegalArgumentException.

--> remove(Object key) : removes the provided key and its associated value. returns the value associated with the key, or null if no value was found. Throws UnsupportedOperationException, ClassCastEception, and NullPointerException.

--> clear() : removes all the key-value entries from the map. Throws UnsupportedOperationException.

--> keySet() : returns a Set containing all the keys. Any change in the map, will be reflected in the Set as well. Similarly, if we remove anything from the Set, it will also remove corresponding mapping from the map.

--> values() : returns a Collection containing all the values.

--> entrySet() : returns a Set containing all the key-value entries in the map.

2) java.util.map.Entry

• It is used to represent the key-value pair of a map. The entrySet() method of the Map interface returns a Set whose elements are of Entry type. Only way to get a reference to a particular entry object is by using the iterator over the elements of this Set.
• Some Methods :

--> getkey() : returns the key corresponding to this entry.

--> getValue() : returns the value corresponding to this entry.

--> setValue() : replaces the current value corresponding to this entry with a new value. Throws UnsupportedOperationException, ClassCastException, NullPointerException, IllegalArgumentException, and IllegalStateException (if the entry itself has been removed from the original Map object)

3) java.util.SortedMap

• If a Map needs to further provide ordering on its keys. The ordering is either provided using natural sorting order of the key type, or using a Comparator provided during creation of the SortedMap.
• All the keys inserted must implement Comparable interface (required for natural sorting).
• Ordering maintained by SortedMap, must be consistent with equals (to correctly implement Map interface). SortedMap performs all key comparison using either compareTo or compare method, while Map interface is defined based on equals method. So, to be consistent two keys defined equal by equals method, must also be equal based on the compareTo/compare method.
• It inherits from Map interface.
• Some important methods :

--> comparator() : returns comparator used to order the keys. null is returned if the set uses the natural sorting.

--> subMap(E fromKey, E toKey) : returns SortedMap with keys from fromKey(inclusive) and toKey(exclusive). If fromKey and toKey are equal, returned SortedMap is empty. The returned Map is backed by the original SortedMap, so any changes in the SortedMap will be reflected in the returned Map. Throws ClassCastException, NullPointerException, and IllegalArgumentException(if fromKey is greater than the toKey)

--> headMap(E toKey) : returns SortedMap with elements strictly less than toKey. The returned Map is backed by the original SortedMap, so any changes in the SortedMap will be reflected in the returned Map. Throws ClassCastException, NullPointerException, and IllegalArgumentException

--> tailMap(E fromKey) : returns SortedMap with keys greater than or equal to fromKey. The returned Map is backed by the original SortedMap, so any changes in the SortedMap will be reflected in the returned Map. Throws ClassCastException, NullPointerException, and IllegalArgumentException.

--> firstKey() : returns the lowest key in the map.

--> lastKey() : returns the highest key in the map.