Iterators - Data Structures and Abstractions with Java - page 388

/** Replaces the last entry in the list that either next()
or previous() has returned.
Precondition: next() or previous() has been called, but the
iterator's remove() or add() method has not been called
since then.
@param newEntry an object that is the replacement entry
@throws ClassCastException if the class of newEntry prevents the
addition to the list
@throws IllegalArgumentException if some other aspect of newEntry
prevents the addition to the list
@throws IllegalStateException if next() or previous() has not
been called, or if remove() or add() has been called
already after the last call to next() or previous()
@throws UnsupportedOperationException if the iterator does not
permit a set operation */
public void set(T newEntry); // Optional method
} // end ListIterator

15.33

Observations. Notice that ListIterator extends Iterator . Thus, ListIterator would include
the methods hasNext , next , and remove from the interface Iterator , even if we did not write them
explicitly. We have done so for your reference and to indicate remove 's additional behavior.
The methods remove , add , and set are optional in the sense that you can choose not to provide one
or more of these operations. In that case, however, each such operation must have an implementation
that throws the exception UnsupportedOperationException if the client invokes the operation. An
iterator of type ListIterator that does not support remove , add , and set is still useful, since it enables
you to traverse a list in both directions. It is also easier to implement without these operations.
The programming tip given in Segment 15.4 for the interface Iterator applies here as well.
We repeat it here in terms of ListInterface .

Programming Tip: All of the exceptions mentioned in the interface ListIterator are
run-time exceptions, so no throws clause is necessary in any of the methods' headers. In
addition, you do not have to write try and catch blocks when you invoke these methods.
However, you will need to import NoSuchElementException from the package java.util .
The other exceptions are in java.lang , so no import statement is necessary for them.

15.34

The next entry. Like Iterator , ListIterator positions an iterator either before the first entry in a list,
between two entries, or after the last entry. Recall that the method hasNext sees whether a next entry
exists after the iterator's position. If one exists, next returns a reference to it and advances the iterator's
cursor by one position, as Figure 15-1 illustrated. Repeated calls to next step through the list. So far,
nothing is different from what you learned about the interface Iterator earlier in this chapter.

15.35

The previous entry. ListIterator also provides access to the entry just before the iterator's
position—that is, to the previous entry. The method hasPrevious sees whether a previous
entry exists. If so, the method previous returns a reference to it and moves the iterator's cur-
sor back by one position. Figure 15-9 shows the effect of previous on a list. Intermixing calls
to previous and next enables you to move back and forth within the list. If you call next and
then call previous , each method returns the same entry. Like next , previous throws an excep-
tion when called after it has completed its traversal of the list.