47. Prefer using Iterators over Enumerations

According to the Java API, Interface Enumeration<E> documentation [API 2011],

An object that implements the Enumeration interface generates a series of elements, one at a time. Successive calls to the nextElement method return successive elements of the series.

As an example, the following code uses an Enumeration to display the contents of a Vector:

for (Enumeration e = vector.elements(); e.hasMoreElements();) {
  System.out.println(e.nextElement());
}

Unfortunately, Collections and an Enumerations may fail to work well together. In fact, the Java API [API 2011] recommends, "New implementations should consider using Iterator in preference to Enumeration." Consequently, iterators rather than enumerators should be preferred when examining iterable collections.

Noncompliant Code Example

This noncompliant code example implements a BankOperations class with a removeAccounts() method used to terminate all the accounts of a particular account holder, as identified by the name. Names can be repeated in the vector if a person has more than one account. The remove() method attempts to iterate through all the vector entries comparing each entry with the name "Harry."

class BankOperations {
  private static void removeAccount(Vector<String> v, String name) {
    Enumeration e = v.elements();
          
    while (e.hasMoreElements()) {
      String s = (String) e.nextElement();
      if (s.equals(name)) {
        v.remove(name); // Second Harry is not removed
      }
    }
  }
      
  public static void main(String args[]) { 
    // List contains a sorted array of account holder names
    // Repeats are admissible 
    List<String> list = new ArrayList<String>( Arrays.asList(
      new String[] {"Dick", "Harry", "Harry", "Tom"}));
    Vector<String> v = new Vector<String>(list);
    removeAccount(v, "Harry"); 
    // Display current account holders
    System.out.println("The names are:");
    Enumeration e = v.elements();
    while (e.hasMoreElements()) {
      System.out.println(e.nextElement());  // Prints Dick, Harry, Tom    
    }
  }
}

Upon encountering the first "Harry," it successfully removes the entry, and the size of the vector diminishes to three. However, the index of the Enumeration remains unchanged, causing the program to perform the next (now final) comparison with "Tom". Consequently, the second "Harry" remains in the vector unscathed, having shifted to the second position in the vector.

Compliant Solution

According to the Java API, Interface Iterator<E> documentation [API 2011],

Iterator takes the place of Enumeration in the Java collections framework. Iterators differ from enumerations in two ways:

• Iterators allow the caller to remove elements from the underlying collection during the iteration with well-defined semantics.
• Method names have been improved.

This compliant solution remedies the problem described in the noncompliant code example and demonstrates the advantages of using an Iterator over an Enumeration. It also uses Java's for-each syntax to iterate over the Vector implicitly. This is a more concise way of iterating over any collection, but is not useful when the iterator must be accessed directly (such as when removing an element).

class BankOperations {
  private static void removeAccount(Vector<String> v, String name) {
    Iterator i = v.iterator();
      
    while (i.hasNext()) {
      String s = (String) i.next();
      if (s.equals(name)) {
        i.remove(); // Correctly removes all instances of the name Harry
      }
    }
  }
      
  public static void main(String args[]) { 
    // List contains a sorted array of account holder names
    // Repeats are admissible 
    List<String> list = new ArrayList<String>( Arrays.asList(
      new String[] {"Dick", "Harry", "Harry", "Tom"}));
    Vector<String> v = new Vector<String>(list);
    removeAccount(v, "Harry"); 
    // Display current account holders
    System.out.println("The names are:");
    for (String s: v) {
      System.out.println(s); // Prints Dick, Tom only     
    }
  }
}

Applicability

Using Enumeration when performing remove operations on an iterable Collection may cause unexpected program behavior.

Bibliography