Java Generics and Collections

{

9.4 Strategy | 131

public long computeTax(P p); } class DefaultTaxStrategy

implements TaxStrategy

{ private static final double RATE = 0.40; public long computeTax(P payer) { return Math.round(payer.getIncome() * RATE); } } class DodgingTaxStrategy

implements TaxStrategy

{ public long computeTax(P payer) { return 0; } } class TrustTaxStrategy extends DefaultTaxStrategy { public long computeTax(Trust trust) { return trust.isNonProfit() ? 0 : super.computeTax(trust); } }

may define a person with an income of $100,000.00 and two trusts with the same income, one nonprofit and one otherwise: Person person = new Person(10000000); Trust nonProfit = new Trust(10000000, true); Trust forProfit = new Trust(10000000, false);

In accordance with good practice, we represent all monetary values, such as incomes or taxes, by long integers standing for the value in cents (see the item “Avoid float and double if exact answers are required”, in the General Programming chapter of Effective Java by Joshua Bloch, Addison-Wesley). For each tax payer P there may be many possible strategies for computing tax. Each strategy implements the interface TaxStrategy

, which specifies a method compute Tax that takes as argument a tax payer of type P and returns the tax paid. Class Default TaxStrategy computes the tax by multiplying the income by a fixed tax rate of 40 percent, while class DodgingTaxStrategy always computes a tax of zero: TaxStrategy defaultStrategy = new TaxStrategy dodgingStrategy = new assert defaultStrategy.computeTax(person) assert dodgingStrategy.computeTax(person)

DefaultStrategy(); DodgingStrategy(); == 4000000; == 0;

Of course, our example is simplified for purposes of illustration—we do not recommend that you compute taxes using either of these strategies! But it should be clear how these techniques extend to more complex tax payers and tax strategies. Finally, class TrustTaxStrategy computes a tax of zero if the trust is nonprofit and uses the default tax strategy otherwise: TaxStrategy trustStrategy = new TrustTaxStrategy(); assert trustStrategy.computeTax(nonProfit) == 0; assert trustStrategy.computeTax(forProfit) == 4000000;

Generics allow us to specialize a given tax strategy to a given type of tax payer, and allow the compiler to detect when a tax strategy is applied to the wrong type of tax payer: 132 | Chapter 9: Design Patterns

trustStrategy.computeTax(person); // compile-time error

Without generics, the computeTax method of TrustTaxStrategy would have to accept an argument of type TaxPayer and cast it to type Trust, and errors would throw an exception at run time rather than be caught at compile time. This example illustrates a structuring technique found in many object-oriented programs—that of parallel class hierarchies. In this case, one class hierarchy consists of TaxPayer, Person, and Trust. A parallel class hierarchy consists of strategies corresponding to each of these: two strategies, DefaultTaxStrategy and DodgingTaxStrat egy apply to any TaxPayer, no specialized strategies apply to Person, and there is one specialized strategy for Trust. Usually, there is some connection between such parallel hierarchies. In this case, the computeTax method for a TaxStrategy that is parallel to a given TaxPayer expects an argument that is of the corresponding type; for instance, the computeTax method for TrustTaxStrategy expects an argument of type Trust. With generics, we can capture this connection neatly in the types themselves. In this case, the computeTax method for TaxStrategy

expects an argument of type P, where P must be subclass of TaxPayer. Using the techniques we have described here, generics can often be used to capture similar relations in other parallel class hierarchies. An Advanced Strategy Pattern with Recursive Generics In more advanced uses of the Strategy pattern, an object contains the strategy to be applied to it. Modelling this situation requires recursive generic types and exploits a trick to assign a generic type to this. The revised Strategy pattern is shown in Example 9-7. In the advanced version, each tax payer object contains its own tax strategy, and the constructor for each kind of tax payer includes a tax strategy as an additional argument: Person normal = Person dodger = Trust nonProfit Trust forProfit

new Person(10000000, new DefaultTaxStrategy()); new Person(10000000, new DodgingTaxStrategy()); = new Trust(10000000, true, new TrustTaxStrategy()); = new Trust(10000000, false, new TrustTaxStrategy());

Now we may invoke a computeTax method of no arguments directly on the tax payer, which will in turn invoke the computeTax method of the tax strategy, passing it the tax payer: assert assert assert assert

normal.computeTax() == dodger.computeTax() == nonProfit.computeTax() forProfit.computeTax()

4000000; 0; == 0; == 4000000;

This structure is often preferable, since one may associate a given tax strategy directly with a given tax payer. Before, we used a class TaxPayer and an interface TaxStrategy

, where the type variable P stands for the subclass of TaxPayer to which the strategy applies. Now we must add the type parameter P to both, in order that the class TaxPayer

can have a field 9.4 Strategy | 133

of type TaxStrategy

. The new declaration for the type variable P is necessarily recursive, as seen in the new header for the TaxPayer class: class TaxPayer

>

We have seen similar recursive headers before: interface Comparable> class Enum<E extends Enum<E>>

In all three cases, the class or interface is the base class of a type hierarchy, and the type parameter stands for a specific subclass of the base class. Thus, P in TaxPayer

stands for the specific kind of tax payer, such as Person or Trust; just as T in Comparable stands for the specific class being compared, such as String; or E in Enum<E> stands for the specific enumerated type, such as Season. The tax payer class contains a field for the tax strategy and a method that passes the tax payer to the tax strategy, as well as a recursive declaration for P just like the one used in TaxPayer. In outline, we might expect it to look like this: // not well-typed! class TaxPayer

> { private TaxStrategy

strategy; public long computeTax() { return strategy.computeTax(this); } ... } class Person extends TaxPayer { ... } class Trust extends TaxPayer { ... }

But the compiler rejects the above with a type error. The problem is that this has type TaxPayer

, whereas the argument to computeTax must have type P. Indeed, within each specific tax payer class, such as Person or Trust, it is the case that this does have type P; for example, Person extends TaxPayer, so P is the same as Person within this class. So, in fact, this will have the same type as P, but the type system does not know that! We can fix this problem with a trick. In the base class TaxPayer

we define an abstract method getThis that is intended to return the same value as this but gives it the type P. The method is instantiated in each class that corresponds to a specific kind of tax payer, such as Person or Trust, where the type of this is indeed the same as the type P. In outline, the corrected code now looks like this: // now correctly typed abstract class TaxPayer

> { private TaxStrategy

strategy; protected abstract P getThis(); public long computeTax() { return strategy.computeTax(getThis()); } ... } final class Person extends TaxPayer { protected Person getThis() { return this; } ... }

134 | Chapter 9: Design Patterns

final class Trust extends TaxPayer { protected Trust getThis() { return this; } ... }

The differences from the previous code are in bold. Occurences of this are replaced by calls to getThis; the method getThis is declared abstract in the base class and it is instantiated appropriately in each final subclass of the base class. The base class Tax Payer

must be declared abstract because it declares the type for getThis but doesn’t declare the body. The body for getThis is declared in the final subclasses Person and Trust. Since Trust is declared final, it cannot have subclasses. Say we wanted a subclass NonProfitTrust of Trust. Then not only would we have to remove the final declaration on the class Trust, we would also need to add a type parameter to it. Here is a sketch of the required code: abstract class Trust> extends TaxPayer { ... } final class NonProfitTrust extends Trust { ... } final class ForProfitTrust extends Trust { ... }

Example 9-7. An advanced Strategy pattern with recursive bounds abstract class TaxPayer

> { public long income; // in cents private TaxStrategy

strategy; public TaxPayer(long income, TaxStrategy

strategy) { this.income = income; this.strategy = strategy; } protected abstract P getThis(); public long getIncome() { return income; } public long computeTax() { return strategy.computeTax(getThis()); } } class Person extends TaxPayer { public Person(long income, TaxStrategy strategy) { super(income, strategy); } protected Person getThis() { return this; } } class Trust extends TaxPayer { private boolean nonProfit; public Trust(long income, boolean nonProfit, TaxStrategy strategy){ super(income, strategy); this.nonProfit = nonProfit; } protected Trust getThis() { return this; } public boolean isNonProfit() { return nonProfit; } } interface TaxStrategy

> { public long computeTax(P p); } class DefaultTaxStrategy

> implements TaxStrategy

{ private static final double RATE = 0.40; public long computeTax(P payer) {

9.4 Strategy | 135

}

return Math.round(payer.getIncome() * RATE);

} class DodgingTaxStrategy

> implements TaxStrategy

{ public long computeTax(P payer) { return 0; } } class TrustTaxStrategy extends DefaultTaxStrategy { public long computeTax(Trust trust) { return trust.isNonprofit() ? 0 : super.computeTax(trust); } }

Now an instance of NonProfitTrust takes a strategy that expects a NonProfitTrust as an argument, and ForProfitTrust behaves similarly. It is often convenient to set up a parameterized type hierarchy in this way, where classes with subclasses take a type parameter and are abstract and classes without subclasses do not take a type parameter and are final. A body for the getThis method is declared in each final subclass. Summary As we have seen, recursive type parameters often appear in Java: class TaxPayer

> Comparable> class Enum<E extends Enum<E>>

The getThis trick is useful in this situation whenever one wants to use this in the base type with the more specific type provided by the type parameter. We will see another example of recursive type parameters in the next section, applied to two mutually recursive classes. However, although the getThis trick is often useful, we will not require it there.

9.5 Subject-Observer We finish with a more extended example, illustrating the generic Subject-Observer pattern. Like the Strategy pattern, the Subject-Observer pattern uses parallel class hierarchies, but this time we require two type variables with mutually recursive bounds, one to stand for the specific kind of subject and one to stand for the specific kind of observer. This is our first example of type variables with mutually recursive bounds. The Java library implements a nongeneric version of the Subject-Observer pattern in the package java.util with the class Observable and the interface Observer (the former corresponding to the subject), signatures for which are shown in Example 9-8. The Observable class contains methods to register observers (addObserver), to indicate that the observable has changed (setChanged), and to notify all observers of any changes (notifyObservers), among others. The notifyObservers method may accept an arbitrary argument of type Object that is to be broadcast to all the observers. The Observer interface specifies the update method that is called by notifyObservers. This method takes two parameters: the first, of type Observable, is the subject that has changed; the second, of type Object, is the broadcast argument. 136 | Chapter 9: Design Patterns

The appearance of Object in a method signature often indicates an opportunity to generify. So we should expect to generify the classes by adding a type parameter, A, corresponding to the argument type. Further, we can replace Observable and Observer themselves with the type parameters S and O (for Subject and Observer). Then within the update method of the observer, you may call on any method supported by the subject S without first requiring a cast. Example 9-9 shows how to specify corresponding generic signatures for the Observa ble class and the Observer interface. Here are the relevant headers: public class Observable<S extends Observable<S,O,A>, O extends Observer<S,O,A>, A> public interface Observer<S extends Observable<S,O,A>, O extends Observer<S,O,A>, A>

Both declarations take the same three type parameters. The declarations are interesting in that they illustrate that the scope of type parameters can be mutually recursive: all three type parameters appear in the bounds of the first two. Previously, we saw other examples of simple recursion—for instance, in the declarations of Comparable and Enum, and in the previous section on the Strategy pattern. But this is the first time we have seen mutual recursion. Examining the bodies of the declarations, you can see that O but not S appears in the body of the Observable class and that S but not O appears in the body of the Observer interface. So you might wonder: could the declarations be simplified by dropping the type parameter S from Observable and the type parameter O from Observer? But this won’t work, since you need S to be in scope in Observable so that it can be passed as a parameter to Observer, and you needs O to be in scope in Observer so that it can be passed as a parameter to Observable. The generic declarations use stubs, as explained in Section 5.4.2. We compile the client against the generic signatures of Observable and Observer, but run the code against the class files in the standard Java distribution. We use stubs because we don’t want to make any changes to the source of the library, since it is maintained by Sun. Example 9-8. Observable and Observer before generics package java.util; public class Observable { public void addObserver(Observer o) {...} protected void clearChanged() {...} public int countObservers() {...} public void deleteObserver(Observer o) {...} public boolean hasChanged() {...} public void notifyObservers() {...} public void notifyObservers(Object arg) {...} protected void setChanged() {...} }

9.5 Subject-Observer | 137

package java.util; public interface Observer { public void update(Observable o, Object arg); }

Example 9-9. Observable and Observer with generics package java.util; class StubException extends UnsupportedOperationException {} public class Observable<S extends Observable<S,O,A>, O extends Observer<S,O,A>, A> { public void addObserver(O o) { throw new StubException(); protected void clearChanged() { throw new StubException(); public int countObservers() { throw new StubException(); public void deleteObserver(O o) { throw new StubException(); public boolean hasChanged() { throw new StubException(); public void notifyObservers() { throw new StubException(); public void notifyObservers(A a) { throw new StubException(); protected void setChanged() { throw new StubException(); }

} } } } } } } }

package java.util; public interface Observer<S extends Observable<S,O,A>, O extends Observer<S,O,A>, A> { public void update(S o, A a); }

As a demonstration client for Observable and Observer, a currency converter is presented in Example 9-10. A screenshot of the converter is shown in Figure 9-1. The converter allows you to enter conversion rates for each of three currencies (dollars, euros, and pounds), and to enter a value under any currency. Changing the entry for a rate causes the corresponding value to be recomputed; changing the entry for a value causes all the values to be recomputed. The client instantiates the pattern by declaring CModel to be a subclass of Observable, and CView to be a subinterface of Observer. Furthermore, the argument type is instantiated to Currency, an enumerated type, which can be used to inform an observer which components of the subject have changed. Here are the relevant headers: enum Currency { DOLLAR, EURO, POUND } class CModel extends Observable interface CView extends Observer

The classes RateView and ValueView implement CView, and the class Converter defines the top-level frame which controls the display. The CModel class has a method to set and get the rate and value for a given currency. Rates are stored in a map that assigns a rate to each currency, and the value is stored (as a long,

138 | Chapter 9: Design Patterns

Figure 9-1. Currency converter

in cents, euro cents, or pence) together with its actual currency. To compute the value for a given currency, the value is divided by the rate for its actual currency and multiplied by the rate for the given currency. The CModel class invokes the update method of RateView whenever a rate is changed, passing the corresponding currency as the argument (because only the rate and value for that currency need to be updated); and it invokes the update method of ValueView whenever a value is changed, passing null as the argument (because the values for all currencies need to be updated). We compile and run the code as follows. First, we compile the generic versions of Observable and Observer: % javac -d . java/util/Observable.java java/util/Observer.java

Since these are in the package java.util, they must be kept in the subdirectory java/ util of the current directory. Second, we compile Converter and related classes in package com.eg.converter. By default, the Java compiler first searches the current directory for class files (even for the standard library). So the compiler uses the stub class files generated for Observable and Observer, which have the correct generic signature (but no runnable code): % javac -d . com/eg/converter/Converter.java

Third, we run the class file for the converter. By default, the java runtime does not first search the current directory for class files in the packages java and javax—for reasons of security, these are always taken from the standard library. So the runtime uses the standard class files for Observable and Observer, which contain the legacy code we want to run (but do not have the correct generic signature): % java com.eg.converter.Converter

Example 9-10. Currency converter import java.util.*; import javax.swing.*;

9.5 Subject-Observer | 139

import javax.swing.event.*; import java.awt.*; import java.awt.event.*; enum Currency { DOLLAR, EURO, POUND } class CModel extends Observable { private final EnumMap rates; private long value = 0; // cents, euro cents, or pence private Currency currency = Currency.DOLLAR; public CModel() { rates = new EnumMap(Currency.class); } public void initialize(double... initialRates) { for (int i=0; i {} class RateView extends JTextField implements CView { private final CModel model; private final Currency currency; public RateView(final CModel model, final Currency currency) { this.model = model; this.currency = currency; addActionListener(new ActionListener() { public void actionPerformed(ActionEvent e) { try { double rate = Double.parseDouble(getText()); model.setRate(currency, rate); } catch (NumberFormatException x) {} } });

140 | Chapter 9: Design Patterns

}

}

model.addObserver(this);

public void update(CModel model, Currency currency) { if (this.currency == currency) { double rate = model.getRate(currency); setText(String.format("%10.6f", rate)); } }

class ValueView extends JTextField implements CView { private final CModel model; private final Currency currency; public ValueView(final CModel model, final Currency currency) { this.model = model; this.currency = currency; addActionListener(new ActionListener() { public void actionPerformed(ActionEvent e) { try { long value = Math.round(100.0*Double.parseDouble(getText())); model.setValue(currency, value); } catch (NumberFormatException x) {} } }); model.addObserver(this); }

}

public void update(CModel model, Currency currency) { if (currency == null || currency == this.currency) { long value = model.getValue(this.currency); setText(String.format("%15d.%02d", value/100, value%100)); } }

class Converter extends JFrame { public Converter() { CModel model = new CModel(); setTitle("Currency converter"); setLayout(new GridLayout(Currency.values().length+1, 3)); add(new JLabel("currency")); add(new JLabel("rate")); add(new JLabel("value")); for (Currency currency : Currency.values()) { add(new JLabel(currency.name())); add(new RateView(model, currency)); add(new ValueView(model, currency)); } model.initialize(1.0, 0.83, 0.56); setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); pack(); } public static void main(String[] args) {

9.5 Subject-Observer | 141

}

}

new Converter().setVisible(true);

So when we use stubs for standard library classes, we do not need to alter the classpath, as we did in Section 5.4.2, because the correct behavior is obtained by default. (If you do want to alter the standard library classes at runtime, you can use the -Xbootclass path flag.) This concludes our discussion of generics. You now have a thorough grounding that enables you to use generic libraries defined by others, to define your own libraries, to evolve legacy code to generic code, to understand restrictions on generics and avoid the pitfalls, to use checking and specialization where needed, and to exploit generics in design patterns. One of the most important uses of generics is the Collection Framework, and in the next part of this book we will show you how to effectively use this framework and improve your productivity as a Java programmer.

142 | Chapter 9: Design Patterns

PART II

Collections

The Java Collections Framework is a set of interfaces and classes in the packages java.util and java.util.concurrent. They provide client programs with various models of how to organize their objects, and various implementations of each model. These models are sometimes called abstract data types, and we need them because different programs need different ways of organizing their objects. In one situation, you might want to organize your program's objects in a sequential list because their ordering is important and there are duplicates. In another, a set might be the right data type because now ordering is unimportant and you want to discard the duplicates. These two data types (and others) are represented by different interfaces in the Collections Framework, and we will look at examples of their use in this chapter. But that's not all; none of these data types has a single "best" implementation—that is, one implementation that is better than all the others for all the operations. For example, a linked list may be better than an array implementation of lists for inserting and removing elements from the middle, but much worse for random access. So choosing the right implementation for your program involves knowing how it will be used as well as what is available. This part of the book starts with an overview of the Framework and then looks in detail at each of the main interfaces and the standard implementations of them. Finally we will look at the special-purpose implementation and generic algorithms provided in the Collections class.

CHAPTER 10

The Main Interfaces of the Java Collections Framework

Figure 10-1 shows the main interfaces of the Java Collections Framework, together with one other—Iterable—which is outside the Framework but is an essential adjunct to it. Its purpose is as follows: • Iterable defines the contract that a class has to fulfill for its instances to be usable with the foreach statement. And the Framework interfaces have the following purposes: • Collection contains the core functionality required of any collection other than a map. It has no direct concrete implementations; the concrete collection classes all implement one of its subinterfaces as well. • Set is a collection, without duplicates, in which order is not significant. Sorted Set automatically sorts its elements and returns them in order. NavigableSet extends this, adding methods to find the closest matches to a target element. • Queue is a collection designed to accept elements at its tail for processing, yielding them up at its head in the order in which they are to be processed. Its subinterface Deque extends this by allowing elements to be added or removed at both head and tail. Queue and Deque have subinterfaces, BlockingQueue and BlockingDeque respectively, that support concurrent access and allow threads to be blocked, indefinitely or for a maximum time, until the requested operation can be carried out. • List is a collection in which order is significant, accommodating duplicate elements. • Map is a collection which uses key-value associations to store and retrieve elements. It is extended by ConcurrentMap, which provides support for concurrent access, by SortedMap, which guarantees to return its values in ascending key order, by Navi gable-Map which extends SortedMap to find the closest matches to a target element, and by ConcurrentNavigableMap which extends ConcurrentMap and NavigableMap. 145

Iterable

Map

(java.lang)

SortedMap

Collection<E>

ConcurrentMap

NavigableMap Set<E>

List<E>

Queue<E>

SortedSet<E> NavigableSet<E>

(java.util.concurrent)

Deque<E>

ConcurrentNavigableMap (java.util.concurrent)

BlockingQueue<E> (java.util.concurrent)

BlockingDeque<E> (java.util.concurrent)

Figure 10-1. The main interfaces of the Java Collections Framework

Chapters 12 through 16 will concentrate on each of the Collections Framework interfaces in turn. First, though, in Chapter 11, we need to cover some preliminary ideas which run through the entire Framework design.

146 | Chapter 10: The Main Interfaces of the Java Collections Framework

CHAPTER 11

Preliminaries

In this chapter, we will take time to discuss the concepts underlying the framework, before we get into the detail of the collections themselves.

11.1 Iterable and Iterators An iterator is an object that implements the interface Iterator: public Iterator<E> { boolean hasNext(); E next(); void remove(); }

// return true if the iteration has more elements // return the next element in the iteration // remove the last element returned by the iterator

The purpose of iterators is to provide a uniform way of accessing collection elements sequentially, so whatever kind of collection you are dealing with, and however it is implemented, you always know how to process its elements in turn. This used to require some rather clumsy code; for example, in earlier versions of Java, you would write the following to print the string representation of a collection’s contents: // coll refers to an object which implements Collection // ----- not the preferred idiom from Java 5 on ------for (Iterator itr = coll.iterator() ; itr.hasNext() ; ) { System.out.println(itr.next()); }

The strange-looking for statement was the preferred idiom before Java 5 because, by restricting the scope of itr to the body of the loop, it eliminated accidental uses of it elsewhere. This code worked because any class implementing Collection has an iter ator method which returns an iterator appropriate to objects of that class. It is no longer the approved idiom because Java 5 introduced something better: the foreach statement, which you met in Part I. Using foreach, we can write the preceding code more concisely: for (Object o : coll) { System.out.println(o); }

147

This code will work with anything that implements the interface Iterable—that is, anything that can produce an Iterator. This is the declaration of Iterable: public Iterable { Iterator iterator(); }

// return an iterator over elements of type T

In Java 5 the Collection interface was made to extend Iterable, so any set, list, or queue can be the target of foreach, as can arrays. If you write your own implementation of Iterable, that too can be used with foreach. Example 11-1 shows a tiny example of how Iterable can be directly implemented. A Counter object is initialized with a count of Integer objects; its iterator returns these in ascending order in response to calls of next(). Now Counter objects can be the target of a foreach statement: int total = 0; for (int i : new Counter(3)) { total += i; } assert total == 6;

In practice, it is unusual to implement Iterable directly in this way, as foreach is most commonly used with arrays and the standard collections classes. The iterators of the general-purpose collections in the Framework—ArrayList, Hash Map, and so on—can puzzle novice users by throwing ConcurrentModificationExcep tion from single-threaded code. These iterators throw this exception whenever they detect that the collection from which they were derived has been structurally changed (broadly speaking, that elements have been added or removed). The motivation for this behavior is that the iterators are implemented as a view of their underlying collection so, if that collection is structurally changed, the iterator may well not be able to continue operating correctly when it reaches the changed part of the collection. Instead of allowing the manifestation of failure to be delayed, making diagnosis difficult, the general-purpose Collections Framework iterators are fail-fast. The methods of a fail-fast iterator check that the underlying collection has not been structurally changed (by another iterator, or by the methods of the collection itself) since the last iterator method call. If they detect a change, they throw ConcurrentModificationException. Although this restriction rules out some sound programs, it rules out many more unsound ones. Example 11-1. Directly implementing Iterable class Counter implements Iterable { private int count; public Counter(int count) { this.count = count; } public Iterator iterator() { return new Iterator() { private int i = 0; public boolean hasNext() { return i < count; } public Integer next() { i++; return i; } public void remove(){ throw new UnsupportedOperationException(); }

148 | Chapter 11: Preliminaries

}

}

};

The concurrent collections have other strategies for handling concurrent modification, such as weakly consistent iterators. We discuss them in more detail in Section 11.5.

11.2 Implementations We have looked briefly at the interfaces of the Collections Framework, which define the behavior that we can expect of each collection. But as we mentioned in the introduction to this chapter, there are several ways of implementing each of these interfaces. Why doesn’t the Framework just use the best implementation for each interface? That would certainly make life simpler—too simple, in fact, to be anything like life really is. If an implementation is a greyhound for some operations, Murphy’s Law tells us that it will be a tortoise for others. Because there is no “best” implementation of any of the interfaces, you have to make a tradeoff, judging which operations are used most frequently in your application and choosing the implementation that optimizes those operations. The three main kinds of operations that most collection interfaces require are insertion and removal of elements by position, retrieval of elements by content, and iteration over the collection elements. The implementations provide many variations on these operations, but the main differences among them can be discussed in terms of how they carry out these three. In this section, we’ll briefly survey the four main structures used as the basis of the implementations and later, as we need them, we will look at each in more detail. The four structures are: Arrays These are the structures familiar from the Java language—and just about every other programming language since Fortran. Because arrays are implemented directly in hardware, they have the properties of random-access memory: very fast for accessing elements by position and for iterating over them, but slower for inserting and removing elements at arbitrary positions (because that may require adjusting the position of other elements). Arrays are used in the Collections Framework as the backing structure for ArrayList, CopyOnWriteArrayList, EnumSet and EnumMap, and for many of the Queue and Deque implementations. They also form an important part of the mechanism for implementing hash tables (discussed shortly). Linked lists As the name implies, these consist of chains of linked cells. Each cell contains a reference to data and a reference to the next cell in the list (and, in some implementations, the previous cell). Linked lists perform quite differently from arrays: accessing elements by position is slow, because you have to follow the reference chain from the start of the list, but insertion and removal operations can be performed in constant time by rearranging the cell references. Linked lists are the 11.2 Implementations | 149

primary backing structure used for the classes ConcurrentLinkedQueue, LinkedBlock ingQueue, and LinkedList, and the new skip list collections ConcurrentSkipList Set and ConcurrentSkipListMap. They are also used in implementing HashSet and LinkedHashSet. Hash tables These provide a way of storing elements indexed on their content rather than on an integer-valued index, as with lists. In contrast to arrays and linked lists, hash tables provide no support for accessing elements by position, but access by content is usally very fast, as are insertion and removal. Hash tables are the backing structure for many Set and Map implementations, including HashSet and LinkedHash Set together with the corresponding maps HashMap and LinkedHashMap, as well as WeakHashMap, IdentityHashMap and ConcurrentHashMap. Trees These also organize their elements by content, but with the important difference that they can store and retrieve them in sorted order. They are relatively fast for the operations of inserting and removing elements, accessing them by content and iterating over them. Trees are the backing structures for TreeSet and TreeMap. Priority heaps, used in the implementation of PriorityQueue and PriorityBlocking Queue, are treerelated structures.

11.3 Efficiency and the O-Notation In the last section, we talked about different implementations being “good” for different operations. A good algorithm is economical in its use of two resources: time and space. Implementations of collections usually use space proportional to the size of the collection, but they can vary greatly in the time required for access and update, so that will be our primary concern. It’s very hard to say precisely how quickly a program will execute, as that depends on many factors, including some that are outside the province of the programmer, such as the quality of the compiled code and the speed of the hardware. Even if we ignore these and limit ourselves to thinking only about how the execution time for an algorithm depends on its data, detailed analysis can be complex. A relatively simple example is provided in Donald Knuth’s classic book Sorting and Searching (Addison-Wesley), where the worst-case execution time for a multiple list insertion sort program on Knuth’s notional MIX machine is derived as 3.5N2 + 24.5N + 4M + 2 where N is the number of elements being sorted and M is the number of lists. As a shorthand way of describing algorithm efficiency, this isn’t very convenient. Clearly we need a broader brush for general use. The one most commonly used is the Onotation (pronounced "big-oh notation”). The O-notation is a way of describing the performance of an algorithm in an abstract way, without the detail required to predict the precise performance of a particular program running on a particular machine. Our

150 | Chapter 11: Preliminaries

main reason for using it is that it gives us a way of describing how the execution time for an algorithm depends on the size of its data set, provided the data set is large enough. For example, in the previous expression the first two terms are comparable for low values of N; in fact, for N < 8, the second term is larger. But as N grows, the first term increasingly dominates the expression and, by the time it reaches 100, the first term is 15 times as large as the second one. Using a very broad brush, we say that the worst case for this algorithm takes time O(N2). We don’t care too much about the coefficient because that doesn’t make any difference to the single most important question we want to ask about any algorithm: what happens to the running time when the data size increases—say, when it doubles? For the worst-case insertion sort, the answer is that the running time goes up fourfold. That makes O(N2) pretty bad—worse than any we will meet in practical use in this book. Table 11-1. Some common running times Time

Common name

Effect on the running time if N is doubled

Example algorithms

O(1)

Constant

Unchanged

Insertion into a hash table (Section 13.1)

O(log N)

Logarithmic

Increased by a constant amount

Insertion into a tree (Section 13.2.2)

O(N)

Linear

Doubled

Linear search

Doubled plus an amount proportional to N

Merge sort (Section 17.1.1)

Increased fourfold

Bubble sort

O(N log N) O(N2)

Quadratic

Table 11-1 shows some commonly found running times, together with examples of algorithms to which they apply. For example, many other running times are possible, including some that are much worse than those in the Figure. Many important problems can be solved only by algorithms that take O(2N)—for these, when N doubles, the running time is squared! For all but the smallest data sets, such algorithms are infeasibly slow. Sometimes we have to think about situations in which the cost of an operation varies with the state of the data structure. For example, adding an element to the end of an ArrayList can normally be done in constant time, unless the ArrayList has reached its capacity. In that case, a new and larger array must be allocated, and the contents of the old array transferred into it. The cost of this operation is linear in the number of elements in the array, but it happens relatively rarely. In situations like this, we calculate the amortized cost of the operation—that is, the total cost of performing it n times divided by n, taken to the limit as n becomes arbitrarily large. In the case of adding an element to an ArrayList, the total cost for N elements is O(N), so the amortized cost is O(1).

11.3 Efficiency and the O-Notation | 151

11.4 Contracts In reading about software design, you are likely to come across the term contract, often without any accompanying explanation. In fact, software engineering gives this term a meaning that is very close to what people usually understand a contract to be. In everyday usage, a contract defines what two parties can expect of each other—their obligations to each other in some transaction. If a contract specifies the service that a supplier is offering to a client, the supplier’s obligations are obvious. But the client, too, may have obligations—besides the obligation to pay—and failing to meet them will automatically release the supplier from her obligations as well. For example, airlines’ conditions of carriage—for the class of tickets that we can afford, anyway—release them from the obligation to carry passengers who have failed to turn up on time. This allows the airlines to plan their service on the assumption that all the passengers they are carrying are punctual; they do not have to incur extra work to accommodate clients who have not fulfilled their side of the contract. Contracts work just the same way in software. If the contract for a method states preconditions on its arguments (i.e., the obligations that a client must fulfill), the method is required to return its contracted results only when those preconditions are fulfilled. For example, binary search (see Section 17.1.4) is a fast algorithm to find a key within an ordered list, and it fails if you apply it to an unordered list. So the contract for Collections.binarySearch can say, “if the list is unsorted, the results are undefined”, and the implementer of binary search is free to write code which, given an unordered list, returns random results, throws an exception, or even enters an infinite loop. In practice, this situation is relatively rare in the contracts of the core API because, instead of restricting input validity, they mostly allow for error states in the preconditions and specify the exceptions that the method must throw if it gets bad input. This design may be appropriate for general libraries such as the Collections Framework, which will be very heavily used in widely varying situations and by programmers of widely varying ability. You should probably avoid it for less-general libraries, because it restricts the flexibility of the supplier unnecessarily. In principle, all that a client should need to know is how to keep to its side of the contract; if it fails to do that, all bets are off and there should be no need to say exactly what the supplier will do. It’s good practice in Java to code to an interface rather than to a particular implementation, so as to provide maximum flexibility in choosing implementations. For that to work, what does it imply about the behavior of implementations? If your client code uses methods of the List interface, for example, and at run time the object doing the work is actually an ArrayList, you need to know that the assumptions you have made about how Lists behave are true for ArrayLists also. So a class implementing an interface has to fulfill all the obligations laid down by the terms of the interface contract. Of course, a weaker form of these obligations is already imposed by the compiler; a class claiming to implement an interface must provide concrete method definitions

152 | Chapter 11: Preliminaries

matching the declarations in the interface. Contracts take this further by specifying the behavior of these methods as well. The Collections Framework separates interface and implementation obligations in an unusual way. Some API methods return collections with restricted functionality—for example, the set of keys that you can obtain from a Map can have elements removed but not added (see Chapter 16). Others can have elements neither added nor removed (e.g., the list view returned by Arrays.asList), or may be completely read-only, for example collections that have been wrapped in an unmodifiable wrapper (see Section 17.3.2). To accommodate this variety of behaviors in the Framework without an explosion in the number of interfaces, the designers labeled the modification methods in the Col lection interface (and in the Iterator and ListIterator interfaces) as optional operations. If a client tries to modify a collection using an optional operation that the collection does not implement, the method must throw UnsupportedOperationException. The advantage to this approach is that the structure of the Framework interfaces is very simple, a great virtue in a library that every Java programmer must learn. The drawback is that a client programmer can no longer rely on the contract for the interface, but has to know which implementation is being used and to consult the contract for that as well. That’s so serious that you will probably never be justified in subverting interfaces in this way in your own designs. The contract for a class spells out what a client can rely on in using it, often including performance guarantees. To fully understand the performance characteristics of a class, however, you may need to know some detail about the algorithms it uses. In this part of the book, while we concentrate mainly on contracts and how, as a client programmer, you can make use of them, we also give some further implementation detail from the platform classes where it might be of interest. This can be useful in deciding between implementations, but remember that it is not stable; while contracts are binding, one of the main advantages of using them is that they allow implementations to change as better algorithms are discovered or as hardware improvements change their relative merits. And of course, if you are using another implementation, such as GNU Classpath, algorithm details not governed by the contract may be entirely different.

11.5 Collections and Thread Safety When a Java program is running, it is executing one or more execution streams, or threads. A thread is like a lightweight process, so a program simultaneously executing several threads can be thought of as a computer running several programs simultaneously, but with one important difference: different threads can simultaneously access the same memory locations and other system resources. On machines with multiple processors, truly concurrent thread execution can be achieved by assigning a processor to each thread. If, however, there are more threads than processors—the usual case— multithreading is implemented by time slicing, in which a processor executes some instructions from each thread in turn before switching to the next one.

11.5 Collections and Thread Safety | 153

There are two good reasons for using multithread programming. An obvious one, in the case of multicore and multiprocessor machines, is to share the work and get it done quicker. (This reason is becoming ever more compelling as hardware designers turn increasingly to parallelism as the way of improving overall performance.) A second one is that two operations may take varying, perhaps unknown, amounts of time, and you do not want the response to one operation to await the completion of the other. This is particularly true for a graphical user interface (GUI), where the response to the user clicking a button should be immediate, and should not be delayed if, say, the program happens to be running compute-intensive part of the application at the time. Although concurrency may be essential to achieving good performance, it comes at a price. Different threads simultaneously accessing the same memory location can produce unexpected results, unless you take care to constrain their access. Consider Example 11-2, in which the class ArrayStack uses an array and an index to implement the interface Stack, which models a stack of int (despite the similarity of names, this example is different from Example 5-1). For ArrayStack to work correctly, the variable index should always point at the top element of the stack, no matter how many elements are added to or removed from the stack. This is an invariant of the class. Now think about what can happen if two threads simultaneously attempt to push an element on to the stack. As part of the push method, each will execute the lines //1 and //2, which are correct in a single-threaded environment but in a multi-threaded environment may break the invariant. For example, if thread A executes line //1, thread B executes line //1 and then line //2, and finally thread A executes line //2, only the value added by thread B will now be on the stack, and it will have overwritten the value added by thread A. The stack pointer, though, will have been incremented by two, so the value in the top position of the stack is whatever happened to be there before. This is called a race condition, and it will leave the program in an inconsistent state, likely to fail because other parts of it will depend on the invariant being true. Example 11-2. A non-thread-safe stack implementation interface Stack { public void push(int elt); public int pop(); public boolean isEmpty(); } class ArrayStack implements Stack{ private final int MAX_ELEMENTS = 10; private int[] stack; private int index; public ArrayStack() { stack = new int[MAX_ELEMENTS]; index = -1; } public void push(int elt) { if (index != stack.length - 1) { index++;

154 | Chapter 11: Preliminaries

//1

stack[index] = elt; //2 } else { throw new IllegalStateException("stack overflow"); }

}

} public int pop() { if (index != -1) { return stack[index]; index--; } else { throw new IllegalStateException("stack underflow"); } } public boolean isEmpty() { return index == -1; }

The increasing importance of concurrent programming during the lifetime of Java has led to a corresponding emphasis in the collections library on flexible and efficient concurrency policies. As a user of the Java collections, you need a basic understanding of the concurrency policies of the different collections in order to know how to choose between them and how to use them appropriately. In this section, we’ll briefly outline the different ways in which the Framework collections handle concurrency, and the implications for the programmer. For a full treatment of the general theory of concurrent programming, see Concurrent Programming in Java by Doug Lea (Addison-Wesley), and for detail about concurrency in Java, and the collections implementations, see Java Concurrency in Practice by Brian Goetz et. al. (Addison-Wesley).

11.5.1. Synchronization and the Legacy Collections Code like that in ArrayStack is not thread-safe—itworks when executed by a single thread, but may break in a multi-threaded environment. Since the incorrect behavior we observed involved two threads simultaneously executing the push method, we could change the program to make that impossible. Using synchronized to modify the declaration of the push method will guarantee that once a thread has started to execute it, all other threads are excluded from that method until the execution is done: public synchronized void push(int elt) { ... }

This is called synchronizing on a critical section of code, in this case the whole of the push method. Before a thread can execute synchronized code, it has to get the lock on some object—by default, as in this case, the current object. While a lock is held by one thread, another thread that tries to enter any critical section synchronized on that lock will block—that is, will be suspended—until it can get the lock. This synchronized version of push is thread-safe; in a multi-threaded environment, each thread behaves consistently with its behavior in a single-threaded environment.To safeguard the invariant and make ArrayStack as a whole thread-safe, the methods pop and isEmpty must also be synchronized on the same object. The method isEmpty doesn’t write to shared data, so synchronizing it isn’t required to prevent a race condition, but for a different reason. Each thread may use a separate memory cache, which means that writes by one 11.5 Collections and Thread Safety | 155

thread may not be seen by another unless either they both take place within blocks synchronized on the same lock, or unless the variable is marked with the volatile keyword. Full method synchronization was, in fact, the policy of the collection classes provided in JDK1.0: Vector, Hashtable, and their subclasses; all methods that access their instance data are synchronized. These are now regarded as legacy classes to be avoided because of the high price this policy imposes on all clients of these classes, whether they require thread safety or not. Synchronization can be very expensive: forcing threads to queue up to enter the critical section one at a time slows down the overall execution of the program, and the overhead of administering locks can be very high if they are often contended.

11.5.2. JDK 1.2: Synchronized Collections and Fail-Fast Iterators The performance cost of internal synchronization in the JDK 1.0 collections led the designers to avoid it when the Collections Framework was first introduced in JDK 1.2. Instead, the platform implementations of the interfaces List, Set, and Map widened the programmer’s choice of concurrency policies. To provide maximum performance for single-threaded execution, the new collections provided no concurrency control at all. (More recently, the same policy change has been made for the synchronized class StringBuffer, which was complemented in Java 5 by its unsynchronized equivalent, StringBuilder.) Along with this change came a new concurrency policy for collection iterators. In multithreaded environments, a thread which has obtained an iterator will usually continue to use it while other threads modify the original collection. So iterator behavior has to be considered as an integral part of a collection's concurrency policy. The policy of the iterators for the Java 2 collections is to fail fast, as described in Section 11.1: every time they access the backing collection, they check it for structural modification (which, in general, means that elements have been added or removed from the collection). If they detect structural modification, they fail immediately, throwing ConcurrentModificatio nException rather than continuing to attempt to iterate over the modified collection with unpredictable results. Note that this fail-fast behavior is provided to help find and diagnose bugs; it is not guaranteed as part of the collection contract. The appearance of Java collections without compulsory synchronization was a welcome development. However, thread-safe collections were still required in many situations, so the Framework provided an option to use the new collections with the old concurrency policy, by means of synchronized wrappers (see Chapter 17). These are created by calling one of the factory methods in the Collections class, supplying an unsynchronized collection which it will encapsulate. For example, to make a synchronized List, you could supply an instance of ArrayList to be wrapped. The wrapper implements the interface by delegating method calls to the collection you supplied, but the calls are synchronized on the wrapper object itself. Example 11-3 shows a synchron-

156 | Chapter 11: Preliminaries

ized wrapper for the interface Stack of Example 11-2. To get a thread-safe Stack, you would write: Stack threadSafe = new SynchronizedArrayStack(new ArrayStack());

This is the preferred idiom for using synchronized wrappers; the only reference to the wrapped object is held by the wrapper, so all calls on the wrapped object will be synchronized on the same lock—that belonging to the wrapper object itself. It’s important to have the synchronized wrappers available, but you won’t use them more than you have to, because they suffer the same performance disadvantages as the legacy collections. Example 11-3. A synchronized wrapper for ArrayStack public class SynchronizedArrayStack implements Stack { private final Stack stack; public SynchronizedArrayStack(Stack stack) { this.stack = stack; } public synchronized void push(int elt) { stack.push(elt); } public synchronized int pop() { return stack.pop(); } public synchronized boolean isEmpty() { return stack.isEmpty(); } }

Using Synchronized Collections Safely Even a class like SynchronizedArrayStack, which has fully synchronized methods and is itself thread-safe, must still be used with care in a concurrent environment. For example, this client code is not thread-safe: Stack stack = new SynchronizedArrayStack(new ArrayStack()); ... // don't do this in a multi-threaded environment if (!stack.isEmpty()) { stack.pop(); // can throw IllegalStateException }

The exception would be raised if the last element on the stack were removed by another thread in the time between the evaluation of isEmpty and the execution of pop. This is an example of a common concurrent program bug, sometimes called test-then-act, in which program behavior is guided by information that in some circumstances will be out of date. To avoid it, the test and action must be executed atomically. For synchronized collections (as for the legacy collections), this must be enforced with client-side locking: synchronized(stack) { if (!stack.isEmpty()) { stack.pop(); } }

For this technique to work reliably, the lock that the client uses to guard the atomic action should be the same one that is used by the methods of the synchronized wrapper. In this example, as in the synchronized collections, the methods of the wrapper are 11.5 Collections and Thread Safety | 157

synchronized on the wrapper object itself. (An alternative is to confine references to the collection within a single client, which enforces its own synchronization discipline. But this strategy has limited applicability.) Client-side locking ensures thread-safety, but at a cost: since other threads cannot use any of the collection’s methods while the action is being performed, guarding a longlasting action (say, iterating over an entire array) will have an impact on throughput. This impact can be very large if the synchronized methods are heavily used; unless your application needs a feature of the synchronized collections, such as exclusive locking, the Java 5 concurrent collections are almost always a better option.

11.5.3. Concurrent Collections: Java 5 and Beyond Java 5 introduced thread-safe concurrent collections as part of a much larger set of concurrency utilities, including primitives—atomic variables and locks—which give the Java programmer access to relatively recent hardware innovations for managing concurrent threads, notably compare-and-swap operations, explained below. The concurrent collections remove the necessity for client-side locking as described in the previous section—in fact, external synchronization is not even possible with these collections, as there is no one object which when locked will block all methods. Where operations need to be atomic—for example, inserting an element into a Map only if it is currently absent—the concurrent collections provide a method specified to perform atomically—in this case, ConcurrentMap.putIfAbsent. If you need thread safety, the concurrent collections generally provide much better performance than synchronized collections. This is primarily because their throughput is not reduced by the need to serialize access, as is the case with the synchronized collections. Synchronized collections also suffer the overhead of managing locks, which can be high if there is much contention. These differences can lead to efficiency differences of two orders of magnitude for concurrent access by more than a few threads. Mechanisms The concurrent collections achieve thread-safety by several different mechanisms. The first of these—the only one that does not use the new primitives— is copy-on-write. Classes that use copy-on-write store their values in an internal array, which is effectively immutable; any change to the value of the collection results in a new array being created to represent the new values. Synchronization is used by these classes, though only briefly, during the creation of a new array; because read operations do not need to be synchronized, copy-on-write collections perform well in the situations for which they are designed—those in which reads greatly predominate over writes. Copy-on-write is used by the collection classes CopyOnWriteArrayList and CopyOnWri teArraySet. A second group of thread-safe collections relies on compare-and-swap (CAS), a fundamental improvement on traditional synchronization. To see howitworks, consider a computation in which the value of a single variable is used as input to a long-running calculation whose eventual result is used to update the variable. Traditional synchro-

158 | Chapter 11: Preliminaries

nization makes the whole computation atomic, excluding any other thread from concurrently accessing the variable. This reduces opportunities for parallel execution and hurts throughput. An algorithm based on CAS behaves differently: it makes a local copy of the variable and performs the calculation without getting exclusive access. Only when it is ready to update the variable does it call CAS, which in one atomic operation compares the variable’s value with its value at the start and, if they are the same, updates it with the new value. If they are not the same, the variable must have been modified by another thread; in this situation, the CAS thread can try the whole computation again using the new value, or give up, or—in some algorithms— continue, because the interference will have actually done its work for it! Collections using CAS include ConcurrentLinkedQueue and ConcurrentSkipListMap. The third group uses implementations of java.util.concurrent.locks.Lock, an interface introduced in Java 5 as a more flexible alternative to classical synchronization. A Lock has the same basic behavior as classical synchronization, but a thread can also acquire it under special conditions: only if the lock is not currently held, or with a timeout, or if the thread is not interrupted. Unlike synchronized code, in which an object lock is held while a code block or a method is executed, a Lock is held until its unlock method is called. Some of the collection classes in this group make use of these facilities to divide the collection into parts that can be separately locked, giving improved concurrency. For example, LinkedBlockingQueue has separate locks for the head and tail ends of the queue, so that elements can be added and removed in parallel. Other collections using these locks include ConcurrentHashMap and most of the implementations of BlockingQueue. Iterators The mechanisms described above lead to iterator policies more suitable for concurrent use than fail-fast, which implicitly regards concurrent modification as a problem to be eliminated. Copy-on-write collections have snapshot iterators. These collections are backed by arrays which, once created, are never changed; if a value in the collection needs to be changed, a new array is created. So an iterator can read the values in one of these arrays (but never modify them) without danger of them being changed by another thread. Snapshot iterators do not throw ConcurrentModificatio nException. Collections which rely on CAS have weakly consistent iterators, which reflect some but not necessarily all of the changes that have been made to their backing collection since they were created. For example, if elements in the collection have been modified or removed before the iterator reaches them, it definitely will reflect these changes, but no such guarantee is made for insertions. Weakly consistent iterators also do not throw ConcurrentModificationException. The third group described above also have weakly consistent iterators. In Java 6 this includes DelayQueue and PriorityBlockingQueue, which in Java 5 had fail-fast iterators. This means that you cannot iterate over the Java 5 version of these queues unless they are quiescent, at a time when no elements are being added or inserted; at other times you have to copy their elements into an array using toArray and iterate over that instead. 11.5 Collections and Thread Safety | 159

CHAPTER 12

The Collection Interface

The interface Collection (see Figure 12-1) defines the core functionality that we expect of any collection other than a map. It provides methods in four groups. Adding Elements boolean add(E e) boolean addAll(Collection c)

// add the element e // add the contents of c

The boolean result returned by these methods indicates whether the collection was changed by the call. It can be false for collections, such as sets, which will be unchanged if they are asked to add an element that is already present. But the method contracts specify that the elements being added must be present after execution so, if the collection refuses an element for any other reason (for example, some collections don’t permit null elements), these methods must throw an exception.

Figure 12-1. Collection

161

The signatures of these methods show that, as you might expect, you can add elements or element collections only of the parametric type. Removing Elements boolean remove(Object o) void clear() boolean removeAll(Collection c) boolean retainAll(Collection c)

// // // //

remove remove remove remove

the all the the

element o elements elements in c elements *not* in c

If the element 0 is null, remove removes a null from the collection if one is present. Otherwise, if an element e is present for which 0.equals(e), it removes it. If not, it leaves the collection unchanged. Where a method in this group returns a boolean, the value is true if the collection changed as a result of applying the operation. In contrast to the methods for adding elements, these methods—and those of the next group—will accept elements or element collections of any type. We will explain this in a moment, when we look at examples of the use of these methods. Querying the Contents of a Collection boolean contains(Object o) boolean containsAll(Collection c) boolean isEmpty() int size()

// // // // // //

true if o is present true if all elements of c are present in the collection true if no elements are present return the element count (or Integer.MAX_VALUE if that is less)

The decision to make size return Integer.MAX_VALUE for extremely large collections was probably taken on the assumption that such collections—with more than two billion elements—will rarely arise. Even so, an alternative design which raises an exception instead of returning an arbitrary value would have the merit of ensuring that the contract for size could clearly state that if it does succeed in returning a value, that value will be correct. Making a Collection’s Contents Available for Further Processing Iterator<E> iterator() Object[] toArray()

// return an Iterator over the elements // copy contents to an Object[]

T[] toArray(T[] t)

// copy contents to a T[] (for any T)

The last two methods in this group convert collections into arrays. The first method will create a new array of Object, and the second takes an array of T and returns an array of the same type containing the elements of the collection. These methods are important because, although arrays should now be regarded as a legacy data type (see Section 6.9), many APIs, especially older ones that predate the Java Collections Framework, have methods that accept or return arrays. As discussed in Section 6.4, the argument of the second method is required in order to provide at run time the reifiable type of the array, though it can have another purpose as well: if there is room, the elements of the collection are placed in it—otherwise, a

162 | Chapter 12: The Collection Interface

new array of that type is created. The first case can be useful if you want to allow the toArray method to reuse an array that you supply; this can be more efficient, particularly if the method is being called repeatedly. The second case is more convenient—a common and straightforward idiom is to supply an array of zero length: Collection<String> cs = ... String[] sa = cs.toArray(new String[0]);

A more efficient alternative, if a class uses this idiom more than once, is to declare a single empty array of the required type, that can then be used as many times as required: private static final String[] EMPTY_STRING_ARRAY = new String[0]; Collection<String> cs = ... String[] sa = cs.toArray(EMPTY_STRING_ARRAY);

Why is any type allowed for T in the declaration of toArray? One reason is to give the flexibility to allocate a more specific array type if the collection happens to contain elements of that type: List