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.

Subclasses: Hashtable

Passed To: javax.swing.JSlider.setLabelTable(), javax.swing.text.AbstractDocument.setDocumentProperties()

Returned By: javax.swing.JSlider.getLabelTable(), javax.swing.text.AbstractDocument.getDocumentProperties()

EmptyStackException	Java 1.0
java.util	serializable unchecked PJ1.1

Signals that a Stack object is empty.

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

Thrown By: java.awt.EventQueue.pop()

Enumeration	Java 1.0
java.util	PJ1.1

This interface defines the methods necessary to enumerate, or iterate, through a set of values, such as the set of values contained in a hashtable or binary tree. It is particularly useful for data structures, like hashtables, for which elements cannot simply be looked up by index, as they can in arrays. An Enumeration is usually not instantiated directly, but instead is created by the object that is to have its values enumerated. A number of classes, such as Vector and Hashtable, have methods that return Enumeration objects. In Java 1.2, the new Iterator interface is preferred over Enumeration.

To use an Enumeration object, you use its two methods in a loop. hasMoreElements() returns true if there are more values to be enumerated and can determine whether a loop should continue. Within a loop, a call to nextElement() returns a value from the enumeration. An Enumeration makes no guarantees about the order in which the values are returned. The values in an Enumeration can be iterated through only once; there is no way to reset it to the beginning.

Implementations: StringTokenizer, javax.naming.NamingEnumeration

Passed To: java.io.SequenceInputStream.SequenceInputStream(), javax.naming.CompositeName.CompositeName(), javax.naming.CompoundName.CompoundName(), javax.swing.JTree.removeDescendantToggledPaths(), javax.swing.text.AbstractDocument.AbstractElement.removeAttributes(), javax.swing.text.AbstractDocument.AttributeContext.removeAttributes(), javax.swing.text.MutableAttributeSet.removeAttributes(), javax.swing.text.SimpleAttributeSet.removeAttributes(), javax.swing.text.StyleContext.removeAttributes(), javax.swing.text.StyleContext.NamedStyle.removeAttributes(), javax.swing.text.html.StyleSheet.removeAttributes()

Returned By: Too many methods to list.

Type Of: javax.swing.tree.DefaultMutableTreeNode.EMPTY_ENUMERATION

EventListener	Java 1.1
java.util	event listener PJ1.1

EventListener is a base interface for the event model that is used by AWT and Swing in Java 1.1 and later. This interface defines no methods or constants; it serves simply as a tag that identifies objects that act as event listeners. The event listener interfaces in the java.awt.event, java.beans, and javax.swing.event packages extend this interface.

Implementations: Too many classes to list.

Passed To: java.awt.AWTEventMulticaster.{addInternal(), AWTEventMulticaster(), remove(), removeInternal(), save()}, javax.swing.event.EventListenerList.{add(), remove()}

Returned By: Too many methods to list.

Type Of: java.awt.AWTEventMulticaster.{a, b}

EventObject	Java 1.1
java.util	serializable event PJ1.1

EventObject serves as the superclass for all event objects used by the event model introduced in Java 1.1 for AWT and JavaBeans and also used by Swing in Java 1.2. This class defines a generic type of event; it is extended by the more specific event classes in the java.awt, java.awt.event, java.beans, and javax.swing.event packages. The only common feature shared by all events is a source object, which is the object that, in some way, generated the event. The source object is passed to the EventObject() constructor and is returned by the getSource() method.

Hierarchy: Object-->EventObject(Serializable)

Subclasses: Too many classes to list.

Passed To: javax.swing.AbstractCellEditor.{isCellEditable(), shouldSelectCell()}, javax.swing.CellEditor.{isCellEditable(), shouldSelectCell()}, javax.swing.DefaultCellEditor.{isCellEditable(), shouldSelectCell()}, javax.swing.DefaultCellEditor.EditorDelegate.{isCellEditable(), shouldSelectCell(), startCellEditing()}, javax.swing.JTable.editCellAt(), javax.swing.tree.DefaultTreeCellEditor.{canEditImmediately(), isCellEditable(), shouldSelectCell(), shouldStartEditingTimer()}

GregorianCalendar	Java 1.1
java.util	cloneable serializable PJ1.1

This concrete subclass of Calendar implements the standard solar calendar with years numbered from the birth of Christ that is used is most locales throughout the world. You do not typically use this class directly, but instead obtain a Calendar object suitable for the default locale by calling Calendar.getInstance(). See Calendar for details on working with Calendar objects. There is a discontinuity in the Gregorian calendar that represents the historical switch from the Julian calendar to the Gregorian calendar. By default, GregorianCalendar assumes that this switch occurs on October 15, 1582. Most programs need not be concerned with the switch.

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

HashMap	Java 1.2
java.util	cloneable serializable collection

This class implements the Map interface using an internal hashtable. It supports all optional Map methods, allows key and value objects of any types, and allows null to be used as a key or a value. Because HashMap is based on a hashtable data structure, the get() and put() methods are very efficient. HashMap is much like the Hashtable class, except that the HashMap methods are not synchronized (and are therefore faster), and HashMap allows null to be used as a key or a value. If you are working in a multithreaded environment, or if compatibility with previous versions of Java is a concern, use Hashtable. Otherwise, use HashMap.

If you know in advance approximately how many mappings a HashMap will contain, you can improve efficiency by specifying initialCapacity when you call the HashMap() constructor. The initialCapacity argument times the loadFactor argument should be greater than the number of mappings the HashMap will contain. A good value for loadFactor is 0.75; this is also the default value. See Map for details on the methods of HashMap. See also TreeMap and HashSet.

Hierarchy: Object-->AbstractMap(Map)-->HashMap(Cloneable,Map,Serializable)

Type Of: java.beans.beancontext.BeanContextServicesSupport.services, java.beans.beancontext.BeanContextSupport.children

HashSet	Java 1.2
java.util	cloneable serializable collection

This class implements Set using an internal hashtable. It supports all optional Set and Collection methods and allows any type of object or null to be a member of the set. Because HashSet is based on a hashtable, the basic add(), remove(), and contains() methods are all quite efficient. HashSet makes no guarantee about the order in which the set elements are enumerated by the Iterator returned by iterator(). The methods of HashSet are not synchronized. If you are using it in a multithreaded environment, you must explicitly synchronize all code that modifies the set or obtain a synchronized wrapper for it by calling Collections.synchronizedSet().

If you know in advance approximately how many mappings a HashSet will contain, you can improve efficiency by specifying initialCapacity when you call the HashSet() constructor. The initialCapacity argument times the loadFactor argument should be greater than the number of mappings the HashSet will contain. A good value for loadFactor is 0.75; this is also the default value. See Set and Collection for details on the methods of HashSet. See also TreeSet and HashMap.

Hierarchy: Object-->AbstractCollection(Collection)-->AbstractSet(Set(Collection))-->HashSet(Cloneable,Serializable,Set(Collection))

Hashtable	Java 1.0
java.util	cloneable serializable collection PJ1.1

This class implements a hashtable data structure, which maps key objects to value objects and allows the efficient lookup of the value associated with a given key. put() associates a value with a key in a Hashtable. get() retrieves a value for a specified key. remove() deletes a key/value association. keys() and elements() return Enumeration objects that allow you to iterate through the complete set of keys and values stored in the table. Objects used as keys in a Hashtable must have valid equals() and hashCode() methods (the versions inherited from Object are okay). null is not legal as a key or value in a Hashtable.

Hashtable is a commonly used class and has been a part of the Java API since Java 1.0. In Java 1.2, it has been enhanced to implement the Map interface, which defines some functionality in addition to the Java 1.0 Hashtable methods. Hashtable is very similar to the HashMap class, but has synchronized methods, which make it thread-safe but increase the overhead associated with it. If you need thread safety or require compatibility with Java 1.0 or Java 1.1, use Hashtable. Otherwise, use HashMap.

Hierarchy: Object-->Dictionary-->Hashtable(Cloneable,Map,Serializable)

Subclasses: Properties, javax.swing.UIDefaults

Passed To: Too many methods to list.

Returned By: javax.naming.CannotProceedException.getEnvironment(), javax.naming.Context.getEnvironment(), javax.naming.InitialContext.getEnvironment(), javax.servlet.http.HttpUtils.{parsePostData(), parseQueryString()}, javax.swing.JLayeredPane.getComponentToLayer(), javax.swing.JSlider.createStandardLabels()

Type Of: java.awt.GridBagLayout.comptable, javax.naming.CannotProceedException.environment, javax.naming.InitialContext.myProps, javax.swing.JTable.{defaultEditorsByColumnClass, defaultRenderersByColumnClass}, javax.swing.text.html.parser.DTD.{elementHash, entityHash}, javax.swing.undo.StateEdit.{postState, preState}

Iterator	Java 1.2
java.util

This interface defines methods for iterating, or enumerating, the elements of a collection. The hasNext() method returns true if there are more elements to be enumerated or false if all elements have already been returned. The next() method returns the next element. These two methods make it easy to loop through an iterator with code such as the following:

for(Iterator i = c.iterator(); i.hasNext(); )
    processObject(i.next());

The Iterator interface is much like the Enumeration interface. In Java 1.2, Iterator is preferred over Enumeration because it provides a well-defined way to safely remove elements from a collection while the iteration is in progress. The remove() method removes the object most recently returned by next() from the collection that is being iterated through. Note, however, that support for remove() is optional; if an Iterator does not support remove(), it throws a java.lang.UnsupportedOperationException when you call it. While you are iterating through a collection, you are allowed to modify the collection only by calling the remove() method of the Iterator. If the collection is modified in any other way while an iteration is ongoing, the Iterator may fail to operate correctly,x or it may throw a ConcurrentModificationException.

Implementations: java.beans.beancontext.BeanContextSupport.BCSIterator, ListIterator

Returned By: Too many methods to list.

LinkedList	Java 1.2
java.util	cloneable serializable collection

This class implements the List interface in terms of a doubly linked list. It supports all optional methods of List and Collection and allows list elements of any type, including null. Because LinkedList is implemented with a linked list data structure, the get() and set() methods are substantially less efficient than the same methods for an ArrayList. However, a LinkedList may be more efficient when the add() and remove() methods are used frequently. The methods of LinkedList are not synchronized. If you are using a LinkedList in a multithreaded environment, you must explicitly synchronize any code that modifies the list or obtain a synchronized wrapper object with Collections.synchronizedList().

In addition to the methods defined by the List interface, LinkedList defines methods to get the first and last elements of the list, to add an element to the beginning or end of the list, and to remove the first or last element of the list. These convenient and efficient methods make LinkedList well-suited for use as a stack or queue. See List and Collection for details on the methods of LinkedList. See also ArrayList.

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

List	Java 1.2
java.util	collection

This interface represents an ordered collection of objects. Each element in a List has an index, or position, in the list, and elements can be inserted, queried, and removed by index. The first element of a List has an index of 0. The last element in a list has index size()-1.

In addition to the methods defined by the superinterface, Collection, List defines a number of methods for working with its indexed elements. get() and set() query and set the object at a particular index, respectively. Versions of add() and addAll() that take an index argument insert an object or Collection of objects at a specified index. The versions of add() and addAll() that do not take an index argument insert an object or collection of objects at the end of the list. List defines a version of remove() that removes the object at a specified index.

The iterator() method is just like the iterator() method of Collection, except that the Iterator it returns is guaranteed to enumerate the elements of the List in order. listIterator() returns a ListIterator object, which is more powerful than a regular Iterator and allows the list to be modified while iteration proceeds. listIterator() can take an index argument to specify where in the list iteration should begin.

indexOf() and lastIndexOf() perform linear searches from the beginning and end, respectively, of the list, searching for a specified object. Each method returns the index of the first matching object it finds, or -1 if it does not find a match. Finally, subList() returns a List that contains only a specified contiguous range of list elements. The returned list is simply a view into the original list, so changes in the original List are visible in the returned List. This subList() method is particularly useful if you want to sort, search, clear(), or otherwise manipulate only a partial range of a larger list.

An interface cannot specify constructors, but it is conventional that all implementations of List provide at least two standard constructors: one that takes no arguments and creates an empty list, and a copy constructor that accepts an arbitrary Collection object that specifies the initial contents of the new List.

As with Collection, all List methods that change the contents of the list are optional, and implementations that do not support them simply throw java.lang.UnsupportedOperationException. Different implementations of List may have significantly different efficiency characteristics. For example, the get() and set() methods of an ArrayList are much more efficient than those of a LinkedList. On the other hand, the add() and remove() methods of a LinkedList can be more efficient than those of an ArrayList. See also Collection, Set, Map, ArrayList, and LinkedList.

Hierarchy: (java.util.List(Collection))

Implementations: AbstractList, ArrayList, LinkedList, Vector

Passed To: java.awt.dnd.DragGestureEvent.DragGestureEvent(), Collections.{binarySearch(), copy(), fill(), reverse(), shuffle(), sort(), synchronizedList(), unmodifiableList()}

Returned By: java.awt.dnd.DropTargetContext.getCurrentDataFlavorsAsList(), java.awt.dnd.DropTargetDragEvent.getCurrentDataFlavorsAsList(), java.awt.dnd.DropTargetDropEvent.getCurrentDataFlavorsAsList(), AbstractList.subList(), Arrays.asList(), Collections.{nCopies(), singletonList(), synchronizedList(), unmodifiableList()}, java.util.List.subList(), Vector.subList()

Type Of: Collections.EMPTY_LIST

ListIterator	Java 1.2
java.util

This interface is an extension of Iterator for use with ordered collections, or lists. It defines methods to iterate forward and backward through a list, to determine the list index of the elements being iterated, and, for mutable lists, to safely insert, delete, and edit elements in the list while the iteration is in progress. For some lists, notably LinkedList, using an iterator to enumerate the list's elements may be substantially more efficient than looping through the list by index and calling get() repeatedly.

hasNext() and next() are the most commonly used methods of ListIterator; they iterate forward through the list. See Iterator for details. In addition to these two methods, however, ListIterator also defines hasPrevious() and previous() that allow you to iterate backward through the list. previous() returns the previous element on the list or throws a NoSuchElementException if there is no previous element. hasPrevious() returns true if a subsequent call to previous() returns an object. nextIndex() and previousIndex() return the index of the object that would be returned by a subsequent call to next() or previous(). If next() or previous() throw a NoSuchElementException, nextIndex() returns the size of the list, and previousIndex() returns -1.

ListIterator defines three optionally supported methods that provide a safe way to modify the contents of the underlying list while the iteration is in progress. add() inserts a new object into the list, immediately before the object that would be returned by a subsequent call to next(). Calling add() does not affect the value that is returned by next(), however. If you call previous() immediately after calling add(), the method returns the object you just added. remove() deletes from the list the object most recently returned by next() or previous(). You can only call remove() once per call to next() or previous(). If you have called add(), you must call next() or previous() again before calling remove(). set() replaces the object most recently returned by next() or previous() with the specified object. If you have called add() or remove(), you must call next() or previous() again before calling set(). Remember that support for the add(), remove(), and set() methods is optional. Iterators for immutable lists never support them, of course. An unsupported method throws a java.lang.UnsupportedOperationException when called. Also, when an iterator is in use, all modifications should be made through the iterator rather than to the list itself. If the underlying list is modified while an iteration is ongoing, the ListIterator may fail to operate correctly or may throw a ConcurrentModificationException.

Hierarchy: (ListIterator(Iterator))

Returned By: AbstractList.listIterator(), AbstractSequentialList.listIterator(), LinkedList.listIterator(), java.util.List.listIterator()

ListResourceBundle	Java 1.1
java.util	PJ1.1

This abstract class provides a simple way to define a ResourceBundle. You may find it easier to subclass ListResourceBundle than to subclass ResourceBundle directly. ListResourceBundle provides implementations for the abstract handleGetObject() and getKeys() methods defined by ResourceBundle and adds its own abstract getContents() method a subclass must override. getContents() returns an Object[][]--an array of arrays of objects. This array can have any number of elements. Each element of this array must itself be an array with two elements: the first element of each subarray should be a String that specifies the name of a resource, and the corresponding second element should be the value of that resource; this value can be an Object of any desired type. See also ResourceBundle and PropertyResourceBundle.

Hierarchy: Object-->ResourceBundle-->ListResourceBundle

Subclasses: java.text.resources.DateFormatZoneData, java.text.resources.DateFormatZoneData_en, java.text.resources.LocaleElements, java.text.resources.LocaleElements_en, java.text.resources.LocaleElements_en_US, javax.accessibility.AccessibleResourceBundle

Locale	Java 1.1
java.util	cloneable serializable PJ1.1

The Locale class represents a locale: a political, geographical, or cultural region that typically has a distinct language and distinct customs and conventions for such things as formatting dates, times, and numbers. The Locale class defines a number of constants that represent commonly used locales. Locale also defines a static getDefault() method that returns the default Locale object, which represents a locale value inherited from the host system. getAvailableLocales() returns the list of all locales supported by the underlying system. If none of these methods for obtaining a Locale object are suitable, you can explicitly create your own Locale object. To do this, you must specify a language code, a country code, and an optional variant string. getISOCountries() and getISOLanguages() return the list of supported country codes and language codes.

The Locale class does not implement any internationalization behavior itself; it merely serves as a locale identifier for those classes that can localize their behavior. Given a Locale object, you can invoke the various getDisplay methods to obtain a description of the locale suitable for display to a user. These methods may themselves take a Locale argument, so the names of languages and countries can be localized as appropriate.

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

Passed To: Too many methods to list.

Returned By: Too many methods to list.

Type Of: Too many fields to list.

Map	Java 1.2
java.util	collection

This interface represents a collection of mappings, or associations, between key objects and value objects. Hashtables and associative arrays are examples of maps. The set of key objects in a Map must not have any duplicates; the collection of value objects is under no such constraint. The key objects should usually be immutable objects, or, if they are not, care should be taken that they do not change while in use in a Map. As of Java 1.2, the Map interface replaces the abstract Dictionary class. Although a Map is not a Collection, the Map interface is still considered an integral part, along with Set, List, and others, of the Java collections framework.

You can add a key/value association to a Map with the put() method. Use putAll() to copy all mappings from one Map to another. Call get() to look up the value object associated with a specified key object. Use remove() to delete the mapping between a specified key and its value, or use clear() to delete all mappings from a Map. size() returns the number of mappings in a Map, and isEmpty() tests whether the Map contains no mappings. containsKey() tests whether a Map contains the specified key object, and containsValue() tests whether it contains the specified value. (For most implementations, containsValue() is a much more expensive operation than containsKey(), however.) keySet() returns a Set of all key objects in the Map. values() returns a Collection (not a Set, since it may contain duplicates) of all value objects in the map. entrySet() returns a Set of all mappings in a Map. The elements of this returned Set are Map.Entry objects. The collections returned by values(), keySet(), and entrySet() are based on the Map itself, so changes to the Map are reflected in the collections.

An interface cannot specify constructors, but it is conventional that all implementations of Map provide at least two standard constructors: one that takes no arguments and creates an empty map, and a copy constructor that accepts a Map object that specifies the initial contents of the new Map.

Implementations are required to support all methods that query the contents of a Map, but support for methods that modify the contents of a Map is optional. If an implementation does not support a particular method, the implementation of that method simply throws a java.lang.UnsupportedOperationException. See also Collection, Set, List, HashMap, Hashtable, WeakHashMap, SortedMap, and TreeMap.

Implementations: java.awt.RenderingHints, AbstractMap, HashMap, Hashtable, SortedMap, WeakHashMap, java.util.jar.Attributes

Passed To: Too many methods to list.

Returned By: java.awt.Font.getAttributes(), java.awt.Toolkit.mapInputMethodHighlight(), java.awt.datatransfer.FlavorMap.{getFlavorsForNatives(), getNativesForFlavors()}, java.awt.datatransfer.SystemFlavorMap.{getFlavorsForNatives(), getNativesForFlavors()}, java.awt.im.InputMethodHighlight.getStyle(), java.sql.Connection.getTypeMap(), java.text.AttributedCharacterIterator.getAttributes(), Collections.{singletonMap(), synchronizedMap(), unmodifiableMap()}, java.util.jar.Manifest.getEntries(), javax.sql.RowSet.getTypeMap()

Type Of: java.awt.Toolkit.desktopProperties, Collections.EMPTY_MAP, java.util.jar.Attributes.map

Map.Entry	Java 1.2
java.util

This interface represents a single mapping, or association, between a key object and a value object in a Map. The entrySet() method of a Map returns a Set of Map.Entry objects that represent the set of mappings in the map. Use the iterator() method of that Set to enumerate these Map.Entry objects. Use getKey() and getValue() to obtain the key and value objects for the entry. Use the optionally supported setValue() method to change the value of an entry. This method throws a java.lang.UnsupportedOperationException if it is not supported by the implementation.

MissingResourceException	Java 1.1
java.util	serializable unchecked PJ1.1

Signals that no ResourceBundle can be located for the desired locale or that a named resource cannot be found within a given ResourceBundle. getClassName() returns the name of the ResourceBundle class in question, and getKey() returns the name of the resource that cannot be located.

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

Thrown By: Locale.{getISO3Country(), getISO3Language()}, ResourceBundle.{getBundle(), getObject(), getString(), getStringArray(), handleGetObject()}

NoSuchElementException	Java 1.0
java.util	serializable unchecked PJ1.1

Signals that there are no elements in an object (such as a Vector) or that there are no more elements in an object (such as an Enumeration).

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

Observable	Java 1.0
java.util	PJ1.1

This class is the superclass of all observable objects to be used in an object-oriented model/view paradigm. The class methods allow you to add and delete Observer objects on the list maintained by an Observable object and to notify all of the Observer objects on the list. Observer objects are notified by invoking their update() methods. Observable also maintains an internal changed flag that can be set and cleared by the Observable itself and queried with hasChanged() by any interested observer.

Passed To: Observer.update()

Observer	Java 1.0
java.util	PJ1.1

This interface defines the update() method required for an object to observe subclasses of Observable. An Observer registers interest in an Observable object by calling the addObserver() method of Observable. Observer objects that have been registered in this way have their update() methods invoked by the Observable when that object has changed.

Passed To: Observable.{addObserver(), deleteObserver()}

Properties	Java 1.0
java.util	cloneable serializable collection PJ1.1

This class is an extension of Hashtable that allows key/value pairs to be read from and written to a stream. The Properties class implements the system properties list, which supports user customization by allowing programs to look up the values of named resources. Because the load() and store() methods provide an easy way to read and write properties from and to a text stream, this class provides a convenient way to implement an application configuration file.

When you create a Properties object, you may specify another Properties object that contains default values. Keys (property names) and values are associated in a Properties object with the Hashtable method put(). Values are looked up with getProperty(); if this method does not find the key in the current Properties object, it looks in the default Properties object that was passed to the constructor method. A default value can also be specified, in case the key is not found at all. Use setProperty() to add a property name/value pair to the Properties object. This Java 1.2 method is preferred over the inherited put() method because it enforces the constraint that property names and values be strings.

propertyNames() returns an enumeration of all property names (keys) stored in the Properties object and (recursively) all property names stored in the default Properties object associated with it. list() prints the properties stored in a Properties object, which can be useful for debugging. store() writes a Properties object to a stream, writing one property per line, in name=value format. As of Java 1.2, store() is preferred over the deprecated save() method, which writes properties in the same way but suppresses any I/O exceptions that may be thrown in the process. The second argument to both store() and save() is a comment that is written out at the beginning of the property file. Finally, load() reads key/value pairs from a stream and stores them in a Properties object. It is suitable for reading both properties written with store() and hand-edited properties files.

Hierarchy: Object-->Dictionary-->Hashtable(Cloneable,Map,Serializable)-->Properties

Subclasses: java.security.Provider

Passed To: java.awt.Toolkit.getPrintJob(), System.setProperties(), java.rmi.activation.ActivationGroupDesc.ActivationGroupDesc(), java.sql.Driver.{connect(), getPropertyInfo()}, java.sql.DriverManager.getConnection(), Properties.Properties(), javax.ejb.deployment.DeploymentDescriptor.setEnvironmentProperties(), javax.naming.CompoundName.CompoundName(), org.omg.CORBA.ORB.{init(), set_parameters()}

Returned By: System.getProperties(), java.rmi.activation.ActivationGroupDesc.getPropertyOverrides(), javax.ejb.EJBContext.getEnvironment(), javax.ejb.deployment.DeploymentDescriptor.getEnvironmentProperties()

Type Of: Properties.defaults, javax.naming.CompoundName.mySyntax

PropertyPermission	Java 1.2
java.util	serializable permission

This class is a java.security.Permission that governs read and write access to system properties with System.getProperty() and System.setProperty(). A PropertyPermission object has a name, or target, and a comma-separated list of actions. The name of the permission is the name of the property of interest. The action string can be "read" for getProperty() access, "write" for setProperty() access, or "read,write" for both types of access. PropertyPermission extends java.security.BasicPermission, so the name of the property supports simple wildcards. The name "*" represents any property name. If a name ends with ".*", it represents any property names that share the specified prefix. For example, the name "java.*" represents "java.version", "java.vendor", "java.vendor.url", and all other properties that begin with "java".

Granting access to system properties is not overtly dangerous, but caution is still necessary. Some properties, such as "user.home", reveal details about the host system that malicious code can use to mount an attack. Programmers writing system-level code and system administrators configuring security policies may need to use this class, but applications never need to use it.

Hierarchy: Object-->java.security.Permission(java.security.Guard,Serializable)-->java.security.BasicPermission(Serializable)-->PropertyPermission

PropertyResourceBundle	Java 1.1
java.util	PJ1.1

This class is a concrete subclass of ResourceBundle. It reads a Properties file from a specified InputStream and implements the ResourceBundle API for looking up named resources from the resulting Properties object. A Properties file contains lines of the form:

name=value

Each such line defines a named property with the specified String value. Although you can instantiate a PropertyResourceBundle yourself, it is more common to simply define a Properties file and then allow ResourceBundle.getBundle() to look up that file and return the necessary PropertyResourceBundle object. See also Properties and ResourceBundle.

Hierarchy: Object-->ResourceBundle-->PropertyResourceBundle

Random	Java 1.0
java.util	serializable PJ1.1

This class implements a pseudo-random number generator suitable for games and similar applications. If you need a cryptographic-strength source of pseudo-randomness, see java.security.SecureRandom. nextDouble() and nextFloat() return a value between 0.0 and 1.0. nextLong() and the no-argument version of nextInt() return long and int values distributed across the range of those data types. In Java 1.2, if you pass an argument to nextInt(), it returns a value between zero (inclusive) and the specified number (exclusive). nextGaussian() returns pseudo-random floating-point values with a Gaussian distribution; the mean of the values is 0.0 and the standard deviation is 1.0. nextBoolean() returns a pseudo-random boolean value, and nextBytes() fills in the specified byte array with pseudo-random bytes. You can use the setSeed() method or the optional constructor argument to initialize the pseudo-random number generator with some variable seed value other than the current time (the default) or with a constant to ensure a repeatable sequence of pseudo-randomness.

Hierarchy: Object-->Random(Serializable)

Subclasses: java.security.SecureRandom

Passed To: java.math.BigInteger.BigInteger(), Collections.shuffle()

ResourceBundle	Java 1.1
java.util	PJ1.1

This abstract class allows subclasses to define sets of localized resources that can then be dynamically loaded as needed by internationalized programs. Such resources may include user-visible text and images that appear in an application, as well as more complex things such as Menu objects. Use getBundle() to load a ResourceBundle subclass that is appropriate for the default or specified locale. Use getObject(), getString(), and getStringArray() to look up a named resource in a bundle. To define a bundle, provide implementations of handleGetObject() and getKeys(). It is often easier, however, to subclass ListResourceBundle or provide a Properties file that is used by PropertyResourceBundle. The name of any localized ResourceBundle class you define should include the locale language code, and, optionally, the locale country code.

Subclasses: ListResourceBundle, PropertyResourceBundle

Passed To: java.awt.ComponentOrientation.getOrientation(), java.awt.Window.applyResourceBundle(), ResourceBundle.setParent()

Returned By: ResourceBundle.getBundle()

Type Of: ResourceBundle.parent