jdk-sandbox: comparison jdk/src/java.base/share/classes/java/util/doc-files/coll-designfaq.html

equal deleted inserted replaced

-:ea81af6257b3
+:e92e67ed12b4
-<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html>
-<!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
 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">
-<html lang="en-US" xmlns="http://www.w3.org/1999/xhtml" xml: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 />
+<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>
 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" />
+<hr>
 <h3>Core Interfaces - General Questions</h3>
 <ol>
-<li><a name="a1" id="a1"><b>Why don't you support immutability
+<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,
 <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
+<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 name="a3" id="a3"><b>Why isn't there a core interface for
+<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 name="a28" id="a28"><b>Why didn't you use "Beans-style
+<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
 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 />
+<hr>
 <h3>Collection Interface</h3>
 <ol>
-<li><a name="a5" id="a5"><b>Why doesn't Collection extend Cloneable
+<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
 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
+<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 name="a7" id="a7"><b>Why didn't you provide a "Predicate"
+<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 name="a8" id="a8"><b>Why don't you provide a form of the
+<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 name="a9" id="a9"><b>Why don't the concrete implementations
+<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 name="a10" id="a10"><b>Why don't you provide an Iterator.add
+<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 />
+<hr>
 <h3>List Interface</h3>
 <ol>
-<li><a name="a11" id="a11"><b>Why don't you rename the List
+<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
 <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
+<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 />
+<hr>
 <h3>Map Interface</h3>
 <ol>
-<li><a name="a14" id="a14"><b>Why doesn't Map extend
+<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
 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 />
+<hr>
 <h3>Iterator Interface</h3>
 <ol>
-<li><a name="a18" id="a18"><b>Why doesn't Iterator extend
+<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 name="a19" id="a19"><b>Why don't you provide an
+<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 />
+<hr>
 <h3>Miscellaneous</h3>
 <ol>
-<li><a name="a23" id="a23"><b>Why did you write a new collections
+<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
 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
+<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
 "../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
+<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 />
+<hr>
 <p style="font-size:smaller">
-Copyright &copy; 1998, 2017, Oracle and/or its affiliates. 500 Oracle Parkway<br />
+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>

changeset 46900	e92e67ed12b4
parent 45647	ccaa2a452a2d