The Collections Framework (or Data Structures)



How you organize data in your classes depends on the application:
...

The answers to these types of questions determines the type of collection you should use.




Collection Interfaces



Fundamental interface: Collection<E>

The Set<E>, List<E>, and Queue<E> interfaces are all subinterfaces of the Collection interface. The Collection interface contains methods that apply to all types of sets, lists and queues.

The Map<E> interface is part of the Collections Framework, but does not inherit from Collection.





Two Basic Methods from the Collection Interface



There are others that we will talk about more later.


The add() method

This method adds an object to the collection - it returns true if adding the object actually changes the collection, and false otherwise.


The iterator() method

This method returns an object that implements the Iterator interface. You use the iterator object to visit the elements in the collection, one at a time.




The Iterator Interface



public interface Iterator<E>
{
    E next();
    boolean hasNext();
    void remove();
}



The next() method - returns the next element in the collection if there is one.
The hasNext() method - returns true if there are more elements left to visit.
The remove() method - removes the last element that was returned by next(). Only one call to remove() is permitted before next() is called again. Only use this method to delete collection elements while iterating through the collection.



Note: If you call next() on a collection, and you have reached the end of the collection, next() throws a NoSuchElementException. Call hasNext() before calling next().



Example: To look at all elements in a collection, request an interator and keep calling next() as there are more elements in the collection.
Collection<String> c = new ArrayList<String>();
... //
Iterator<String> iter = c.iterator();
while(iter.hasNext())
{
    String str = iter.next();
    // do something with str - remove it if it starts with a particular character, etc.
}



Advancing an iterator - think of an iterator as being between elements. When next() is called, the iterator jumps over the next element, and returns a reference to the element it jumped over.


Example: Remove the first element in a collection
Collection<Circle> c = new ArrayList<Circle>();
... // add to the collection
Iterator<Circle> it = c.iterator();
it.next(); //  I saw the first element
it.remove(); // remove the first element



Example: What happens when I run this code?
Collection<Circle> c = new ArrayList<Circle>();
...// add 10 elements to the collection
Iterator<Circle> it = c.iterator();
it.next();
it.remove();
it.remove();



Another Example: A First Look at a Generic Method




Example: Write a generic method addEm() that adds all objects in one collection to another:

public static <E> boolean addEm(Collection<E> to, Collection<E> from)
{
... // the return value should indicate whether or not the collection has changed as a result of the method call.
... // finish writing this method, and then write code that calls it



}





The AbstractCollection Class









More from the Collection Interface




java.util.Collection<E>

Iterator<E> iterator() - returns an iterator that can be used to visit the elements in the Collection

int size() - returns number of elements in the collection

boolean isEmpty() - returns true if collection contains no elements

boolean contains(Object o) - returns true if this collection contains an object equal to o

boolean containsAll(Collection<?>  other) - returns true if this collection contains all elements in other
    -- The type Collection<?> is called a wildcard type, and is the super type of all Collection types.
    -- The type of its members match any element type.

boolean add(E obj) - adds obj to collection, and returns true if collection changes as a result of the call

boolean addAll(Collection<? extends E> other) - adds all elements of other collection to this collection. Returns true if this collection is changed as a result of the call.
    -- Collection<? extends E> is a bounded wildcard.
    -- ? stands for an unknown type that inherits from type E.
    -- E is called the upper bound of the wildcard.


boolean remove(Object obj) - removes an object equal to obj from this collection if such an object is in the collection. Returns true if a matching object was removed.


boolean removeAll(Collection<?> other) - removes all elements in other from this collection. Returns true if this collection was modified by the call.


void clear() - removes all elements from this collection.


boolean retainAll(Collection<?> other) - removes all elements from this collection that are not equal to an element in other. Returns true if this collection was changed by the call.


<T> T[] toArray(T[] arr) - returns an array containing the elements in this collection. If the specified array arr is large enough to hold the elements, then the elements are stored in arr (and any unused entries in arr are set to null). Otherwise a new array containing this collection's elements is returned.




Note about constructors in Collection implementations: A class that implements Collection must have a constructor that takes a Collection argument. This constructor initializes the new Collection to contain all elements in the specified collection.


Example: Suppose you have a collection c of Strings (which could be a List, Set, etc). To create a new ArrayList containing all elements of c.

List<String> l = new ArrayList<String>(c);





Recall the Collection methods:
Purpose                                                                                  Methods
Determine number of elements in collection                        size(), isEmpty()
Determine if an object is in collection                                  contains()
Add or remove an element                                                     add(), remove()
Visit elements in collection                                                   iterator()