archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 23:34:52 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

8187443: Forest Consolidation: Move files to unified layout

Browse source 
Reviewed-by: darcy, ihse
This commit is contained in:
Erik Joelsson 2017-09-12 19:03:39 +02:00
parent 270fe13182
commit 3789983e89
56923 changed files with 3 additions and 15727 deletions
Download patch file Download diff file Expand all files Collapse all files

395
src/java.base/share/classes/java/util/doc-files/coll-designfaq.html Normal file
View file

@ -0,0 +1,395 @@
<!DOCTYPE html>
<!--
Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the LICENSE file that accompanied this code.
This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).
You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->
<html lang="en-US">
<head>
<title>Java Collections API Design FAQ</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<h2>Java Collections API Design FAQ</h2>
<!-- Body text begins here -->
<hr>
This document answers frequently asked questions concerning the
design of the Java collections framework. It is derived from the
large volume of traffic on the collections-comments alias. It
serves as a design rationale for the collections framework.
<h3>Core Interfaces - General Questions</h3>
<ol>
<li><a href="#a1"><b>Why don't you support immutability directly in
the core collection interfaces so that you can do away with
<em>optional operations</em> (and
UnsupportedOperationException)?</b></a></li>
<li><a href="#a2"><b>Won't programmers have to surround any code
that calls optional operations with a try-catch clause in case they
throw an UnsupportedOperationException?</b></a></li>
<li><a href="#a3"><b>Why isn't there a core interface for "bags"
(AKA multisets)?</b></a></li>
<li><a href="#a28"><b>Why didn't you use "Beans-style names" for
consistency?</b></a></li>
</ol>
<h3>Collection Interface</h3>
<ol>
<li><a href="#a5"><b>Why doesn't Collection extend Cloneable and
Serializable?</b></a></li>
<li><a href="#a6"><b>Why don't you provide an "apply" method in
Collection to apply a given method ("upcall") to all the elements
of the Collection?</b></a></li>
<li><a href="#a7"><b>Why didn't you provide a "Predicate" interface,
and related methods (e.g., a method to find the first element in
the Collection satisfying the predicate)?</b></a></li>
<li><a href="#a8"><b>Why don't you provide a form of the addAll
method that takes an Enumeration (or an Iterator)?</b></a></li>
<li><a href="#a9"><b>Why don't the concrete implementations in the
JDK have Enumeration (or Iterator) constructors?</b></a></li>
<li><a href="#a10"><b>Why don't you provide an Iterator.add
method?</b></a></li>
</ol>
<h3>List Interface</h3>
<ol>
<li><a href="#a11"><b>Why don't you rename the List interface to
Sequence; doesn't "list" generally suggest "linked list"? Also,
doesn't it conflict with java.awt.List?</b></a></li>
<li><a href="#a12"><b>Why don't you rename List's set method to
replace, to avoid confusion with Set.</b></a></li>
</ol>
<h3>Map Interface</h3>
<ol>
<li><a href="#a14"><b>Why doesn't Map extend
Collection?</b></a></li>
</ol>
<h3>Iterator Interface</h3>
<ol>
<li><a href="#a18"><b>Why doesn't Iterator extend
Enumeration?</b></a></li>
<li><a href="#a19"><b>Why don't you provide an Iterator.peek method
that allows you to look at the next element in an iteration without
advancing the iterator?</b></a></li>
</ol>
<h3>Miscellaneous</h3>
<ol>
<li><a href="#a23"><b>Why did you write a new collections framework
instead of adopting JGL (a preexisting collections package from
ObjectSpace, Inc.) into the JDK?</b></a></li>
<li><a href="#a26"><b>Why don't you eliminate all of the methods and
classes that return "views" (Collections backed by other
collection-like objects). This would greatly reduce
aliasing.</b></a></li>
<li><a href="#a27"><b>Why don't you provide for "observable"
collections that send out Events when they're
modified?</b></a></li>
</ol>
<hr>
<h3>Core Interfaces - General Questions</h3>
<ol>
<li><a id="a1"><b>Why don't you support immutability
directly in the core collection interfaces so that you can do away
with <em>optional operations</em> (and
UnsupportedOperationException)?</b></a>
<p>This is the most controversial design decision in the whole API.
Clearly, static (compile time) type checking is highly desirable,
and is the norm in Java. We would have supported it if we believed
it were feasible. Unfortunately, attempts to achieve this goal
cause an explosion in the size of the interface hierarchy, and do
not succeed in eliminating the need for runtime exceptions (though
they reduce it substantially).</p>
<p>Doug Lea, who wrote a popular Java collections package that did
reflect mutability distinctions in its interface hierarchy, no
longer believes it is a viable approach, based on user experience
with his collections package. In his words (from personal
correspondence) "Much as it pains me to say it, strong static
typing does not work for collection interfaces in Java."</p>
<p>To illustrate the problem in gory detail, suppose you want to
add the notion of modifiability to the Hierarchy. You need four new
interfaces: ModifiableCollection, ModifiableSet, ModifiableList,
and ModifiableMap. What was previously a simple hierarchy is now a
messy heterarchy. Also, you need a new Iterator interface for use
with unmodifiable Collections, that does not contain the remove
operation. Now can you do away with UnsupportedOperationException?
Unfortunately not.</p>
<p>Consider arrays. They implement most of the List operations, but
not remove and add. They are "fixed-size" Lists. If you want to
capture this notion in the hierarchy, you have to add two new
interfaces: VariableSizeList and VariableSizeMap. You don't have to
add VariableSizeCollection and VariableSizeSet, because they'd be
identical to ModifiableCollection and ModifiableSet, but you might
choose to add them anyway for consistency's sake. Also, you need a
new variety of ListIterator that doesn't support the add and remove
operations, to go along with unmodifiable List. Now we're up to ten
or twelve interfaces, plus two new Iterator interfaces, instead of
our original four. Are we done? No.</p>
<p>Consider logs (such as error logs, audit logs and journals for
recoverable data objects). They are natural append-only sequences,
that support all of the List operations except for remove and set
(replace). They require a new core interface, and a new
iterator.</p>
<p>And what about immutable Collections, as opposed to unmodifiable
ones? (i.e., Collections that cannot be changed by the client AND
will never change for any other reason). Many argue that this is
the most important distinction of all, because it allows multiple
threads to access a collection concurrently without the need for
synchronization. Adding this support to the type hierarchy requires
four more interfaces.</p>
<p>Now we're up to twenty or so interfaces and five iterators, and
it's almost certain that there are still collections arising in
practice that don't fit cleanly into any of the interfaces. For
example, the <em>collection-views</em> returned by Map are natural
delete-only collections. Also, there are collections that will
reject certain elements on the basis of their value, so we still
haven't done away with runtime exceptions.</p>
<p>When all was said and done, we felt that it was a sound
engineering compromise to sidestep the whole issue by providing a
very small set of core interfaces that can throw a runtime
exception.</p>
</li>
<li><a id="a2"><b>Won't programmers have to surround any
code that calls optional operations with a try-catch clause in case
they throw an UnsupportedOperationException?</b></a>
<p>It was never our intention that programs should catch these
exceptions: that's why they're unchecked (runtime) exceptions. They
should only arise as a result of programming errors, in which case,
your program will halt due to the uncaught exception.</p>
</li>
<li><a id="a3"><b>Why isn't there a core interface for
"bags" (AKA multisets)?</b></a>
<p>The Collection interface provides this functionality. We are not
providing any public implementations of this interface, as we think
that it wouldn't be used frequently enough to "pull its weight." We
occasionally return such Collections, which are implemented easily
atop AbstractCollection (for example, the Collection returned by
Map.values).</p>
</li>
<li><a id="a28"><b>Why didn't you use "Beans-style
names" for consistency?</b></a>
<p>While the names of the new collections methods do not adhere to
the "Beans naming conventions", we believe that they are
reasonable, consistent and appropriate to their purpose. It should
be remembered that the Beans naming conventions do not apply to the
JDK as a whole; the AWT did adopt these conventions, but that
decision was somewhat controversial. We suspect that the
collections APIs will be used quite pervasively, often with
multiple method calls on a single line of code, so it is important
that the names be short. Consider, for example, the Iterator
methods. Currently, a loop over a collection looks like this:</p>
<pre>
for (Iterator i = c.iterator(); i.hasNext(); )
System.out.println(i.next());
</pre>
Everything fits neatly on one line, even if the Collection name is
a long expression. If we named the methods "getIterator",
"hasNextElement" and "getNextElement", this would no longer be the
case. Thus, we adopted the "traditional" JDK style rather than the
Beans style.</li>
</ol>
<hr>
<h3>Collection Interface</h3>
<ol>
<li><a id="a5"><b>Why doesn't Collection extend Cloneable
and Serializable?</b></a>
<p>Many Collection implementations (including all of the ones
provided by the JDK) will have a public clone method, but it would
be mistake to require it of all Collections. For example, what does
it mean to clone a Collection that's backed by a terabyte SQL
database? Should the method call cause the company to requisition a
new disk farm? Similar arguments hold for serializable.</p>
<p>If the client doesn't know the actual type of a Collection, it's
much more flexible and less error prone to have the client decide
what type of Collection is desired, create an empty Collection of
this type, and use the addAll method to copy the elements of the
original collection into the new one.</p>
</li>
<li><a id="a6"><b>Why don't you provide an "apply" method
in Collection to apply a given method ("upcall") to all the
elements of the Collection?</b></a>
<p>This is what is referred to as an "Internal Iterator" in the
"Design Patterns" book (Gamma et al.). We considered providing it,
but decided not to as it seems somewhat redundant to support
internal and external iterators, and Java already has a precedent
for external iterators (with Enumerations). The "throw weight" of
this functionality is increased by the fact that it requires a
public interface to describe upcalls.</p>
</li>
<li><a id="a7"><b>Why didn't you provide a "Predicate"
interface, and related methods (e.g., a method to find the first
element in the Collection satisfying the predicate)?</b></a>
<p>It's easy to implement this functionality atop Iterators, and
the resulting code may actually look cleaner as the user can inline
the predicate. Thus, it's not clear whether this facility pulls its
weight. It could be added to the Collections class at a later date
(implemented atop Iterator), if it's deemed useful.</p>
</li>
<li><a id="a8"><b>Why don't you provide a form of the
addAll method that takes an Enumeration (or an Iterator)?</b></a>
<p>Because we don't believe in using Enumerations (or Iterators) as
"poor man's collections." This was occasionally done in prior
releases, but now that we have the Collection interface, it is the
preferred way to pass around abstract collections of objects.</p>
</li>
<li><a id="a9"><b>Why don't the concrete implementations
in the JDK have Enumeration (or Iterator) constructors?</b></a>
<p>Again, this is an instance of an Enumeration serving as a "poor
man's collection" and we're trying to discourage that. Note
however, that we strongly suggest that all concrete implementations
should have constructors that take a Collection (and create a new
Collection with the same elements).</p>
</li>
<li><a id="a10"><b>Why don't you provide an Iterator.add
method?</b></a>
<p>The semantics are unclear, given that the contract for Iterator
makes no guarantees about the order of iteration. Note, however,
that ListIterator does provide an add operation, as it does
guarantee the order of the iteration.</p>
</li>
</ol>
<hr>
<h3>List Interface</h3>
<ol>
<li><a id="a11"><b>Why don't you rename the List
interface to Sequence; doesn't "list" generally suggest "linked
list"? Also, doesn't it conflict with java.awt.List?</b></a>
<p>People were evenly divided as to whether List suggests linked
lists. Given the implementation naming convention,
&lt;<em>Implementation</em>&gt;&lt;<em>Interface</em>&gt;, there
was a strong desire to keep the core interface names short. Also,
several existing names (AbstractSequentialList, LinkedList) would
have been decidedly worse if we changed List to Sequence. The
naming conflict can be dealt with by the following incantation:</p>
<pre>
import java.util.*;
import java.awt.*;
import java.util.List; // Dictates interpretation of "List"
</pre></li>
<li><a id="a12"><b>Why don't you rename List's set
method to replace, to avoid confusion with Set.</b></a>
<p>It was decided that the "set/get" naming convention was strongly
enough enshrined in the language that we'd stick with it.</p>
</li>
</ol>
<hr>
<h3>Map Interface</h3>
<ol>
<li><a id="a14"><b>Why doesn't Map extend
Collection?</b></a>
<p>This was by design. We feel that mappings are not collections
and collections are not mappings. Thus, it makes little sense for
Map to extend the Collection interface (or vice versa).</p>
<p>If a Map is a Collection, what are the elements? The only
reasonable answer is "Key-value pairs", but this provides a very
limited (and not particularly useful) Map abstraction. You can't
ask what value a given key maps to, nor can you delete the entry
for a given key without knowing what value it maps to.</p>
<p>Collection could be made to extend Map, but this raises the
question: what are the keys? There's no really satisfactory answer,
and forcing one leads to an unnatural interface.</p>
<p>Maps can be <em>viewed</em> as Collections (of keys, values, or
pairs), and this fact is reflected in the three "Collection view
operations" on Maps (keySet, entrySet, and values). While it is, in
principle, possible to view a List as a Map mapping indices to
elements, this has the nasty property that deleting an element from
the List changes the Key associated with every element before the
deleted element. That's why we don't have a map view operation on
Lists.</p>
</li>
</ol>
<hr>
<h3>Iterator Interface</h3>
<ol>
<li><a id="a18"><b>Why doesn't Iterator extend
Enumeration?</b></a>
<p>We view the method names for Enumeration as unfortunate. They're
very long, and very frequently used. Given that we were adding a
method and creating a whole new framework, we felt that it would be
foolish not to take advantage of the opportunity to improve the
names. Of course we could support the new and old names in
Iterator, but it doesn't seem worthwhile.</p>
</li>
<li><a id="a19"><b>Why don't you provide an
Iterator.peek method that allows you to look at the next element in
an iteration without advancing the iterator?</b></a>
<p>It can be implemented atop the current Iterators (a similar
pattern to java.io.PushbackInputStream). We believe that its use
would be rare enough that it isn't worth including in the interface
that everyone has to implement.</p>
</li>
</ol>
<hr>
<h3>Miscellaneous</h3>
<ol>
<li><a id="a23"><b>Why did you write a new collections
framework instead of adopting JGL (a preexisting collections
package from ObjectSpace, Inc.) into the JDK?</b></a>
<p>If you examine the goals for our Collections framework (in the
Overview), you'll see that we are not really "playing in the same
space" as JGL. Quoting from the "Design Goals" Section of the Java
Collections Overview: "Our main design goal was to produce an API
that was reasonably small, both in size, and (more importantly) in
'conceptual weight.'"</p>
<p>JGL consists of approximately 130 classes and interfaces; its
main goal was consistency with the C++ Standard Template Library
(STL). This was <em>not</em> one of our goals. Java has
traditionally stayed away from C++'s more complex features (e.g.,
multiple inheritance, operator overloading). Our entire framework,
including all infrastructure, contains approximately 25 classes and
interfaces.</p>
<p>While this may cause some discomfort for some C++ programmers,
we feel that it will be good for Java in the long run. As the Java
libraries mature, they inevitably grow, but we are trying as hard
as we can to keep them small and manageable, so that Java continues
to be an easy, fun language to learn and to use.</p>
</li>
<li><a id="a26"><b>Why don't you eliminate all of the
methods and classes that return "views" (Collections backed by
other collection-like objects). This would greatly reduce
aliasing.</b></a>
<p>Given that we provide core collection interfaces behind which
programmers can "hide" their own implementations, there will be
aliased collections whether the JDK provides them or not.
Eliminating all views from the JDK would greatly increase the cost
of common operations like making a Collection out of an array, and
would do away with many useful facilities (like synchronizing
wrappers). One view that we see as being particularly useful is
<a href=
"../List.html#subList-int-int-">List.subList</a>.
The existence of this method means that people who write methods
taking List on input do not have to write secondary forms taking an
offset and a length (as they do for arrays).</p>
</li>
<li><a id="a27"><b>Why don't you provide for
"observable" collections that send out Events when they're
modified?</b></a>
<p>Primarily, resource constraints. If we're going to commit to
such an API, it has to be something that works for everyone, that
we can live with for the long haul. We may provide such a facility
some day. In the meantime, it's not difficult to implement such a
facility on top of the public APIs.</p>
</li>
</ol>
<hr>
<p style="font-size:smaller">
Copyright &copy; 1998, 2017, Oracle and/or its affiliates. 500 Oracle Parkway<br>
Redwood Shores, CA 94065 USA. All rights reserved.</p>
<!-- Body text ends here -->
</body>
</html>

77
src/java.base/share/classes/java/util/doc-files/coll-index.html Normal file
View file

@ -0,0 +1,77 @@
<!DOCTYPE html>
<!--
Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the LICENSE file that accompanied this code.
This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).
You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->
<html lang="en-US">
<head>
<meta name="generator" content="HTML Tidy, see www.w3.org" />
<title>The Collections Framework</title>
<style type="text/css">
/*<![CDATA[*/
ul li, ul ul li {font-weight: normal;}
pre {margin-left: 42pt;}
a {font-weight: bold;}
/*]]>*/
</style>
</head>
<body>
<h1>The Collections Framework</h1>
<!-- Body text begins here -->
<p>The collections framework is a unified architecture for
representing and manipulating collections, enabling them to be
manipulated independently of the details of their representation.
It reduces programming effort while increasing performance. It
enables interoperability among unrelated APIs, reduces effort in
designing and learning new APIs, and fosters software reuse. The
framework is based on more than a dozen collection interfaces. It
includes implementations of these interfaces and algorithms to
manipulate them.</p>
<p>The documents in this section are non-normative portions of
the Java&trade; Platform, Standard Edition API Specification.</p>
<ul>
<li><b><a href="coll-overview.html">Overview</a></b> - An overview of
the collections framework.</li>
</ul>
<ul>
<li><b><a href="coll-reference.html">Annotated API Outline</a></b> - An
annotated outline of the classes and interfaces comprising the
collections framework, with links into the API Specification.</li>
</ul>
<ul>
<li><b><a href="coll-designfaq.html">Design FAQ</a></b> - Answers to
frequently asked questions (FAQ) about the design of the
collections framework.</li>
</ul>
<hr>
<p style="font-size:smaller">
Copyright &copy; 1998, 2017, Oracle and/or its affiliates. 500 Oracle Parkway<br />
Redwood Shores, CA 94065 USA. All rights reserved.</p>
<!-- Body text ends here -->
</body>
</html>

367
src/java.base/share/classes/java/util/doc-files/coll-overview.html Normal file
View file

@ -0,0 +1,367 @@
<!DOCTYPE html>
<!--
Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the LICENSE file that accompanied this code.
This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).
You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->
<html lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Collections Framework Overview</title>
<style>
#impls {
border: 1px solid black;
border-collapse: collapse;
margin: 0 auto;
}
#impls caption {
font-weight: bold;
font-size: smaller;
}
#impls, #impls th, #impls td {
border: 1px solid black;
padding: 2px .5em;
}
#impls tbody th {
font-weight: normal;
text-align:left;
}
</style>
</head>
<body>
<h1>Collections Framework Overview</h1>
<!-- Body text begins here -->
<h2>Introduction</h2>
The Java platform includes a <i>collections framework</i>. A
<i>collection</i> is an object that represents a group of objects
(such as the classic <a href="../ArrayList.html">ArrayList</a> class).
A collections framework is a unified architecture for representing
and manipulating collections, enabling collections to be
manipulated independently of implementation details.
<p>The primary advantages of a collections framework are that
it:</p>
<ul>
<li><strong>Reduces programming effort</strong> by providing data
structures and algorithms so you don't have to write them
yourself.</li>
<li><strong>Increases performance</strong> by providing
high-performance implementations of data structures and algorithms.
Because the various implementations of each interface are
interchangeable, programs can be tuned by switching
implementations.</li>
<li><strong>Provides interoperability between unrelated
APIs</strong> by establishing a common language to pass collections
back and forth.</li>
<li><strong>Reduces the effort required to learn APIs</strong> by
requiring you to learn multiple ad hoc collection APIs.</li>
<li><strong>Reduces the effort required to design and implement
APIs</strong> by not requiring you to produce ad hoc collections
APIs.</li>
<li><strong>Fosters software reuse</strong> by providing a standard
interface for collections and algorithms with which to manipulate
them.</li>
</ul>
<p>The collections framework consists of:</p>
<ul>
<li><strong>Collection interfaces</strong>. Represent different
types of collections, such as sets, lists, and maps. These
interfaces form the basis of the framework.</li>
<li><strong>General-purpose implementations</strong>. Primary
implementations of the collection interfaces.</li>
<li><strong>Legacy implementations</strong>. The collection classes
from earlier releases, <code>Vector</code> and <code>Hashtable</code>, were
retrofitted to implement the collection interfaces.</li>
<li><strong>Special-purpose implementations</strong>.
Implementations designed for use in special situations. These
implementations display nonstandard performance characteristics,
usage restrictions, or behavior.</li>
<li><strong>Concurrent implementations</strong>. Implementations
designed for highly concurrent use.</li>
<li><strong>Wrapper implementations</strong>. Add functionality,
such as synchronization, to other implementations.</li>
<li><strong>Convenience implementations</strong>. High-performance
"mini-implementations" of the collection interfaces.</li>
<li><strong>Abstract implementations</strong>. Partial
implementations of the collection interfaces to facilitate custom
implementations.</li>
<li><strong>Algorithms</strong>. Static methods that perform useful
functions on collections, such as sorting a list.</li>
<li><strong>Infrastructure</strong>. Interfaces that provide
essential support for the collection interfaces.</li>
<li><strong>Array Utilities</strong>. Utility functions for arrays
of primitive types and reference objects. Not, strictly speaking, a
part of the collections framework, this feature was added to the
Java platform at the same time as the collections framework and
relies on some of the same infrastructure.</li>
</ul>
<hr />
<h2>Collection Interfaces</h2>
<p>The <i>collection interfaces</i> are divided into two groups.
The most basic interface, <code><a href=
"../Collection.html">java.util.Collection</a></code>,
has the following descendants:</p>
<ul>
<li><code><a href=
"../Set.html">java.util.Set</a></code></li>
<li><code><a href=
"../SortedSet.html">java.util.SortedSet</a></code></li>
<li><code><a href=
"../NavigableSet.html">java.util.NavigableSet</a></code></li>
<li><code><a href=
"../Queue.html">java.util.Queue</a></code></li>
<li><code><a href=
"../concurrent/BlockingQueue.html">java.util.concurrent.BlockingQueue</a></code></li>
<li><code><a href=
"../concurrent/TransferQueue.html">java.util.concurrent.TransferQueue</a></code></li>
<li><code><a href=
"../Deque.html">java.util.Deque</a></code></li>
<li><code><a href=
"../concurrent/BlockingDeque.html">java.util.concurrent.BlockingDeque</a></code></li>
</ul>
<p>The other collection interfaces are based on <code><a href=
"../Map.html">java.util.Map</a></code> and are
not true collections. However, these interfaces contain
<i>collection-view</i> operations, which enable them to be
manipulated as collections. <code>Map</code> has the following
offspring:</p>
<ul>
<li><code><a href=
"../SortedMap.html">java.util.SortedMap</a></code></li>
<li><code><a href=
"../NavigableMap.html">java.util.NavigableMap</a></code></li>
<li><code><a href=
"../concurrent/ConcurrentMap.html">java.util.concurrent.ConcurrentMap</a></code></li>
<li><code><a href=
"../concurrent/ConcurrentNavigableMap.html">java.util.concurrent.ConcurrentNavigableMap</a></code></li>
</ul>
<p>Many of the modification methods in the collection interfaces
are labeled <i>optional</i>. Implementations are permitted to not
perform one or more of these operations, throwing a runtime
exception (<code>UnsupportedOperationException</code>) if they are
attempted. The documentation for each implementation must specify
which optional operations are supported. Several terms are
introduced to aid in this specification:</p>
<ul>
<li>Collections that do not support modification operations (such
as <code>add</code>, <code>remove</code> and <code>clear</code>) are referred
to as <i>unmodifiable</i>. Collections that are not unmodifiable
are <i>modifiable.</i></li>
<li>Collections that additionally guarantee that no change in the
<code>Collection</code> object will be visible are referred to as
<i>immutable</i>. Collections that are not immutable are
<i>mutable</i>.</li>
<li>Lists that guarantee that their size remains constant even
though the elements can change are referred to as
<i>fixed-size</i>. Lists that are not fixed-size are referred to as
<i>variable-size</i>.</li>
<li>Lists that support fast (generally constant time) indexed
element access are known as <i>random access</i> lists. Lists that
do not support fast indexed element access are known as
<i>sequential access</i> lists. The <code><a href=
"../RandomAccess.html">RandomAccess</a></code>
marker interface enables lists to advertise the fact that they
support random access. This enables generic algorithms to change
their behavior to provide good performance when applied to either
random or sequential access lists.</li>
</ul>
<p>Some implementations restrict what elements (or in the case of
<code>Maps</code>, keys and values) can be stored. Possible
restrictions include requiring elements to:</p>
<ul>
<li>Be of a particular type.</li>
<li>Be not null.</li>
<li>Obey some arbitrary predicate.</li>
</ul>
<p>Attempting to add an element that violates an implementation's
restrictions results in a runtime exception, typically a
<code>ClassCastException</code>, an <code>IllegalArgumentException</code>,
or a <code>NullPointerException</code>. Attempting to remove or test
for the presence of an element that violates an implementation's
restrictions can result in an exception. Some restricted
collections permit this usage.</p>
<hr>
<h2>Collection Implementations</h2>
<p>Classes that implement the collection interfaces typically have
names in the form of
&lt;<em>Implementation-style</em>&gt;&lt;<em>Interface</em>&gt;.
The general purpose implementations are summarized in the following
table:</p>
<table id="impls">
<caption>General purpose implementations</caption>
<thead>
<tr>
<th scope="col">Interface</th>
<th scope="col">Hash Table</th>
<th scope="col">Resizable Array</th>
<th scope="col">Balanced Tree</th>
<th scope="col">Linked List</th>
<th scope="col">Hash Table + Linked List</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row"><code>Set</code></th>
<td><a href="../HashSet.html"><code>HashSet</code></a></td>
<td>&nbsp;</td>
<td><a href="../TreeSet.html"><code>TreeSet</code></a></td>
<td>&nbsp;</td>
<td><a href=
"../LinkedHashSet.html"><code>LinkedHashSet</code></a></td>
</tr>
<tr>
<th scope="row"><code>List</code></th>
<td>&nbsp;</td>
<td><a href="../ArrayList.html"><code>ArrayList</code></a></td>
<td>&nbsp;</td>
<td><a href="../LinkedList.html"><code>LinkedList</code></a></td>
<td>&nbsp;</td>
</tr>
<tr>
<th scope="row"><code>Deque</code></th>
<td>&nbsp;</td>
<td><a href="../ArrayDeque.html"><code>ArrayDeque</code></a></td>
<td>&nbsp;</td>
<td><a href="../LinkedList.html"><code>LinkedList</code></a></td>
<td>&nbsp;</td>
</tr>
<tr>
<th scope="row"><code>Map</code></th>
<td><a href="../HashMap.html"><code>HashMap</code></a></td>
<td>&nbsp;</td>
<td><a href="../TreeMap.html"><code>TreeMap</code></a></td>
<td>&nbsp;</td>
<td><a href="../LinkedHashMap.html"><code>LinkedHashMap</code></a></td>
</tr>
</tbody>
</table>
<p>The general-purpose implementations support all of the
<i>optional operations</i> in the collection interfaces and have no
restrictions on the elements they may contain. They are
unsynchronized, but the <code>Collections</code> class contains static
factories called <a href=
"../Collections.html#synchronizedCollection-java.util.Collection-">
<em>synchronization wrappers</em></a> that can be used to add
synchronization to many unsynchronized collections. All of the new
implementations have <i>fail-fast iterators</i>, which detect
invalid concurrent modification, and fail quickly and cleanly
(rather than behaving erratically).</p>
<p>The <code>AbstractCollection</code>, <code>AbstractSet</code>,
<code>AbstractList</code>, <code>AbstractSequentialList</code> and
<code>AbstractMap</code> classes provide basic implementations of the
core collection interfaces, to minimize the effort required to
implement them. The API documentation for these classes describes
precisely how each method is implemented so the implementer knows
which methods must be overridden, given the performance of the
basic operations of a specific implementation.</p>
<hr>
<h2>Concurrent Collections</h2>
<p>Applications that use collections from more than one thread must
be carefully programmed. In general, this is known as <i>concurrent
programming</i>. The Java platform includes extensive support for
concurrent programming. See <a href=
"../concurrent/package-summary.html">Java Concurrency
Utilities</a> for details.</p>
<p>Collections are so frequently used that various concurrent
friendly interfaces and implementations of collections are included
in the APIs. These types go beyond the synchronization wrappers
discussed previously to provide features that are frequently needed
in concurrent programming.</p>
<p>These concurrent-aware interfaces are available:</p>
<ul>
<li><code><a href=
"../concurrent/BlockingQueue.html">BlockingQueue</a></code></li>
<li><code><a href=
"../concurrent/TransferQueue.html">TransferQueue</a></code></li>
<li><code><a href=
"../concurrent/BlockingDeque.html">BlockingDeque</a></code></li>
<li><code><a href=
"../concurrent/ConcurrentMap.html">ConcurrentMap</a></code></li>
<li><code><a href=
"../concurrent/ConcurrentNavigableMap.html">ConcurrentNavigableMap</a></code></li>
</ul>
<p>The following concurrent-aware implementation classes are
available. See the API documentation for the correct usage of these
implementations.</p>
<ul>
<li><code><a href=
"../concurrent/LinkedBlockingQueue.html">LinkedBlockingQueue</a></code></li>
<li><code><a href=
"../concurrent/ArrayBlockingQueue.html">ArrayBlockingQueue</a></code></li>
<li><code><a href=
"../concurrent/PriorityBlockingQueue.html">PriorityBlockingQueue</a></code></li>
<li><code><a href=
"../concurrent/DelayQueue.html">DelayQueue</a></code></li>
<li><code><a href=
"../concurrent/SynchronousQueue.html">SynchronousQueue</a></code></li>
<li><a href=
"../concurrent/LinkedBlockingDeque.html"><code>LinkedBlockingDeque</code></a></li>
<li><a href=
"../concurrent/LinkedTransferQueue.html"><code>LinkedTransferQueue</code></a></li>
<li><code><a href=
"../concurrent/CopyOnWriteArrayList.html">CopyOnWriteArrayList</a></code></li>
<li><code><a href=
"../concurrent/CopyOnWriteArraySet.html">CopyOnWriteArraySet</a></code></li>
<li><code><a href=
"../concurrent/ConcurrentSkipListSet.html">ConcurrentSkipListSet</a></code></li>
<li><code><a href=
"../concurrent/ConcurrentHashMap.html">ConcurrentHashMap</a></code></li>
<li><code><a href=
"../concurrent/ConcurrentSkipListMap.html">ConcurrentSkipListMap</a></code></li>
</ul>
<hr>
<h2>Design Goals</h2>
<p>The main design goal was to produce an API that was small in
size and, more importantly, in &quot;conceptual weight.&quot; It
was critical that the new functionality not seem too different to
current Java programmers; it had to augment current facilities,
rather than replace them. At the same time, the new API had to be
powerful enough to provide all the advantages described
previously.</p>
<p>To keep the number of core interfaces small, the interfaces do
not attempt to capture such subtle distinctions as mutability,
modifiability, and resizability. Instead, certain calls in the core
interfaces are <i>optional</i>, enabling implementations to throw
an <code>UnsupportedOperationException</code> to indicate that they do
not support a specified optional operation. Collection implementers
must clearly document which optional operations are supported by an
implementation.</p>
<p>To keep the number of methods in each core interface small, an
interface contains a method only if either:</p>
<ul>
<li>It is a truly <i>fundamental operation</i>: a basic operations
in terms of which others could be reasonably defined,</li>
<li>There is a compelling performance reason why an important
implementation would want to override it.</li>
</ul>
<p>It was critical that all reasonable representations of
collections interoperate well. This included arrays, which cannot
be made to implement the <code>Collection</code> interface directly
without changing the language. Thus, the framework includes methods
to enable collections to be moved into arrays, arrays to be viewed
as collections, and maps to be viewed as collections.</p>
<hr>
<p style="font-size:smaller">
Copyright &copy; 1998, 2017, Oracle and/or its affiliates. 500 Oracle Parkway<br>
Redwood Shores, CA 94065 USA. All rights reserved.</p>
<!-- Body text ends here -->
</body>
</html>

561
src/java.base/share/classes/java/util/doc-files/coll-reference.html Normal file
View file

@ -0,0 +1,561 @@
<!DOCTYPE html>
<!--
Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation. Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the LICENSE file that accompanied this code.
This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).
You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->
<html lang="en-US">
<head>
<title>Outline of the Collections Framework</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<h1>Outline of the Collections Framework</h1>
<!-- Body text begins here -->
The collections framework consists of:
<ul>
<li><strong>Collection interfaces</strong> - The primary means by
which collections are manipulated.
<ul>
<li><a href=
"../Collection.html"><strong>Collection</strong></a>
- A group of objects. No assumptions are made about the order of
the collection (if any) or whether it can contain duplicate
elements.</li>
<li><a href=
"../Set.html"><strong>Set</strong></a> - The
familiar set abstraction. No duplicate elements permitted. May or
may not be ordered. Extends the <code>Collection</code> interface.</li>
<li><a href=
"../List.html"><strong>List</strong></a> -
Ordered collection, also known as a <i>sequence</i>. Duplicates are
generally permitted. Allows positional access. Extends the
<code>Collection</code> interface.</li>
<li><a href=
"../Queue.html"><strong>Queue</strong></a> - A
collection designed for holding elements before processing. Besides
basic <code>Collection</code> operations, queues provide additional
insertion, extraction, and inspection operations.</li>
<li><a href=
"../Deque.html"><strong>Deque</strong></a> - A
<em>double ended queue</em>, supporting element insertion and
removal at both ends. Extends the <code>Queue</code> interface.</li>
<li><a href=
"../Map.html"><strong>Map</strong></a> - A
mapping from keys to values. Each key can map to one value.</li>
<li><a href=
"../SortedSet.html"><strong>SortedSet</strong></a>
- A set whose elements are automatically sorted, either in their
<i>natural ordering</i> (see the <a href=
"../../lang/Comparable.html"><code>Comparable</code></a>
interface) or by a <a href=
"../Comparator.html"><code>Comparator</code></a>
object provided when a <code>SortedSet</code> instance is created.
Extends the <code>Set</code> interface.</li>
<li><a href=
"../SortedMap.html"><strong>SortedMap</strong></a>
- A map whose mappings are automatically sorted by key, either
using the <i>natural ordering</i> of the keys or by a comparator
provided when a <code>SortedMap</code> instance is created. Extends the
<code>Map</code> interface.</li>
<li><a href=
"../NavigableSet.html"><strong>NavigableSet</strong></a>
- A <code>SortedSet</code> extended with navigation methods reporting
closest matches for given search targets. A <code>NavigableSet</code>
may be accessed and traversed in either ascending or descending
order.</li>
<li><a href=
"../NavigableMap.html"><strong>NavigableMap</strong></a>
- A <code>SortedMap</code> extended with navigation methods returning
the closest matches for given search targets. A
<code>NavigableMap</code> can be accessed and traversed in either
ascending or descending key order.</li>
<li><a href=
"../concurrent/BlockingQueue.html"><strong>BlockingQueue</strong></a>
- A <code>Queue</code> with operations that wait for the queue to
become nonempty when retrieving an element and that wait for space
to become available in the queue when storing an element. (This
interface is part of the <code><a href=
"../concurrent/package-summary.html">java.util.concurrent</a></code>
package.)</li>
<li><a href=
"../concurrent/TransferQueue.html"><strong>TransferQueue</strong></a>
- A <code>BlockingQueue</code> in which producers can wait for
consumers to receive elements. (This interface is part of the
<code><a href=
"../concurrent/package-summary.html">java.util.concurrent</a></code>
package.)</li>
<li><a href=
"../concurrent/BlockingDeque.html"><strong>BlockingDeque</strong></a>
- A <code>Deque</code> with operations that wait for the deque to
become nonempty when retrieving an element and wait for space to
become available in the deque when storing an element. Extends both
the <code>Deque</code> and <code>BlockingQueue</code> interfaces. (This
interface is part of the <code><a href=
"../concurrent/package-summary.html">java.util.concurrent</a></code>
package.)</li>
<li><a href=
"../concurrent/ConcurrentMap.html"><strong>ConcurrentMap</strong></a>
- A <code>Map</code> with atomic <code>putIfAbsent</code>, <code>remove</code>,
and <code>replace</code> methods. (This interface is part of the
<code>java.util.concurrent</code> package.)</li>
<li><a href=
"../concurrent/ConcurrentNavigableMap.html"><strong>
ConcurrentNavigableMap</strong></a> - A <code>ConcurrentMap</code> that
is also a <code>NavigableMap</code>.</li>
</ul>
</li>
<li><strong>General-purpose implementations</strong> - The primary
implementations of the collection interfaces.
<ul>
<li><strong><a href=
"../HashSet.html">HashSet</a></strong> - Hash
table implementation of the <code>Set</code> interface. The best
all-around implementation of the <code>Set</code> interface.</li>
<li><a href=
"../TreeSet.html"><strong>TreeSet</strong></a>
- Red-black tree implementation of the <code>NavigableSet</code>
interface.</li>
<li><strong><a href=
"../LinkedHashSet.html">LinkedHashSet</a></strong>
- Hash table and linked list implementation of the <code>Set</code>
interface. An insertion-ordered <code>Set</code> implementation that
runs nearly as fast as <code>HashSet</code>.</li>
<li><strong><a href=
"../ArrayList.html">ArrayList</a></strong> -
Resizable array implementation of the <code>List</code> interface (an
unsynchronized <code>Vector</code>). The best all-around implementation
of the <code>List</code> interface.</li>
<li><strong><a href=
"../ArrayDeque.html">ArrayDeque</a></strong> -
Efficient, resizable array implementation of the <code>Deque</code>
interface.</li>
<li><a href=
"../LinkedList.html"><strong>LinkedList</strong></a>
- Doubly-linked list implementation of the <code>List</code> interface.
Provides better performance than the <code>ArrayList</code>
implementation if elements are frequently inserted or deleted
within the list. Also implements the <code>Deque</code> interface. When
accessed through the <code>Queue</code> interface, <code>LinkedList</code>
acts as a FIFO queue.</li>
<li><strong><a href=
"../PriorityQueue.html">PriorityQueue</a></strong>
- Heap implementation of an unbounded priority queue.</li>
<li><strong><a href=
"../HashMap.html">HashMap</a></strong> - Hash
table implementation of the <code>Map</code> interface (an
unsynchronized <code>Hashtable</code> that supports <code>null</code> keys
and values). The best all-around implementation of the <code>Map</code>
interface.</li>
<li><a href=
"../TreeMap.html"><strong>TreeMap</strong></a>
Red-black tree implementation of the <code>NavigableMap</code>
interface.</li>
<li><strong><a href=
"../LinkedHashMap.html">LinkedHashMap</a></strong>
- Hash table and linked list implementation of the <code>Map</code>
interface. An insertion-ordered <code>Map</code> implementation that
runs nearly as fast as <code>HashMap</code>. Also useful for building
caches (see <a href=
"../LinkedHashMap.html#removeEldestEntry-java.util.Map.Entry-">
removeEldestEntry(Map.Entry)</a> ).</li>
</ul>
</li>
<li><strong>Wrapper implementations</strong> -
Functionality-enhancing implementations for use with other
implementations. Accessed solely through static factory methods.
<ul>
<li><a href=
"../Collections.html#unmodifiableCollection-java.util.Collection-">
<strong>Collections.unmodifiable<i>Interface</i></strong></a> -
Returns an unmodifiable view of a specified collection that throws
an <code>UnsupportedOperationException</code> if the user attempts to
modify it.</li>
<li><a href=
"../Collections.html#synchronizedCollection-java.util.Collection-"
id=
"synchWrappers"><strong>Collections.synchronized<i>Interface</i></strong></a>
- Returns a synchronized collection that is backed by the specified
(typically unsynchronized) collection. As long as all accesses to
the backing collection are through the returned collection, thread
safety is guaranteed.</li>
<li><a href=
"../Collections.html#checkedCollection-java.util.Collection-java.lang.Class-">
<strong>Collections.checked<i>Interface</i></strong></a> - Returns
a dynamically type-safe view of the specified collection, which
throws a <code>ClassCastException</code> if a client attempts to add an
element of the wrong type. The generics mechanism in the language
provides compile-time (static) type checking, but it is possible to
bypass this mechanism. Dynamically type-safe views eliminate this
possibility.</li>
</ul>
</li>
<li><strong>Adapter implementations</strong> - Implementations that
adapt one collections interface to another:
<ul>
<li><strong><a href=
"../Collections.html#newSetFromMap-java.util.Map-">
newSetFromMap(Map)</a></strong> - Creates a general-purpose
<code>Set</code> implementation from a general-purpose <code>Map</code>
implementation.</li>
<li><strong><a href=
"../Collections.html#asLifoQueue-java.util.Deque-">
asLifoQueue(Deque)</a></strong> - Returns a view of a
<code>Deque</code> as a Last In First Out (LIFO) <code>Queue</code>.</li>
</ul>
</li>
<li><strong>Convenience implementations</strong> - High-performance
"mini-implementations" of the collection interfaces.
<ul>
<li><a href=
"../Arrays.html#asList-T...-"><strong>Arrays.asList</strong></a>
- Enables an array to be viewed as a list.</li>
<li><strong><a href=
"../Collections.html#emptySet--">emptySet</a>,
<a href=
"../Collections.html#emptyList--">emptyList</a>
and <a href=
"../Collections.html#emptyMap--">emptyMap</a></strong>
- Return an immutable empty set, list, or map.</li>
<li><strong><a href=
"../Collections.html#singleton-java.lang.Object-">
singleton</a>, <a href=
"../Collections.html#singletonList-java.lang.Object-">
singletonList</a>, and <a href=
"../Collections.html#singletonMap-K-V-">singletonMap</a></strong>
- Return an immutable singleton set, list, or map, containing only
the specified object (or key-value mapping).</li>
<li><a href=
"../Collections.html#nCopies-int-T-"><strong>
nCopies</strong></a> - Returns an immutable list consisting of n
copies of a specified object.</li>
</ul>
</li>
<li><strong>Legacy implementations</strong> - Older collection
classes were retrofitted to implement the collection interfaces.
<ul>
<li><a href=
"../Vector.html"><strong>Vector</strong></a> -
Synchronized resizable array implementation of the <code>List</code>
interface with additional legacy methods.</li>
<li><a href=
"../Hashtable.html"><strong>Hashtable</strong></a>
- Synchronized hash table implementation of the <code>Map</code>
interface that does not allow <code>null</code> keys or values, plus
additional legacy methods.</li>
</ul>
</li>
<li><strong>Special-purpose implementations</strong>
<ul>
<li><strong><a href=
"../WeakHashMap.html">WeakHashMap</a></strong>
- An implementation of the <code>Map</code> interface that stores only
<a href="../../lang/ref/WeakReference.html"><i>weak
references</i></a> to its keys. Storing only weak references
enables key-value pairs to be garbage collected when the key is no
longer referenced outside of the <code>WeakHashMap</code>. This class
is the easiest way to use the power of weak references. It is
useful for implementing registry-like data structures, where the
utility of an entry vanishes when its key is no longer reachable by
any thread.</li>
<li><strong><a href=
"../IdentityHashMap.html">IdentityHashMap</a></strong>
- Identity-based <code>Map</code> implementation based on a hash table.
This class is useful for topology-preserving object graph
transformations (such as serialization or deep copying). To perform
these transformations, you must maintain an identity-based "node
table" that keeps track of which objects have already been seen.
Identity-based maps are also used to maintain
object-to-meta-information mappings in dynamic debuggers and
similar systems. Finally, identity-based maps are useful in
preventing "spoof attacks" resulting from intentionally perverse
equals methods. (<code>IdentityHashMap</code> never invokes the equals
method on its keys.) An added benefit of this implementation is
that it is fast.</li>
<li><strong><a href=
"../concurrent/CopyOnWriteArrayList.html">CopyOnWriteArrayList</a></strong>
- A <code>List</code> implementation backed by an copy-on-write array.
All mutative operations (such as <code>add</code>, <code>set</code>, and
<code>remove</code>) are implemented by making a new copy of the array.
No synchronization is necessary, even during iteration, and
iterators are guaranteed never to throw
<code>ConcurrentModificationException</code>. This implementation is
well-suited to maintaining event-handler lists (where change is
infrequent, and traversal is frequent and potentially
time-consuming).</li>
<li><strong><a href=
"../concurrent/CopyOnWriteArraySet.html">CopyOnWriteArraySet</a></strong>
- A <code>Set</code> implementation backed by a copy-on-write array.
This implementation is similar to <code>CopyOnWriteArrayList</code>.
Unlike most <code>Set</code> implementations, the <code>add</code>,
<code>remove</code>, and <code>contains</code> methods require time
proportional to the size of the set. This implementation is well
suited to maintaining event-handler lists that must prevent
duplicates.</li>
<li><strong><a href=
"../EnumSet.html">EnumSet</a></strong> - A
high-performance <code>Set</code> implementation backed by a bit
vector. All elements of each <code>EnumSet</code> instance must be
elements of a single enum type.</li>
<li><strong><a href=
"../EnumMap.html">EnumMap</a></strong> - A
high-performance <code>Map</code> implementation backed by an array.
All keys in each <code>EnumMap</code> instance must be elements of a
single enum type.</li>
</ul>
</li>
<li><strong>Concurrent implementations</strong> - These
implementations are part of <code>java.util.concurrent</code>.
<ul>
<li><strong><a href=
"../concurrent/ConcurrentLinkedQueue.html">ConcurrentLinkedQueue</a></strong>
- An unbounded first in, first out (FIFO) queue based on linked
nodes.</li>
<li><a href=
"../concurrent/LinkedBlockingQueue.html"><strong>
LinkedBlockingQueue</strong></a> - An optionally bounded FIFO
blocking queue backed by linked nodes.</li>
<li><a href=
"../concurrent/ArrayBlockingQueue.html"><strong>
ArrayBlockingQueue</strong></a> - A bounded FIFO blocking queue
backed by an array.</li>
<li><a href=
"../concurrent/PriorityBlockingQueue.html"><strong>
PriorityBlockingQueue</strong></a> - An unbounded blocking priority
queue backed by a priority heap.</li>
<li><a href=
"../concurrent/DelayQueue.html"><strong>DelayQueue</strong></a>
- A time-based scheduling queue backed by a priority heap.</li>
<li><a href=
"../concurrent/SynchronousQueue.html"><strong>SynchronousQueue</strong></a>
- A simple rendezvous mechanism that uses the
<code>BlockingQueue</code> interface.</li>
<li><a href=
"../concurrent/LinkedBlockingDeque.html"><strong>
LinkedBlockingDeque</strong></a> - An optionally bounded FIFO
blocking deque backed by linked nodes.</li>
<li><a href=
"../concurrent/LinkedTransferQueue.html"><strong>
LinkedTransferQueue</strong></a> - An unbounded
<code>TransferQueue</code> backed by linked nodes.</li>
<li><a href=
"../concurrent/ConcurrentHashMap.html"><strong>ConcurrentHashMap</strong></a>
- A highly concurrent, high-performance <code>ConcurrentMap</code>
implementation based on a hash table. This implementation never
blocks when performing retrievals and enables the client to select
the concurrency level for updates. It is intended as a drop-in
replacement for <code><a href=
"../Hashtable.html">Hashtable</a></code>. In
addition to implementing <code>ConcurrentMap</code>, it supports all of
the legacy methods of <code>Hashtable</code>.</li>
<li><a href=
"../concurrent/ConcurrentSkipListSet.html"><strong>
ConcurrentSkipListSet</strong></a> - Skips list implementation of
the <code>NavigableSet</code> interface.</li>
<li><a href=
"../concurrent/ConcurrentSkipListMap.html"><strong>
ConcurrentSkipListMap</strong></a> - Skips list implementation of
the <code>ConcurrentNavigableMap</code> interface.</li>
</ul>
</li>
<li><strong>Abstract implementations</strong> - Skeletal
implementations of the collection interfaces to facilitate custom
implementations.
<ul>
<li><a href=
"../AbstractCollection.html"><strong>AbstractCollection</strong></a>
- Skeletal <code>Collection</code> implementation that is neither a set
nor a list (such as a "bag" or multiset).</li>
<li><a href=
"../AbstractSet.html"><strong>AbstractSet</strong></a>
- Skeletal <code>Set</code> implementation.</li>
<li><a href=
"../AbstractList.html"><strong>AbstractList</strong></a>
- Skeletal <code>List</code> implementation backed by a random access
data store (such as an array).</li>
<li><a href=
"../AbstractSequentialList.html"><strong>AbstractSequentialList</strong></a>
- Skeletal <code>List</code> implementation backed by a sequential
access data store (such as a linked list).</li>
<li><a href=
"../AbstractQueue.html"><strong>AbstractQueue</strong></a>
- Skeletal <code>Queue</code> implementation.</li>
<li><a href=
"../AbstractMap.html"><strong>AbstractMap</strong></a>
- Skeletal <code>Map</code> implementation.</li>
</ul>
</li>
<li><strong>Algorithms</strong> - The <a href=
"../Collections.html"><strong>Collections</strong></a>
class contains these useful static methods.
<ul>
<li><strong><a href=
"../Collections.html#sort-java.util.List-">sort(List)</a></strong>
- Sorts a list using a merge sort algorithm, which provides average
case performance comparable to a high quality quicksort, guaranteed
O(n*log n) performance (unlike quicksort), and <em>stability</em>
(unlike quicksort). A stable sort is one that does not reorder
equal elements.</li>
<li><strong><a href=
"../Collections.html#binarySearch-java.util.List-T-">
binarySearch(List, Object)</a></strong> - Searches for an element
in an ordered list using the binary search algorithm.</li>
<li><strong><a href=
"../Collections.html#reverse-java.util.List-">reverse(List)</a></strong>
- Reverses the order of the elements in a list.</li>
<li><strong><a href=
"../Collections.html#shuffle-java.util.List-">shuffle(List)</a></strong>
- Randomly changes the order of the elements in a list.</li>
<li><strong><a href=
"../Collections.html#fill-java.util.List-T-">
fill(List, Object)</a></strong> - Overwrites every element in a
list with the specified value.</li>
<li><strong><a href=
"../Collections.html#copy-java.util.List-java.util.List-">
copy(List dest, List src)</a></strong> - Copies the source list
into the destination list.</li>
<li><strong><a href=
"../Collections.html#min-java.util.Collection-">
min(Collection)</a></strong> - Returns the minimum element in a
collection.</li>
<li><strong><a href=
"../Collections.html#max-java.util.Collection-">
max(Collection)</a></strong> - Returns the maximum element in a
collection.</li>
<li><strong><a href=
"../Collections.html#rotate-java.util.List-int-">
rotate(List list, int distance)</a></strong> - Rotates all of the
elements in the list by the specified distance.</li>
<li><strong><a href=
"../Collections.html#replaceAll-java.util.List-T-T-">
replaceAll(List list, Object oldVal, Object newVal)</a></strong> -
Replaces all occurrences of one specified value with another.</li>
<li><strong><a href=
"../Collections.html#indexOfSubList-java.util.List-java.util.List-">
indexOfSubList(List source, List target)</a></strong> - Returns the
index of the first sublist of source that is equal to target.</li>
<li><strong><a href=
"../Collections.html#lastIndexOfSubList-java.util.List-java.util.List-">
lastIndexOfSubList(List source, List target)</a></strong> - Returns
the index of the last sublist of source that is equal to
target.</li>
<li><strong><a href=
"../Collections.html#swap-java.util.List-int-int-">
swap(List, int, int)</a></strong> - Swaps the elements at the
specified positions in the specified list.</li>
<li><strong><a href=
"../Collections.html#frequency-java.util.Collection-java.lang.Object-">
frequency(Collection, Object)</a></strong> - Counts the number of
times the specified element occurs in the specified
collection.</li>
<li><strong><a href=
"../Collections.html#disjoint-java.util.Collection-java.util.Collection-">
disjoint(Collection, Collection)</a></strong> - Determines whether
two collections are disjoint, in other words, whether they contain
no elements in common.</li>
<li><strong><a href=
"../Collections.html#addAll-java.util.Collection-T...-">
addAll(Collection&lt;? super T&gt;, T...)</a></strong> - Adds all
of the elements in the specified array to the specified
collection.</li>
</ul>
</li>
<li><strong>Infrastructure</strong>
<ul>
<li><strong>Iterators</strong> - Similar to the familiar <a href=
"../Enumeration.html">Enumeration</a>
interface, but more powerful, and with improved method names.
<ul>
<li><a href=
"../Iterator.html"><strong>Iterator</strong></a>
- In addition to the functionality of the <code>Enumeration</code>
interface, enables the user to remove elements from the backing
collection with well-defined, useful semantics.</li>
<li><a href=
"../ListIterator.html"><strong>ListIterator</strong></a>
- Iterator for use with lists. In addition to the functionality of
the <code>Iterator</code> interface, supports bidirectional iteration,
element replacement, element insertion, and index retrieval.</li>
</ul>
</li>
<li><strong>Ordering</strong>
<ul>
<li><a href=
"../../lang/Comparable.html"><strong>Comparable</strong></a>
- Imparts a <i>natural ordering</i> to classes that implement it.
The natural ordering can be used to sort a list or maintain order
in a sorted set or map. Many classes were retrofitted to implement
this interface.</li>
<li><a href=
"../Comparator.html"><strong>Comparator</strong></a>
- Represents an order relation, which can be used to sort a list or
maintain order in a sorted set or map. Can override a type's
natural ordering or order objects of a type that does not implement
the <code>Comparable</code> interface.</li>
</ul>
</li>
<li><strong>Runtime exceptions</strong>
<ul>
<li><a href=
"../../lang/UnsupportedOperationException.html"><strong>
UnsupportedOperationException</strong></a> - Thrown by collections
if an unsupported optional operation is called.</li>
<li><a href=
"../ConcurrentModificationException.html"><strong>
ConcurrentModificationException</strong></a> - Thrown by iterators
and list iterators if the backing collection is changed
unexpectedly while the iteration is in progress. Also thrown by
<i>sublist</i> views of lists if the backing list is changed
unexpectedly.</li>
</ul>
</li>
<li><strong>Performance</strong>
<ul>
<li><strong><a href=
"../RandomAccess.html">RandomAccess</a></strong>
- Marker interface that lets <code>List</code> implementations indicate
that they support fast (generally constant time) random access.
This lets generic algorithms change their behavior to provide good
performance when applied to either random or sequential access
lists.</li>
</ul>
</li>
</ul>
</li>
<li><strong>Array Utilities</strong>
<ul>
<li><a href=
"../Arrays.html"><strong>Arrays</strong></a> -
Contains static methods to sort, search, compare, hash, copy,
resize, convert to <code>String</code>, and fill arrays of primitives
and objects.</li>
</ul>
</li>
</ul>
<hr>
<p style="font-size:smaller">
Copyright &copy; 1998, 2017, Oracle and/or its affiliates. 500 Oracle Parkway<br>
Redwood Shores, CA 94065 USA. All rights reserved.</p>
<!-- Body text ends here -->
</body>
</html>