Methods that return interfaces

[Tim Oister]

I hope that this isn't an Intermediate-level question, but I was working with a LinkedList, specifically the listIterator() method which returns a ListIterator object.
When I check the API docs, I find that the ListIterator is an interface which inherits from the Iterator interface.
Where is the class used to create the ListIterator object returned from the listIterator() method? Or in other words, when you use any of the methods of the ListIterator interface, what class holds the implementations for those methods, if any?
In the hierarchy, it ends at the ListIterator interface. I'm sure that this isn't a single instance of this occurrence, so I guess I'm questioning any case where this happens.
Thanks in advance!

[Ernest Friedman-Hill]

Hi Tim,
Only the individual implementation of listIterator() knows the answer to your question. Each implementation of listIterator() returns a different implementation of this interface, specifically written to iterate over a given kind of list (obviously, the most efficient way to write a ListIterator for an ArrayList, based on an array, is going to be different than how you'd write one for a LinkedList!)
Many iterators are implemented as inner classes of the Collection class that defines them; this gives the iterator class access to the Collection's private data, so that the Iterator can be written more cleanly.

[Layne Lund]

As mentioned, the class may be implemented as an inner class, which is most likely also private. This would explain why it doesn't appear in the API docs, which only document public and protected members.
Typically, it doesn't really matter what the exact implementation is, just as long as it obeys the contract of the specified interface.

[Wayne L Johnson]

Sun does a great service in providing source code for most of the base Java classes, which means you can look directly into the code to see what's going in. In this specific case, the source for "java.util.LinkedList" includes the following, and I hope I'm not violating some license agreement by posting this here ;-)

public ListIterator listIterator(int index) {
   return new ListItr(index);
}
private class ListItr implements ListIterator {
   private Entry lastReturned = header;
   private Entry next;
   private int nextIndex;
   private int expectedModCount = modCount;
   ListItr(int index) {
      if (index < 0 || index > size)
         throw new IndexOutOfBoundsException("Index: "+index+
                                             ", Size: "+size);
      if (index < (size >> 1)) {
         next = header.next;
         for (nextIndex=0; nextIndex<index; nextIndex++)
            next = next.next;
      } else {
         next = header;
         for (nextIndex=size; nextIndex>index; nextIndex--)
            next = next.previous;
      }
   }
   public boolean hasNext() {
      return nextIndex != size;
   }
      . . .  // other methods
}

The class ListIter is in nested (inner) class that implements all of the behavior of a "ListIterator". It is private so you can't willy-nilly create one, but when you call the "listIterator(index)" method a "ListIter" is instantiated and returned to you. Since its methods are public you can call them.
Ernest has explained the advantages of doing it this way. It's a nice model to understand.

[Tim Oister]

Thanks to all for the answers to this question, and big thanks to Wayne for the code snippet. As soon as I saw the mention of inner classes, the light came on. Makes perfect sense now!
Thanks again!