Chapter 23. The java.util Package

AbstractCollection	Java 1.2
java.util	collection

This abstract class is a partial implementation of Collection that makes it easy to define custom Collection implementations. To create an unmodifiable collection, simply override size() and iterator(). The Iterator object returned by iterator() has to support only the hasNext() and next() methods. To define a modifiable collection, you must additionally override the add() method of AbstractCollection and make sure the Iterator returned by iterator() supports the remove() method. Some subclasses may choose to override other methods to tune performance. In addition, it is conventional that all subclasses provide two constructors: one that takes no arguments and one that accepts a Collection argument that specifies the initial contents of the collection.

Note that if you subclass AbstractCollection directly, you are implementing a bag--an unordered collection that allows duplicate elements. If your add() method rejects duplicate elements, you should subclass AbstractSet instead. See also AbstractList.

Hierarchy: Object-->AbstractCollection(Collection)

Subclasses: AbstractList, AbstractSet

AbstractList	Java 1.2
java.util	collection

This abstract class is a partial implementation of the List interface that makes it easy to define custom List implementations based on random-access list elements (such as objects stored in an array). If you want to base a List implementation on a sequential-access data model (such as a linked list), subclass AbstractSequentialList instead.

To create an unmodifiable List, simply subclass AbstractList and override the (inherited) size() and get() methods. To create a modifiable list, you must also override set() and, optionally, add() and remove(). These three methods are optional, so unless you override them, they simply throw an UnsupportedOperationException. All other methods of the List interface are implemented in terms of size(), get(), set(), add(), and remove(). In some cases, you may want to override these other methods to improve performance. By convention, all List implementations should define two constructors: one that accepts no arguments and another that accepts a Collection of initial elements for the list.

Hierarchy: Object-->AbstractCollection(Collection)-->AbstractList(java.util.List(Collection))

Subclasses: AbstractSequentialList, ArrayList, Vector

AbstractMap	Java 1.2
java.util	collection

This abstract class is a partial implementation of the Map interface that makes it easy to define simple custom Map implementations. To define an unmodifiable map, subclass AbstractMap and override the entrySet() method so that it returns a set of Map.Entry objects. (Note that you must also implement Map.Entry, of course.) The returned set should not support add() or remove(), and its iterator should not support remove(). In order to define a modifiable Map, you must additionally override the put() method and provide support for the remove() method of the iterator returned by entrySet().iterator(). In addition, it is conventional that all Map implementations define two constructors: one that accepts no arguments and another that accepts a Map of initial mappings.

AbstractMap defines all Map methods in terms of its entrySet() and put() methods and the remove() method of the entry set iterator. Note, however, that the implementation is based on a linear search of the Set returned by entrySet() and is not efficient when the Map contains more than a handful of entries. Some subclasses may want to override additional AbstractMap methods to improve performance. HashMap and TreeMap use different algorithms are are substantially more efficient.

Hierarchy: Object-->AbstractMap(Map)

Subclasses: HashMap, TreeMap, WeakHashMap

AbstractSequentialList	Java 1.2
java.util	collection

This abstract class is a partial implementation of the List interface that makes it easy to define List implementations based on a sequential-access data model, as is the case with the LinkedList subclass. To implement a List based on an array or other random-access model, subclass AbstractList instead.

To implement an unmodifiable list, subclass this class and override the size() and listIterator() methods. listIterator() must return a ListIterator that defines the hasNext(), hasPrevious(), next(), previous(), and index() methods. If you want to allow the list to be modified, the ListIterator should also support the set() method and, optionally, the add() and remove() methods. AbstractSequentialList implements all other List methods in terms of these methods. Some subclasses may want to override additional methods to improve performance. In addition, it is conventional that all List implementations define two constructors: one that accepts no arguments and another that accepts a Collection of initial elements for the list.

Hierarchy: Object-->AbstractCollection(Collection)-->AbstractList(java.util.List(Collection))-->AbstractSequentialList

Subclasses: LinkedList

AbstractSet	Java 1.2
java.util	collection

This abstract class is a partial implementation of the Set interface that makes it easy to create custom Set implementations. Since Set defines the same methods as Collection, you can subclass AbstractSet exactly as you would subclass AbstractCollection. See AbstractCollection for details. Note, however, that when subclassing AbstractSet, you should be sure that your add() method and your constructors do not allow duplicate elements to be added to the set. See also AbstractList.

Hierarchy: Object-->AbstractCollection(Collection)-->AbstractSet(Set(Collection))

Subclasses: HashSet, TreeSet

ArrayList	Java 1.2
java.util	cloneable serializable collection

This class is a List implementation based on an array (that is recreated as necessary as the list grows or shrinks). ArrayList implements all optional List and Collection methods and allows list elements of any type (including null). Because ArrayList is based on an array, the get() and set() methods are very efficient. (This is not the case for the LinkedList implementation, for example.) ArrayList is a general-purpose implementation of List and is quite commonly used. ArrayList is very much like the Vector class, except that its methods are not synchronized. If you are using an ArrayList in a multithreaded environment, you should explicitly synchronize any modifications to the list, or wrap the list with Collections.synchronizedList(). See List and Collection for details on the methods of ArrayList. See also LinkedList.

An ArrayList has a capacity, which is the number of elements in the internal array that contains the elements of the list. When the number of elements exceeds the capacity, a new array, with a larger capacity, must be created. In addition to the List and Collection methods, ArrayList defines a couple of methods that help you manage this capacity. If you know in advance how many elements an ArrayList will contain, you can call ensureCapacity(), which can increase efficiency by avoiding incremental reallocation of the internal array. You can also pass an initial capacity value to the ArrayList() constructor. Finally, if an ArrayList has reached its final size and will not change in the future, you can call trimToSize() to reallocate the internal array with a capacity that matches the list size exactly. When the ArrayList will have a long lifetime, this can be a useful technique to reduce memory usage.

Hierarchy: Object-->AbstractCollection(Collection)-->AbstractList(java.util.List(Collection))-->ArrayList(Cloneable,java.util.List(Collection),Serializable)

Type Of: java.awt.dnd.DragGestureRecognizer.events, java.beans.beancontext.BeanContextServicesSupport.bcsListeners, java.beans.beancontext.BeanContextSupport.bcmListeners

Arrays	Java 1.2
java.util

This class defines static methods for sorting, searching, and performing other useful operations on arrays. It also defines the asList() method, which returns a List wrapper around a specified array of objects. Any changes made to the List are also made to the underlying array. This is a powerful method that allows any array of objects to be manipulated in any of the ways a List can be manipulated. It provides a link between arrays and the Java collections framework.

The various sort() methods sort an array (or a specified portion of an array) in place. Variants of the method are defined for arrays of each primitive type and for arrays of Object. For arrays of primitive types, the sorting is done according to the natural ordering of the type. For arrays of objects, the sorting is done according to the specified Comparator, or, if the array contains only java.lang.Comparable objects, according to the ordering defined by that interface. When sorting an array of objects, a stable sorting algorithm is used so that the relative ordering of equal objects is not disturbed. (This allows repeated sorts to order objects by key and subkey, for example.)

The binarySearch() methods perform an efficient search (in logarithmic time) of a sorted array for a specified value. If a match is found in the array, binarySearch() returns the index of the match. If no match is found, the method returns a negative number. For a negative return value r, the index -(r+1) specifies the array index at which the specified value can be inserted to maintain the sorted order of the array. When the array to be searched is an array of objects, the elements of the array must all implement java.lang.Comparable, or you must provide a Comparator object to compare them.

The equals() methods test whether two arrays are equal. Two arrays of primitive type are equal if they contain the same number of elements and if corresponding pairs of elements are equal according to the == operator. Two arrays of objects are equal if they contain the same number of elements and if corresponding pairs of elements are equal according to the equals() method defined by those objects. The fill() methods fill an array or a specified range of an array with the specified value.

BitSet	Java 1.0
java.util	cloneable serializable PJ1.1

This class defines an arbitrarily large set of bits. Instance methods allow you to set, clear, and query individual bits in the set. You can also perform bitwise boolean arithmetic on the bits in BitSet objects. This class can be used as an extremely compact array of boolean values, although reading and writing those values is slower than normal array access.

Hierarchy: Object-->BitSet(Cloneable,Serializable)

Passed To: BitSet.{and(), andNot(), or(), xor()}, javax.swing.text.html.parser.DTD.defineElement()

Type Of: javax.swing.text.html.parser.Element.{exclusions, inclusions}

Calendar	Java 1.1
java.util	cloneable serializable PJ1.1

This abstract class defines methods that perform date and time arithmetic. It also includes methods that convert dates and times to and from the machine-usable millisecond format used by the Date class and units such as minutes, hours, days, weeks, months, and years that are more useful to humans. As an abstract class, Calendar cannot be directly instantiated. Instead, it provides static getInstance() methods that return instances of a Calendar subclass suitable for use in a specified or default locale with a specified or default time zone. See also Date, DateFormat, and TimeZone.

Calendar defines a number of useful constants. Some of these are values that represent days of the week and months of the year. Other constants, such as HOUR and DAY_OF_WEEK, represent various fields of date and time information. These field constants are passed to a number of Calendar methods, such as get() and set(), in order to indicate what particular date or time field is desired.

setTime() and the various set() methods set the date represented by a Calendar object. The add() method adds (or subtracts) values to a calendar field, incrementing the next larger field when the field being set rolls over. roll() does the same, without modifying anything but the specified field. before() and after() compare two Calendar objects. Many of the methods of the Calendar class are replacements for methods of Date that have been deprecated as of Java 1.1. While the Calendar class converts a time value to its various hour, day, month, and other fields, it is not intended to present those fields in a form suitable for display to the end user. That function is performed by the java.text.DateFormat class, which handles internationalization issues.

Hierarchy: Object-->Calendar(Cloneable,Serializable)

Subclasses: GregorianCalendar

Passed To: Too many methods to list.

Returned By: java.text.DateFormat.getCalendar(), Calendar.getInstance()

Type Of: java.text.DateFormat.calendar

Collection	Java 1.2
java.util	collection

This interface represents a group, or collection, of objects. The objects may or may not be ordered, and the collection may or may not contain duplicate objects. Collection is not often implemented directly. Instead, most collection classes implement one of the more specific subinterfaces: Set, an unordered collection that does not allow duplicates, or List, an ordered collection that does allow duplicates.

The Collection type provides a general way to refer to any set, list, or other collection of objects; it defines generic methods that work with any collection. contains() and containsAll() test whether the Collection contains a specified object or all the objects in a given collection. isEmpty() returns true if the Collection has no elements, or false otherwise. size() returns the number of elements in the Collection. iterator() returns an Iterator object that allows you to iterate through the objects in the collection. toArray() returns the objects in the Collection in a new array of type Object. Another version of toArray() takes an array as an argument and stores all elements of the Collection (which must all be compatible with the array) into that array. If the array is not big enough, the method allocates a new, larger array of the same type. If the array is too big, the method stores null into the first empty element of the array. This version of toArray() returns the array that was passed in or the new array, if one was allocated.

The previous methods all query or extract the contents of a collection. The Collection interface also defines methods for modifying the contents of the collection. add() and addAll() add an object or a collection of objects to a Collection. remove() and removeAll() remove an object or collection. retainAll() is a variant that removes all objects except those in a specified Collection. clear() removes all objects from the collection. All these modification methods except clear() return true if the collection was modified as a result of the call. An interface cannot specify constructors, but it is conventional that all implementations of Collection provide at least two standard constructors: one that takes no arguments and creates an empty collection, and a copy constructor that accepts a Collection object that specifies the initial contents of the new Collection.

Implementations of Collection and its subinterfaces are not required to support all operations defined by the Collection interface. All modification methods listed above are optional; an implementation (such as an immutable Set implementation) that does not support them simply throws java.lang.UnsupportedOperationException for these methods. Furthermore, implementations are free to impose restrictions on the types of objects that can be members of a collection. Some implementations might require elements to be of a particular type, for example, and others might not allow null as an element.

See also Set, List, Map, and Collections.

Implementations: java.beans.beancontext.BeanContext, AbstractCollection, java.util.List, Set

Passed To: Too many methods to list.

Returned By: java.awt.RenderingHints.values(), java.security.Provider.values(), java.security.cert.CertificateFactory.{generateCertificates(), generateCRLs()}, java.security.cert.CertificateFactorySpi.{engineGenerateCertificates(), engineGenerateCRLs()}, AbstractMap.values(), Collections.{synchronizedCollection(), unmodifiableCollection()}, HashMap.values(), Hashtable.values(), Map.values(), TreeMap.values(), java.util.jar.Attributes.values()

Type Of: java.beans.beancontext.BeanContextMembershipEvent.children

Collections	Java 1.2
java.util

This class defines static methods and constants that are useful for working with collections and maps. One of the most commonly used methods is sort(), which sorts a List in place (the list cannot be immutable, of course). The sorting algorithm is stable, which means that equal elements retain the same relative order. One version of sort() uses a specified Comparator to perform the sort; the other relies on the natural ordering of the list elements and requires all the elements to implement java.lang.Comparable.

A related method is binarySearch(). It efficiently (in logarithmic time) searches a sorted List for a specified object and returns the index at which a matching object is found. If no match is found, it returns a negative number. For a negative return value r, the value -(r+1) specifies the index at which the specified object can be inserted into the list to maintain the sorted order of the list. As with sort(), binarySearch() can be passed a Comparator that defines the order of the sorted list. If no Comparator is specified, the list elements must all implement Comparable, and the list is assumed to be sorted according to the natural ordering defined by this interface.

The various methods whose names begin with synchronized return a thread-safe collection object wrapped around the specified collection. Vector and Hashtable are the only two collection objects thread-safe by default. Use these methods to obtain a synchronized wrapper object if you are using any other type of Collection or Map in a multithreaded environment where more than one thread can modify it.

The various methods whose names begin with unmodifiable function like synchronized methods. They return a Collection or Map object wrapped around the specified collection. The returned object is unmodifiable, however, so its add(), remove(), set(), put(), etc., methods all throw java.lang.UnsupportedOperationException.

The Collections class also defines a number of miscellanous methods. copy() copies elements of a source list into a destination list. enumeration() returns an Enumeration for a Collection, which is useful when working with code that uses the old Enumeration interface instead of the newer Iterator interface. fill() replaces all elements of the specified list with the specified object. The min() and max() methods search an unordered Collection for the minimum and maximum elements, according either to a specified Comparator or to the natural order defined by the Comparable elements themselves. nCopies() creates a new immutable List that contains a specified number of copies of a specified object. reverse() reverses the order of the elements in a list. This method operates in place and therefore does not work for immutable lists. reverseOrder() returns a convenient predefined Comparator object that can order Comparable objects into the reverse of their natural ordering. shuffle() randomizes the order of elements in a list, using either an internal source of randomness or the Random pseudo-random number generator you provide. singleton() returns an unmodifiable set that contains only the specified object. The Collections class also defines two related constants, EMPTY_LIST and EMPTY_SET, which are immutable List and Set objects that contain no elements. In Java 1.3, singletonList() and singletonMap() return an immutable list and an immutable map, respectively, each of which contains only a single entry. The Collections class also defines related constants, EMPTY_LIST, EMPTY_SET, and EMPTY_MAP (in Java 1.3), which are immutable List, Set, and Map objects that contain no elements.

See Arrays for methods that perform sorting and searching operations on arrays instead of collections.

Comparator	Java 1.2
java.util

This interface defines a compare() method that specifies a total ordering for a set of objects, allowing those objects to be sorted. The Comparator is used when the objects to be ordered do not have a natural ordering defined by the Comparable interface, or when you want to order them using something other than their natural ordering.

The compare() method is passed two objects. If the first argument is less than the second argument or should be placed before the second argument in a sorted list, compare() should return a negative integer. If the first argument is greater than the second argument or should be placed after the second argument in a sorted list, compare() should return a positive integer. If the two objects are equivalent or if their relative position in a sorted list does not matter, compare() should return 0. Comparator implementations may assume that both Object arguments are of appropriate types and cast them as desired. If either argument is not of the expected type, the compare() method throws a ClassCastException.

Note that the magnitude of the numbers returned by compare() does not matter, only whether they are less than, equal to, or greater than zero. In most cases, you should implement a Comparator so that compare(o1,o2) returns 0 if and only if o1.equals(o2) returns true. This is particularly important when using a Comparator to impose an ordering on a TreeSet or a TreeMap.

See Collections and Arrays for various methods that use Comparator objects for sorting and searching. See also the related java.lang.Comparable interface.

Implementations: java.text.Collator

Passed To: Arrays.{binarySearch(), sort()}, Collections.{binarySearch(), max(), min(), sort()}, TreeMap.TreeMap(), TreeSet.TreeSet()

Returned By: Collections.reverseOrder(), SortedMap.comparator(), SortedSet.comparator(), TreeMap.comparator(), TreeSet.comparator()

Type Of: String.CASE_INSENSITIVE_ORDER

ConcurrentModificationException	Java 1.2
java.util	serializable unchecked

Signals that a modification has been made to a data structure at the same time some other operation is in progress and that, as a result, the correctness of the ongoing operation cannot be guaranteed. It is typically thrown by an Iterator or ListIterator object to stop an iteration if it detects that the underlying collection has been modified while the iteration is in progress.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->RuntimeException-->ConcurrentModificationException

Date	Java 1.0
java.util	cloneable serializable comparable PJ1.1

This class represents dates and times and lets you work with them in a system-independent way. You can create a Date by specifying the number of milliseconds from the epoch (midnight GMT, January 1st, 1970) or the year, month, date, and, optionally, the hour, minute, and second. Years are specified as the number of years since 1900. If you call the Date constructor with no arguments, the Date is initialized to the current time and date. The instance methods of the class allow you to get and set the various date and time fields, to compare dates and times, and to convert dates to and from string representations. As of Java 1.1, many of the date methods have been deprecated in favor of the methods of the Calendar class.

Hierarchy: Object-->java.util.Date(Cloneable,Comparable,Serializable)

Subclasses: java.sql.Date, java.sql.Time, java.sql.Timestamp

Passed To: java.security.cert.X509Certificate.checkValidity(), java.text.DateFormat.format(), java.text.SimpleDateFormat.{format(), set2DigitYearStart()}, Calendar.setTime(), java.util.Date.{after(), before(), compareTo()}, GregorianCalendar.setGregorianChange(), SimpleTimeZone.inDaylightTime(), java.util.Timer.{schedule(), scheduleAtFixedRate()}, TimeZone.inDaylightTime()

Returned By: java.security.KeyStore.getCreationDate(), java.security.KeyStoreSpi.engineGetCreationDate(), java.security.cert.X509Certificate.{getNotAfter(), getNotBefore()}, java.security.cert.X509CRL.{getNextUpdate(), getThisUpdate()}, java.security.cert.X509CRLEntry.getRevocationDate(), java.text.DateFormat.parse(), java.text.SimpleDateFormat.{get2DigitYearStart(), parse()}, Calendar.getTime(), GregorianCalendar.getGregorianChange()

Dictionary	Java 1.0
java.util	PJ1.1

This abstract class is the superclass of Hashtable. Other hashtable-like data structures might also extend this class. See Hashtable for more information. In Java 1.2, the Map interface replaces the functionality of this class.