Java Collections Framework: Collection Interface

Reading time: 15 minutes

The Collection interface (java.util.Collection) is one of the root interfaces of the Java collection classes. A collection represents a group of objects known as its elements. The Java platform doesn’t provide any direct implementations of this interface.

This interface has methods to determine the number of elements in the collection (size, isEmpty), to check whether a given object is in the collection (contains), to add and remove an element from the collection (add, remove) and to provide an iterator over the collection (iterator). Collection interface also provides bulk operation methods that work on entire collection such as containsAll, addAll, removeAll, retainAll and clear. The toArray methods are provided as a bridge between collections and older APIs that expect arrays on input.

The following 6 interfaces extends the Collection interface:

  • List
  • Set
  • SortedSet
  • NavigableSet
  • Queue
  • Deque
6 interfaces extending the Collection interface

Java does not come with a usable implementation of the Collection interface, so you will have to use one of the listed subtypes. The Collection interface just defines a set of methods (behaviour) that each of these Collection subtypes share. This makes it possible ignore what specific type of Collection you are using, and just treat it as a Collection. This is standard inheritance, so there is nothing magical about, but it can still be a nice feature from time to time. Later sections in this text will describe the most used of these common operations.

Here is a method that operates on a Collection:


public class MyCollectionUtil
{
  public static void doSomething(Collection collection) 
  {
    Iterator iterator = collection.iterator();
    while(iterator.hasNext())
    {
      Object object = iterator.next();
      //do something to object here...
    }
  }
}

And here are a few ways to call this method with different Collection subtypes:


Set  set  = new HashSet();
List list = new ArrayList();

MyCollectionUtil.doSomething(set);
MyCollectionUtil.doSomething(list);   

Adding and Removing Elements


Regardless of what Collection subtype you are using there are a few standard methods to add and remove elements from a Collection. Adding and removing single elements is done like this:


String     anElement  = "an element";
Collection collection = new HashSet();

boolean didCollectionChange = collection.add(anElement);
boolean wasElementRemoved   = collection.remove(anElement);    

add() adds the given element to the collection, and returns true if the Collection changed as a result of calling the add() method. A Set for instance may not have changed. If the Set already contained that element, it is not added again. On the other hand, if you called add() on a List and the List already contained that element, the element would then exist twice in the List.

remove() removes the given element and returns true if the removed element was present in the Collection, and was removed. If the element was not present, the remove() method returns false.

You can also add and remove collections of objects. Here are a few examples:


Set  aSet  = ... // get Set  with elements from somewhere
List aList = ... // get List with elements from somewhere

Collection collection = new HashSet();

collection.addAll(aSet);    //returns boolean too, but ignored here.
collection.addAll(aList);   //returns boolean too, but ignored here.

collection.removeAll(aList);   //returns boolean too...
collection.retainAll(aSet);    //returns boolean too...

addAll() adds all elements found in the Collection passed as parameter to the method. The Collection object itself is not added. Only its elements. If you had called add() with the Collection as parameter instead, the Collection object itself would have been added, not its elements.

Exactly how thet addAll() method behaves depends on the Collection subtype. Some Collection subtypes allows the same element to be added more than once, and others do not.

removeAll() removes all elements found the Collection passed as parameter to the method. If the Collection parameter contains any elements not found the target collection, these are just ignored.

retainAll() does the opposite of removeAll(). Instead of removing all the elements found in the parameter Collection, it keeps all these elements, and removes all other elements. Keep in mind, that only if the elements were already contained in the target collection, are they retained. Any new elements found in the parameter Collection which are not in the target collection, are not automatically added. They are just ignored.

Let us see an example using some pseudo-language:


Collection colA = [A,B,C]
Collection colB = [1,2,3]

Collection target = [];

target.addAll(colA);     //target now contains [A,B,C]
target.addAll(colB);     //target now contains [A,B,C,1,2,3]

target.retainAll(colB);  //target now contains [1,2,3]

target.removeAll(colA);  //nothing happens - already removed
target.removeAll(colB);  //target is now empty.

Checking if a Collection Contains a Certain Element


The Collection interface has two methods to check if a Collection contains one or more certain elements. These are the contains() and containsAll() methods. They are illustrated here:


Collection collection   = new HashSet();
boolean containsElement = collection.contains("an element");

Collection elements     = new HashSet();
boolean containsAll     = collection.containsAll(elements);

contains() returns true if the collection contains the element, and false if not.

containsAll() returns true if the collection contains all the elements in the parameter collection, and false if not.


Collection Size


You can check the size of a collection using the size() method. By "size" is meant the number of elements in the collection. Here is an example:


int numberOfElements = collection.size();    

Iterating a Collection
You can iterate all elements of a collection. This is done by obtaining an Iterator from the collection, and iterate through that. Here is how it looks:

Collection collection = new HashSet();
//... add elements to the collection

Iterator iterator = collection.iterator();
while(iterator.hasNext()){
    Object object = iterator.next();
    //do something to object;    
}
You can also use the new for-loop:

Collection collection = new HashSet();
//... add elements to the collection

for(Object object : collection) {
  //do something to object;
}

Applications


Applications of Java Collection Interface are:

  • Useful classes such as List, Set, SortedSet and others are used for various specific purposes

  • This interface has the ability to manage all data in a single data structure.