8177788: migrate collections technotes/guides into java/util/doc-files
Reviewed-by: mchung, bchristi, martin
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/java.base/share/classes/java/util/doc-files/coll-designfaq.html Fri May 19 14:46:50 2017 -0700
@@ -0,0 +1,399 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<!--
+ 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" xmlns="http://www.w3.org/1999/xhtml" xml:lang=
+"en-US">
+<head>
+<title>Java Collections API Design FAQ</title>
+</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 size="3" noshade="noshade" />
+<h3>Core Interfaces - General Questions</h3>
+<ol>
+<li><a name="a1" 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 name="a2" 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 name="a3" 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 name="a28" 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 name="a5" 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 name="a6" 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 name="a7" 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 name="a8" 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 name="a9" 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 name="a10" 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 name="a11" 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,
+<<em>Implementation</em>><<em>Interface</em>>, 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 name="a12" 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 name="a14" 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 name="a18" 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 name="a19" 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 name="a23" 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 name="a26" 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 name="a27" 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 © 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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/java.base/share/classes/java/util/doc-files/coll-index.html Fri May 19 14:46:50 2017 -0700
@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<!--
+ 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" xmlns="http://www.w3.org/1999/xhtml" xml: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™ 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 © 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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/java.base/share/classes/java/util/doc-files/coll-overview.html Fri May 19 14:46:50 2017 -0700
@@ -0,0 +1,359 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<!--
+ 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" xmlns="http://www.w3.org/1999/xhtml" xml:lang=
+"en-US">
+<head>
+<title>Collections Framework Overview</title>
+</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, <tt>Vector</tt> and <tt>Hashtable</tt>, 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, <tt><a href=
+"../Collection.html">java.util.Collection</a></tt>,
+has the following descendants:</p>
+<ul>
+<li><tt><a href=
+"../Set.html">java.util.Set</a></tt></li>
+<li><tt><a href=
+"../SortedSet.html">java.util.SortedSet</a></tt></li>
+<li><tt><a href=
+"../NavigableSet.html">java.util.NavigableSet</a></tt></li>
+<li><tt><a href=
+"../Queue.html">java.util.Queue</a></tt></li>
+<li><tt><a href=
+"../concurrent/BlockingQueue.html">java.util.concurrent.BlockingQueue</a></tt></li>
+<li><tt><a href=
+"../concurrent/TransferQueue.html">java.util.concurrent.TransferQueue</a></tt></li>
+<li><tt><a href=
+"../Deque.html">java.util.Deque</a></tt></li>
+<li><tt><a href=
+"../concurrent/BlockingDeque.html">java.util.concurrent.BlockingDeque</a></tt></li>
+</ul>
+<p>The other collection interfaces are based on <tt><a href=
+"../Map.html">java.util.Map</a></tt> and are
+not true collections. However, these interfaces contain
+<i>collection-view</i> operations, which enable them to be
+manipulated as collections. <tt>Map</tt> has the following
+offspring:</p>
+<ul>
+<li><tt><a href=
+"../SortedMap.html">java.util.SortedMap</a></tt></li>
+<li><tt><a href=
+"../NavigableMap.html">java.util.NavigableMap</a></tt></li>
+<li><tt><a href=
+"../concurrent/ConcurrentMap.html">java.util.concurrent.ConcurrentMap</a></tt></li>
+<li><tt><a href=
+"../concurrent/ConcurrentNavigableMap.html">java.util.concurrent.ConcurrentNavigableMap</a></tt></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 (<tt>UnsupportedOperationException</tt>) 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 <tt>add</tt>, <tt>remove</tt> and <tt>clear</tt>) 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
+<tt>Collection</tt> 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 <tt><a href=
+"../RandomAccess.html">RandomAccess</a></tt>
+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
+<tt>Maps</tt>, 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
+<tt>ClassCastException</tt>, an <tt>IllegalArgumentException</tt>,
+or a <tt>NullPointerException</tt>. 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
+<<em>Implementation-style</em>><<em>Interface</em>>.
+The general purpose implementations are summarized in the following
+table:</p>
+<table border="2" summary=
+"general purpose implementations and interfaces" align="center">
+<thead>
+<tr>
+<th id="interfaces">Interface</th>
+<th id="hashtable">Hash Table</th>
+<th id="resizablearray">Resizable Array</th>
+<th id="balancedtree">Balanced Tree</th>
+<th id="linkedlist">Linked List</th>
+<th id="hashtableandlinkedlist">Hash Table + Linked List</th>
+</tr>
+<tr>
+<td headers="interfaces"><code>Set</code></td>
+<td headers="hashtable"><a href=
+"../HashSet.html"><tt>HashSet</tt></a></td>
+<td headers="resizablearray"> </td>
+<td headers="balancedtree"><a href=
+"../TreeSet.html"><tt>TreeSet</tt></a></td>
+<td headers="linkedlist"> </td>
+<td headers="hashtableandlinkedlist"><a href=
+"../LinkedHashSet.html"><tt>LinkedHashSet</tt></a></td>
+</tr>
+<tr>
+<td headers="interfaces"><code>List</code></td>
+<td headers="hashtable"> </td>
+<td headers="resizablearray"><a href=
+"../ArrayList.html"><tt>ArrayList</tt></a></td>
+<td headers="balancedtree"> </td>
+<td headers="linkedlist"><a href=
+"../LinkedList.html"><tt>LinkedList</tt></a></td>
+<td headers="hashtableandlinkedlist"> </td>
+</tr>
+<tr>
+<td headers="interfaces"><code>Deque</code></td>
+<td headers="hashtable"> </td>
+<td headers="resizablearray"><a href=
+"../ArrayDeque.html"><tt>ArrayDeque</tt></a></td>
+<td headers="balancedtree"> </td>
+<td headers="linkedlist"><a href=
+"../LinkedList.html"><tt>LinkedList</tt></a></td>
+<td headers="hashtableandlinkedlist"> </td>
+</tr>
+<tr>
+<td headers="interfaces"><code>Map</code></td>
+<td headers="hashtable"><a href=
+"../HashMap.html"><tt>HashMap</tt></a></td>
+<td headers="resizablearray"> </td>
+<td headers="balancedtree"><a href=
+"../TreeMap.html"><tt>TreeMap</tt></a></td>
+<td headers="linkedlist"> </td>
+<td headers="hashtableandlinkedlist"><a href=
+"../LinkedHashMap.html"><tt>LinkedHashMap</tt></a></td>
+</tr>
+</thead>
+</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 <tt>Collections</tt> 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 <tt>AbstractCollection</tt>, <tt>AbstractSet</tt>,
+<tt>AbstractList</tt>, <tt>AbstractSequentialList</tt> and
+<tt>AbstractMap</tt> 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><tt><a href=
+"../concurrent/BlockingQueue.html">BlockingQueue</a></tt></li>
+<li><tt><a href=
+"../concurrent/TransferQueue.html">TransferQueue</a></tt></li>
+<li><tt><a href=
+"../concurrent/BlockingDeque.html">BlockingDeque</a></tt></li>
+<li><tt><a href=
+"../concurrent/ConcurrentMap.html">ConcurrentMap</a></tt></li>
+<li><tt><a href=
+"../concurrent/ConcurrentNavigableMap.html">ConcurrentNavigableMap</a></tt></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><tt><a href=
+"../concurrent/LinkedBlockingQueue.html">LinkedBlockingQueue</a></tt></li>
+<li><tt><a href=
+"../concurrent/ArrayBlockingQueue.html">ArrayBlockingQueue</a></tt></li>
+<li><tt><a href=
+"../concurrent/PriorityBlockingQueue.html">PriorityBlockingQueue</a></tt></li>
+<li><tt><a href=
+"../concurrent/DelayQueue.html">DelayQueue</a></tt></li>
+<li><tt><a href=
+"../concurrent/SynchronousQueue.html">SynchronousQueue</a></tt></li>
+<li><a href=
+"../concurrent/LinkedBlockingDeque.html"><tt>LinkedBlockingDeque</tt></a></li>
+<li><a href=
+"../concurrent/LinkedTransferQueue.html"><tt>LinkedTransferQueue</tt></a></li>
+<li><tt><a href=
+"../concurrent/CopyOnWriteArrayList.html">CopyOnWriteArrayList</a></tt></li>
+<li><tt><a href=
+"../concurrent/CopyOnWriteArraySet.html">CopyOnWriteArraySet</a></tt></li>
+<li><tt><a href=
+"../concurrent/ConcurrentSkipListSet.html">ConcurrentSkipListSet</a></tt></li>
+<li><tt><a href=
+"../concurrent/ConcurrentHashMap.html">ConcurrentHashMap</a></tt></li>
+<li><tt><a href=
+"../concurrent/ConcurrentSkipListMap.html">ConcurrentSkipListMap</a></tt></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 "conceptual weight." 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 <tt>UnsupportedOperationException</tt> 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 <tt>Collection</tt> 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 © 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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/java.base/share/classes/java/util/doc-files/coll-reference.html Fri May 19 14:46:50 2017 -0700
@@ -0,0 +1,564 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<!--
+ 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" xmlns="http://www.w3.org/1999/xhtml" xml:lang=
+"en-US">
+<head>
+<title>Outline of the Collections Framework</title>
+</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 <tt>Collection</tt> 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
+<tt>Collection</tt> interface.</li>
+<li><a href=
+"../Queue.html"><strong>Queue</strong></a> - A
+collection designed for holding elements before processing. Besides
+basic <tt>Collection</tt> 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 <tt>Queue</tt> 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"><tt>Comparable</tt></a>
+interface) or by a <a href=
+"../Comparator.html"><tt>Comparator</tt></a>
+object provided when a <tt>SortedSet</tt> instance is created.
+Extends the <tt>Set</tt> 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 <tt>SortedMap</tt> instance is created. Extends the
+<tt>Map</tt> interface.</li>
+<li><a href=
+"../NavigableSet.html"><strong>NavigableSet</strong></a>
+- A <tt>SortedSet</tt> extended with navigation methods reporting
+closest matches for given search targets. A <tt>NavigableSet</tt>
+may be accessed and traversed in either ascending or descending
+order.</li>
+<li><a href=
+"../NavigableMap.html"><strong>NavigableMap</strong></a>
+- A <tt>SortedMap</tt> extended with navigation methods returning
+the closest matches for given search targets. A
+<tt>NavigableMap</tt> can be accessed and traversed in either
+ascending or descending key order.</li>
+<li><a href=
+"../concurrent/BlockingQueue.html"><strong>BlockingQueue</strong></a>
+- A <tt>Queue</tt> 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 <tt><a href=
+"../concurrent/package-summary.html">java.util.concurrent</a></tt>
+package.)</li>
+<li><a href=
+"../concurrent/TransferQueue.html"><strong>TransferQueue</strong></a>
+- A <tt>BlockingQueue</tt> in which producers can wait for
+consumers to receive elements. (This interface is part of the
+<tt><a href=
+"../concurrent/package-summary.html">java.util.concurrent</a></tt>
+package.)</li>
+<li><a href=
+"../concurrent/BlockingDeque.html"><strong>BlockingDeque</strong></a>
+- A <tt>Deque</tt> 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 <tt>Deque</tt> and <tt>BlockingQueue</tt> interfaces. (This
+interface is part of the <tt><a href=
+"../concurrent/package-summary.html">java.util.concurrent</a></tt>
+package.)</li>
+<li><a href=
+"../concurrent/ConcurrentMap.html"><strong>ConcurrentMap</strong></a>
+- A <tt>Map</tt> with atomic <tt>putIfAbsent</tt>, <tt>remove</tt>,
+and <tt>replace</tt> methods. (This interface is part of the
+<tt>java.util.concurrent</tt> package.)</li>
+<li><a href=
+"../concurrent/ConcurrentNavigableMap.html"><strong>
+ConcurrentNavigableMap</strong></a> - A <tt>ConcurrentMap</tt> that
+is also a <tt>NavigableMap</tt>.</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 <tt>Set</tt> interface. The best
+all-around implementation of the <tt>Set</tt> interface.</li>
+<li><a href=
+"../TreeSet.html"><strong>TreeSet</strong></a>
+- Red-black tree implementation of the <tt>NavigableSet</tt>
+interface.</li>
+<li><strong><a href=
+"../LinkedHashSet.html">LinkedHashSet</a></strong>
+- Hash table and linked list implementation of the <tt>Set</tt>
+interface. An insertion-ordered <tt>Set</tt> implementation that
+runs nearly as fast as <tt>HashSet</tt>.</li>
+<li><strong><a href=
+"../ArrayList.html">ArrayList</a></strong> -
+Resizable array implementation of the <tt>List</tt> interface (an
+unsynchronized <tt>Vector</tt>). The best all-around implementation
+of the <tt>List</tt> interface.</li>
+<li><strong><a href=
+"../ArrayDeque.html">ArrayDeque</a></strong> -
+Efficient, resizable array implementation of the <tt>Deque</tt>
+interface.</li>
+<li><a href=
+"../LinkedList.html"><strong>LinkedList</strong></a>
+- Doubly-linked list implementation of the <tt>List</tt> interface.
+Provides better performance than the <tt>ArrayList</tt>
+implementation if elements are frequently inserted or deleted
+within the list. Also implements the <tt>Deque</tt> interface. When
+accessed through the <tt>Queue</tt> interface, <tt>LinkedList</tt>
+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 <tt>Map</tt> interface (an
+unsynchronized <tt>Hashtable</tt> that supports <tt>null</tt> keys
+and values). The best all-around implementation of the <tt>Map</tt>
+interface.</li>
+<li><a href=
+"../TreeMap.html"><strong>TreeMap</strong></a>
+Red-black tree implementation of the <tt>NavigableMap</tt>
+interface.</li>
+<li><strong><a href=
+"../LinkedHashMap.html">LinkedHashMap</a></strong>
+- Hash table and linked list implementation of the <tt>Map</tt>
+interface. An insertion-ordered <tt>Map</tt> implementation that
+runs nearly as fast as <tt>HashMap</tt>. 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 <tt>UnsupportedOperationException</tt> if the user attempts to
+modify it.</li>
+<li><a name="synchWrappers" 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 <tt>ClassCastException</tt> 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
+<tt>Set</tt> implementation from a general-purpose <tt>Map</tt>
+implementation.</li>
+<li><strong><a href=
+"../Collections.html#asLifoQueue-java.util.Deque-">
+asLifoQueue(Deque)</a></strong> - Returns a view of a
+<tt>Deque</tt> as a Last In First Out (LIFO) <tt>Queue</tt>.</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 <tt>List</tt>
+interface with additional legacy methods.</li>
+<li><a href=
+"../Hashtable.html"><strong>Hashtable</strong></a>
+- Synchronized hash table implementation of the <tt>Map</tt>
+interface that does not allow <tt>null</tt> 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 <tt>Map</tt> 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 <tt>WeakHashMap</tt>. 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 <tt>Map</tt> 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. (<tt>IdentityHashMap</tt> 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 <tt>List</tt> implementation backed by an copy-on-write array.
+All mutative operations (such as <tt>add</tt>, <tt>set</tt>, and
+<tt>remove</tt>) are implemented by making a new copy of the array.
+No synchronization is necessary, even during iteration, and
+iterators are guaranteed never to throw
+<tt>ConcurrentModificationException</tt>. 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 <tt>Set</tt> implementation backed by a copy-on-write array.
+This implementation is similar to <tt>CopyOnWriteArrayList</tt>.
+Unlike most <tt>Set</tt> implementations, the <tt>add</tt>,
+<tt>remove</tt>, and <tt>contains</tt> 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 <tt>Set</tt> implementation backed by a bit
+vector. All elements of each <tt>EnumSet</tt> instance must be
+elements of a single enum type.</li>
+<li><strong><a href=
+"../EnumMap.html">EnumMap</a></strong> - A
+high-performance <tt>Map</tt> implementation backed by an array.
+All keys in each <tt>EnumMap</tt> instance must be elements of a
+single enum type.</li>
+</ul>
+</li>
+<li><strong>Concurrent implementations</strong> - These
+implementations are part of <tt>java.util.concurrent</tt>.
+<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
+<tt>BlockingQueue</tt> 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
+<tt>TransferQueue</tt> backed by linked nodes.</li>
+<li><a href=
+"../concurrent/ConcurrentHashMap.html"><strong>ConcurrentHashMap</strong></a>
+- A highly concurrent, high-performance <tt>ConcurrentMap</tt>
+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 <tt><a href=
+"../Hashtable.html">Hashtable</a></tt>. In
+addition to implementing <tt>ConcurrentMap</tt>, it supports all of
+the legacy methods of <tt>Hashtable</tt>.</li>
+<li><a href=
+"../concurrent/ConcurrentSkipListSet.html"><strong>
+ConcurrentSkipListSet</strong></a> - Skips list implementation of
+the <tt>NavigableSet</tt> interface.</li>
+<li><a href=
+"../concurrent/ConcurrentSkipListMap.html"><strong>
+ConcurrentSkipListMap</strong></a> - Skips list implementation of
+the <tt>ConcurrentNavigableMap</tt> 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 <tt>Collection</tt> 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 <tt>Set</tt> implementation.</li>
+<li><a href=
+"../AbstractList.html"><strong>AbstractList</strong></a>
+- Skeletal <tt>List</tt> implementation backed by a random access
+data store (such as an array).</li>
+<li><a href=
+"../AbstractSequentialList.html"><strong>AbstractSequentialList</strong></a>
+- Skeletal <tt>List</tt> implementation backed by a sequential
+access data store (such as a linked list).</li>
+<li><a href=
+"../AbstractQueue.html"><strong>AbstractQueue</strong></a>
+- Skeletal <tt>Queue</tt> implementation.</li>
+<li><a href=
+"../AbstractMap.html"><strong>AbstractMap</strong></a>
+- Skeletal <tt>Map</tt> 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<? super T>, 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 <tt>Enumeration</tt>
+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 <tt>Iterator</tt> 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 <tt>Comparable</tt> 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 <tt>List</tt> 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 <tt>String</tt>, and fill arrays of primitives
+and objects.</li>
+</ul>
+</li>
+</ul>
+<hr />
+<p style="font-size:smaller">
+Copyright © 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>
--- a/jdk/src/java.base/share/classes/java/util/package-info.java Fri Jun 16 22:10:20 2017 +0000
+++ b/jdk/src/java.base/share/classes/java/util/package-info.java Fri May 19 14:46:50 2017 -0700
@@ -24,27 +24,24 @@
*/
/**
- * Contains the collections framework, legacy collection classes,
- * event model, date and time facilities, internationalization, and
- * miscellaneous utility classes (a string tokenizer, a random-number
- * generator, and a bit array).
+ * Contains the collections framework, some internationalization support classes,
+ * a service loader, properties, random number generation, string parsing
+ * and scanning classes, base64 encoding and decoding, a bit array, and
+ * several miscellaneous utility classes. This package also contains
+ * legacy collection classes and legacy date and time classes.
*
* <h2><a id="CollectionsFramework"></a>{@index "Java Collections Framework"}</h2>
+ * <p>For an overview, API outline, and design rationale, please see:
* <ul>
- * <li><a href="../../../technotes/guides/collections/overview.html"><b>Collections Framework Overview</b></a>
- * <li><a href="../../../technotes/guides/collections/reference.html"><b>
- * Collections Framework Annotated Outline</b></a>
+ * <li><a href="doc-files/coll-index.html">
+ * <b>Collections Framework Documentation</b></a>
* </ul>
*
- * <h2>Related Documentation</h2>
- * For overviews, tutorials, examples, guides, and tool documentation,
- * please see:
+ * <p>For a tutorial and programming guide with examples of use
+ * of the collections framework, please see:
* <ul>
- * <li><a href="http://docs.oracle.com/javase/tutorial/collections/index.html">
- * <b>Collections Framework Tutorial</b></a>
- * <li><a
- * href="../../../technotes/guides/collections/designfaq.html"><b>Collections
- * Framework Design FAQ</b></a>
+ * <li><a href="http://docs.oracle.com/javase/tutorial/collections/index.html">
+ * <b>Collections Framework Tutorial</b></a>
* </ul>
*
* @since 1.0