Tech and Media Labs
This site uses cookies to improve the user experience.




Java Collections - List

Jakob Jenkov
Last update: 2015-07-05

The java.util.List interface is a subtype of the java.util.Collection interface. It represents an ordered list of objects, meaning you can access the elements of a List in a specific order, and by an index too. You can also add the same element more than once to a List.

Java List Tutorial Video

If you prefer to watch a video instead of reading text, here is a video version of this Java List tutorial:

List Implementations

Being a Collection subtype all methods in the Collection interface are also available in the List interface.

Since List is an interface you need to instantiate a concrete implementation of the interface in order to use it. You can choose between the following List implementations in the Java Collections API:

  • java.util.ArrayList
  • java.util.LinkedList
  • java.util.Vector
  • java.util.Stack

There are also List implementations in the java.util.concurrent package, but I will leave the concurrency utilities out of this tutorial.

Here are a few examples of how to create a List instance:

List listA = new ArrayList();
List listB = new LinkedList();
List listC = new Vector();
List listD = new Stack();

Adding and Accessing Elements

To add elements to a List you call its add() method. This method is inherited from the Collection interface. Here are a few examples:

List listA = new ArrayList();

listA.add("element 1");
listA.add("element 2");
listA.add("element 3");

listA.add(0, "element 0");

The first three add() calls add a String instance to the end of the list. The last add() call adds a String at index 0, meaning at the beginning of the list.

The order in which the elements are added to the List is stored, so you can access the elements in the same order. You can do so using either the get(int index) method, or via the Iterator returned by the iterator() method. Here is how:

List listA = new ArrayList();

listA.add("element 0");
listA.add("element 1");
listA.add("element 2");

//access via index
String element0 = listA.get(0);
String element1 = listA.get(1);
String element3 = listA.get(2);


//access via Iterator
Iterator iterator = listA.iterator();
while(iterator.hasNext(){
  String element = (String) iterator.next();
}


//access via new for-loop
for(Object object : listA) {
    String element = (String) object;
}

When iterating the list via its Iterator or via the for-loop (which also uses the Iterator behind the scene), the elements are iterated in the same sequence they are stored in the list.

Removing Elements

You can remove elements in two ways:

  1. remove(Object element)
  2. remove(int index)

remove(Object element) removes that element in the list, if it is present. All subsequent elements in the list are then moved up in the list. Their index thus decreases by 1.

remove(int index) removes the element at the given index. All subsequent elements in the list are then moved up in the list. Their index thus decreases by 1.

Clearing a List

The Java List interface contains a clear() method which removes all elements from the list when called. Here is simple example of clearing a List with clear():

List list = new ArrayList();

list.add("object 1");
list.add("object 2");
//etc.

list.clear();

List Size

You can obtain the number of elements in the List by calling the size() method. Here is an example:

List list = new ArrayList();

list.add("object 1");
list.add("object 2");

int size = list.size();

Generic Lists

By default you can put any Object into a List, but from Java 5, Java Generics makes it possible to limit the types of object you can insert into a List. Here is an example:

List<MyObject> list = new ArrayList<MyObject>();

This List can now only have MyObject instances inserted into it. You can then access and iterate its elements without casting them. Here is how it looks:

MyObject myObject = list.get(0);

for(MyObject anObject : list){
   //do someting to anObject...
}

For more information about Java Generics, see the Java Generics Tutorial.

Iterating a List

You can iterate a Java List in several different ways. I will cover the three most common mechanisms here.

The first way to iterate a List is to use an Iterator. Here is an example of iterating a List with an Iterator:

List list = new ArrayList();

//add elements to list

Iterator iterator = list.iterator();
while(iterator.hasNext()) {
    Object next = iterator.next();
}

You obtain an Iterator by calling the iterator() method of the List interface.

Once you have obtained an Iterator you can keep calling its hasNext() method until it returns false. Calling hasNext() is done inside a while loop as you can see.

Inside the while loop you call the next() method of the Iterator interface to obtain the next element pointed to by the Iterator.

If the List is typed you can save some object casting inside the while loop. Here is an example:

List<String> mylistStr = new ArrayList<>();

Iterator<String> iterator = mylistStr.iterator();
while(iterator.hasNext()){
    String obj = iterator.next();
}

Another way to iterate a List is to use the for loop added in Java 5 (also called a "for each" loop). Here is an example of iterating a List using the for loop:

List list = new ArrayList();

//add elements to list

for(Object obj : list) {
    
}

The for loop is executed once per element in the List. Inside the for loop each element is in turn bound to the obj variable.

If the list is typed (a generic List) you can change the type of the variable inside the for loop. Here is typed List iteration example:

List<String> list = new ArrayList<String>();

//add elements to list

for(String obj : list) {
    
}

Notice how the List is typed to String. Therefore you can set the type of the variable inside the for loop to String.

The last way to iterate a List is to use a standard for loop like this:

List list = new ArrayList();

//add elements to list

for(int i=0; i < list.size(); i++) {
    Object obj = list.get(i);
}

The for loop creates an int variable and initializes it to 0. Then it loops as long as the int variable i is less than the size of the list. For each iteration the variable i is incremented.

Inside the for loop the example accesses the elements in the List via its get() method, passing the incrementing variable i as parameter.

More Details in the JavaDoc

There is a lot more you can do with a List, but you will have to check out the JavaDoc for more details. This text focused on the two most common operations: Adding / removing elements, and iterating the elements.

Jakob Jenkov




Copyright  Jenkov Aps
Close TOC