1 <?xml version="1.0" encoding="utf-8"?> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 4 5 <!-- 6 Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved. 7 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 8 9 This code is free software; you can redistribute it and/or modify it 10 under the terms of the GNU General Public License version 2 only, as 11 published by the Free Software Foundation. Oracle designates this 12 particular file as subject to the "Classpath" exception as provided 13 by Oracle in the LICENSE file that accompanied this code. 14 15 This code is distributed in the hope that it will be useful, but WITHOUT 16 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 17 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 18 version 2 for more details (a copy is included in the LICENSE file that 19 accompanied this code). 20 21 You should have received a copy of the GNU General Public License version 22 2 along with this work; if not, write to the Free Software Foundation, 23 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 24 25 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 26 or visit www.oracle.com if you need additional information or have any 27 questions. 28 --> 29 30 <html lang="en-US" xmlns="http://www.w3.org/1999/xhtml" xml:lang= 31 "en-US"> 32 <head> 33 <title>Collections Framework Overview</title> 34 </head> 35 <body> 36 <h1>Collections Framework Overview</h1> 37 <!-- Body text begins here --> 38 <h2>Introduction</h2> 39 The Java platform includes a <i>collections framework</i>. A 40 <i>collection</i> is an object that represents a group of objects 41 (such as the classic <a href="../ArrayList.html">ArrayList</a> class). 42 A collections framework is a unified architecture for representing 43 and manipulating collections, enabling collections to be 44 manipulated independently of implementation details. 45 <p>The primary advantages of a collections framework are that 46 it:</p> 47 <ul> 48 <li><strong>Reduces programming effort</strong> by providing data 49 structures and algorithms so you don't have to write them 50 yourself.</li> 51 <li><strong>Increases performance</strong> by providing 52 high-performance implementations of data structures and algorithms. 53 Because the various implementations of each interface are 56 <li><strong>Provides interoperability between unrelated 57 APIs</strong> by establishing a common language to pass collections 58 back and forth.</li> 59 <li><strong>Reduces the effort required to learn APIs</strong> by 60 requiring you to learn multiple ad hoc collection APIs.</li> 61 <li><strong>Reduces the effort required to design and implement 62 APIs</strong> by not requiring you to produce ad hoc collections 63 APIs.</li> 64 <li><strong>Fosters software reuse</strong> by providing a standard 65 interface for collections and algorithms with which to manipulate 66 them.</li> 67 </ul> 68 <p>The collections framework consists of:</p> 69 <ul> 70 <li><strong>Collection interfaces</strong>. Represent different 71 types of collections, such as sets, lists, and maps. These 72 interfaces form the basis of the framework.</li> 73 <li><strong>General-purpose implementations</strong>. Primary 74 implementations of the collection interfaces.</li> 75 <li><strong>Legacy implementations</strong>. The collection classes 76 from earlier releases, <tt>Vector</tt> and <tt>Hashtable</tt>, were 77 retrofitted to implement the collection interfaces.</li> 78 <li><strong>Special-purpose implementations</strong>. 79 Implementations designed for use in special situations. These 80 implementations display nonstandard performance characteristics, 81 usage restrictions, or behavior.</li> 82 <li><strong>Concurrent implementations</strong>. Implementations 83 designed for highly concurrent use.</li> 84 <li><strong>Wrapper implementations</strong>. Add functionality, 85 such as synchronization, to other implementations.</li> 86 <li><strong>Convenience implementations</strong>. High-performance 87 "mini-implementations" of the collection interfaces.</li> 88 <li><strong>Abstract implementations</strong>. Partial 89 implementations of the collection interfaces to facilitate custom 90 implementations.</li> 91 <li><strong>Algorithms</strong>. Static methods that perform useful 92 functions on collections, such as sorting a list.</li> 93 <li><strong>Infrastructure</strong>. Interfaces that provide 94 essential support for the collection interfaces.</li> 95 <li><strong>Array Utilities</strong>. Utility functions for arrays 96 of primitive types and reference objects. Not, strictly speaking, a 97 part of the collections framework, this feature was added to the 98 Java platform at the same time as the collections framework and 99 relies on some of the same infrastructure.</li> 100 </ul> 101 <hr /> 102 <h2>Collection Interfaces</h2> 103 <p>The <i>collection interfaces</i> are divided into two groups. 104 The most basic interface, <tt><a href= 105 "../Collection.html">java.util.Collection</a></tt>, 106 has the following descendants:</p> 107 <ul> 108 <li><tt><a href= 109 "../Set.html">java.util.Set</a></tt></li> 110 <li><tt><a href= 111 "../SortedSet.html">java.util.SortedSet</a></tt></li> 112 <li><tt><a href= 113 "../NavigableSet.html">java.util.NavigableSet</a></tt></li> 114 <li><tt><a href= 115 "../Queue.html">java.util.Queue</a></tt></li> 116 <li><tt><a href= 117 "../concurrent/BlockingQueue.html">java.util.concurrent.BlockingQueue</a></tt></li> 118 <li><tt><a href= 119 "../concurrent/TransferQueue.html">java.util.concurrent.TransferQueue</a></tt></li> 120 <li><tt><a href= 121 "../Deque.html">java.util.Deque</a></tt></li> 122 <li><tt><a href= 123 "../concurrent/BlockingDeque.html">java.util.concurrent.BlockingDeque</a></tt></li> 124 </ul> 125 <p>The other collection interfaces are based on <tt><a href= 126 "../Map.html">java.util.Map</a></tt> and are 127 not true collections. However, these interfaces contain 128 <i>collection-view</i> operations, which enable them to be 129 manipulated as collections. <tt>Map</tt> has the following 130 offspring:</p> 131 <ul> 132 <li><tt><a href= 133 "../SortedMap.html">java.util.SortedMap</a></tt></li> 134 <li><tt><a href= 135 "../NavigableMap.html">java.util.NavigableMap</a></tt></li> 136 <li><tt><a href= 137 "../concurrent/ConcurrentMap.html">java.util.concurrent.ConcurrentMap</a></tt></li> 138 <li><tt><a href= 139 "../concurrent/ConcurrentNavigableMap.html">java.util.concurrent.ConcurrentNavigableMap</a></tt></li> 140 </ul> 141 <p>Many of the modification methods in the collection interfaces 142 are labeled <i>optional</i>. Implementations are permitted to not 143 perform one or more of these operations, throwing a runtime 144 exception (<tt>UnsupportedOperationException</tt>) if they are 145 attempted. The documentation for each implementation must specify 146 which optional operations are supported. Several terms are 147 introduced to aid in this specification:</p> 148 <ul> 149 <li>Collections that do not support modification operations (such 150 as <tt>add</tt>, <tt>remove</tt> and <tt>clear</tt>) are referred 151 to as <i>unmodifiable</i>. Collections that are not unmodifiable 152 are <i>modifiable.</i></li> 153 <li>Collections that additionally guarantee that no change in the 154 <tt>Collection</tt> object will be visible are referred to as 155 <i>immutable</i>. Collections that are not immutable are 156 <i>mutable</i>.</li> 157 <li>Lists that guarantee that their size remains constant even 158 though the elements can change are referred to as 159 <i>fixed-size</i>. Lists that are not fixed-size are referred to as 160 <i>variable-size</i>.</li> 161 <li>Lists that support fast (generally constant time) indexed 162 element access are known as <i>random access</i> lists. Lists that 163 do not support fast indexed element access are known as 164 <i>sequential access</i> lists. The <tt><a href= 165 "../RandomAccess.html">RandomAccess</a></tt> 166 marker interface enables lists to advertise the fact that they 167 support random access. This enables generic algorithms to change 168 their behavior to provide good performance when applied to either 169 random or sequential access lists.</li> 170 </ul> 171 <p>Some implementations restrict what elements (or in the case of 172 <tt>Maps</tt>, keys and values) can be stored. Possible 173 restrictions include requiring elements to:</p> 174 <ul> 175 <li>Be of a particular type.</li> 176 <li>Be not null.</li> 177 <li>Obey some arbitrary predicate.</li> 178 </ul> 179 <p>Attempting to add an element that violates an implementation's 180 restrictions results in a runtime exception, typically a 181 <tt>ClassCastException</tt>, an <tt>IllegalArgumentException</tt>, 182 or a <tt>NullPointerException</tt>. Attempting to remove or test 183 for the presence of an element that violates an implementation's 184 restrictions can result in an exception. Some restricted 185 collections permit this usage.</p> 186 <hr /> 187 <h2>Collection Implementations</h2> 188 <p>Classes that implement the collection interfaces typically have 189 names in the form of 190 <<em>Implementation-style</em>><<em>Interface</em>>. 191 The general purpose implementations are summarized in the following 192 table:</p> 193 <table border="2" summary= 194 "general purpose implementations and interfaces" align="center"> 195 <thead> 196 <tr> 197 <th id="interfaces">Interface</th> 198 <th id="hashtable">Hash Table</th> 199 <th id="resizablearray">Resizable Array</th> 200 <th id="balancedtree">Balanced Tree</th> 201 <th id="linkedlist">Linked List</th> 202 <th id="hashtableandlinkedlist">Hash Table + Linked List</th> 203 </tr> 204 <tr> 205 <td headers="interfaces"><code>Set</code></td> 206 <td headers="hashtable"><a href= 207 "../HashSet.html"><tt>HashSet</tt></a></td> 208 <td headers="resizablearray"> </td> 209 <td headers="balancedtree"><a href= 210 "../TreeSet.html"><tt>TreeSet</tt></a></td> 211 <td headers="linkedlist"> </td> 212 <td headers="hashtableandlinkedlist"><a href= 213 "../LinkedHashSet.html"><tt>LinkedHashSet</tt></a></td> 214 </tr> 215 <tr> 216 <td headers="interfaces"><code>List</code></td> 217 <td headers="hashtable"> </td> 218 <td headers="resizablearray"><a href= 219 "../ArrayList.html"><tt>ArrayList</tt></a></td> 220 <td headers="balancedtree"> </td> 221 <td headers="linkedlist"><a href= 222 "../LinkedList.html"><tt>LinkedList</tt></a></td> 223 <td headers="hashtableandlinkedlist"> </td> 224 </tr> 225 <tr> 226 <td headers="interfaces"><code>Deque</code></td> 227 <td headers="hashtable"> </td> 228 <td headers="resizablearray"><a href= 229 "../ArrayDeque.html"><tt>ArrayDeque</tt></a></td> 230 <td headers="balancedtree"> </td> 231 <td headers="linkedlist"><a href= 232 "../LinkedList.html"><tt>LinkedList</tt></a></td> 233 <td headers="hashtableandlinkedlist"> </td> 234 </tr> 235 <tr> 236 <td headers="interfaces"><code>Map</code></td> 237 <td headers="hashtable"><a href= 238 "../HashMap.html"><tt>HashMap</tt></a></td> 239 <td headers="resizablearray"> </td> 240 <td headers="balancedtree"><a href= 241 "../TreeMap.html"><tt>TreeMap</tt></a></td> 242 <td headers="linkedlist"> </td> 243 <td headers="hashtableandlinkedlist"><a href= 244 "../LinkedHashMap.html"><tt>LinkedHashMap</tt></a></td> 245 </tr> 246 </thead> 247 </table> 248 <p>The general-purpose implementations support all of the 249 <i>optional operations</i> in the collection interfaces and have no 250 restrictions on the elements they may contain. They are 251 unsynchronized, but the <tt>Collections</tt> class contains static 252 factories called <a href= 253 "../Collections.html#synchronizedCollection-java.util.Collection-"> 254 <em>synchronization wrappers</em></a> that can be used to add 255 synchronization to many unsynchronized collections. All of the new 256 implementations have <i>fail-fast iterators</i>, which detect 257 invalid concurrent modification, and fail quickly and cleanly 258 (rather than behaving erratically).</p> 259 <p>The <tt>AbstractCollection</tt>, <tt>AbstractSet</tt>, 260 <tt>AbstractList</tt>, <tt>AbstractSequentialList</tt> and 261 <tt>AbstractMap</tt> classes provide basic implementations of the 262 core collection interfaces, to minimize the effort required to 263 implement them. The API documentation for these classes describes 264 precisely how each method is implemented so the implementer knows 265 which methods must be overridden, given the performance of the 266 basic operations of a specific implementation.</p> 267 <hr /> 268 <h2>Concurrent Collections</h2> 269 <p>Applications that use collections from more than one thread must 270 be carefully programmed. In general, this is known as <i>concurrent 271 programming</i>. The Java platform includes extensive support for 272 concurrent programming. See <a href= 273 "../concurrent/package-summary.html">Java Concurrency 274 Utilities</a> for details.</p> 275 <p>Collections are so frequently used that various concurrent 276 friendly interfaces and implementations of collections are included 277 in the APIs. These types go beyond the synchronization wrappers 278 discussed previously to provide features that are frequently needed 279 in concurrent programming.</p> 280 <p>These concurrent-aware interfaces are available:</p> 281 <ul> 282 <li><tt><a href= 283 "../concurrent/BlockingQueue.html">BlockingQueue</a></tt></li> 284 <li><tt><a href= 285 "../concurrent/TransferQueue.html">TransferQueue</a></tt></li> 286 <li><tt><a href= 287 "../concurrent/BlockingDeque.html">BlockingDeque</a></tt></li> 288 <li><tt><a href= 289 "../concurrent/ConcurrentMap.html">ConcurrentMap</a></tt></li> 290 <li><tt><a href= 291 "../concurrent/ConcurrentNavigableMap.html">ConcurrentNavigableMap</a></tt></li> 292 </ul> 293 <p>The following concurrent-aware implementation classes are 294 available. See the API documentation for the correct usage of these 295 implementations.</p> 296 <ul> 297 <li><tt><a href= 298 "../concurrent/LinkedBlockingQueue.html">LinkedBlockingQueue</a></tt></li> 299 <li><tt><a href= 300 "../concurrent/ArrayBlockingQueue.html">ArrayBlockingQueue</a></tt></li> 301 <li><tt><a href= 302 "../concurrent/PriorityBlockingQueue.html">PriorityBlockingQueue</a></tt></li> 303 <li><tt><a href= 304 "../concurrent/DelayQueue.html">DelayQueue</a></tt></li> 305 <li><tt><a href= 306 "../concurrent/SynchronousQueue.html">SynchronousQueue</a></tt></li> 307 <li><a href= 308 "../concurrent/LinkedBlockingDeque.html"><tt>LinkedBlockingDeque</tt></a></li> 309 <li><a href= 310 "../concurrent/LinkedTransferQueue.html"><tt>LinkedTransferQueue</tt></a></li> 311 <li><tt><a href= 312 "../concurrent/CopyOnWriteArrayList.html">CopyOnWriteArrayList</a></tt></li> 313 <li><tt><a href= 314 "../concurrent/CopyOnWriteArraySet.html">CopyOnWriteArraySet</a></tt></li> 315 <li><tt><a href= 316 "../concurrent/ConcurrentSkipListSet.html">ConcurrentSkipListSet</a></tt></li> 317 <li><tt><a href= 318 "../concurrent/ConcurrentHashMap.html">ConcurrentHashMap</a></tt></li> 319 <li><tt><a href= 320 "../concurrent/ConcurrentSkipListMap.html">ConcurrentSkipListMap</a></tt></li> 321 </ul> 322 <hr /> 323 <h2>Design Goals</h2> 324 <p>The main design goal was to produce an API that was small in 325 size and, more importantly, in "conceptual weight." It 326 was critical that the new functionality not seem too different to 327 current Java programmers; it had to augment current facilities, 328 rather than replace them. At the same time, the new API had to be 329 powerful enough to provide all the advantages described 330 previously.</p> 331 <p>To keep the number of core interfaces small, the interfaces do 332 not attempt to capture such subtle distinctions as mutability, 333 modifiability, and resizability. Instead, certain calls in the core 334 interfaces are <i>optional</i>, enabling implementations to throw 335 an <tt>UnsupportedOperationException</tt> to indicate that they do 336 not support a specified optional operation. Collection implementers 337 must clearly document which optional operations are supported by an 338 implementation.</p> 339 <p>To keep the number of methods in each core interface small, an 340 interface contains a method only if either:</p> 341 <ul> 342 <li>It is a truly <i>fundamental operation</i>: a basic operations 343 in terms of which others could be reasonably defined,</li> 344 <li>There is a compelling performance reason why an important 345 implementation would want to override it.</li> 346 </ul> 347 <p>It was critical that all reasonable representations of 348 collections interoperate well. This included arrays, which cannot 349 be made to implement the <tt>Collection</tt> interface directly 350 without changing the language. Thus, the framework includes methods 351 to enable collections to be moved into arrays, arrays to be viewed 352 as collections, and maps to be viewed as collections.</p> 353 <hr /> 354 <p style="font-size:smaller"> 355 Copyright © 1998, 2017, Oracle and/or its affiliates. 500 Oracle Parkway<br /> 356 Redwood Shores, CA 94065 USA. All rights reserved.</p> 357 <!-- Body text ends here --> 358 </body> 359 </html> | 1 <!DOCTYPE html> 2 <!-- 3 Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved. 4 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 6 This code is free software; you can redistribute it and/or modify it 7 under the terms of the GNU General Public License version 2 only, as 8 published by the Free Software Foundation. Oracle designates this 9 particular file as subject to the "Classpath" exception as provided 10 by Oracle in the LICENSE file that accompanied this code. 11 12 This code is distributed in the hope that it will be useful, but WITHOUT 13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 version 2 for more details (a copy is included in the LICENSE file that 16 accompanied this code). 17 18 You should have received a copy of the GNU General Public License version 19 2 along with this work; if not, write to the Free Software Foundation, 20 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 22 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 or visit www.oracle.com if you need additional information or have any 24 questions. 25 --> 26 <html lang="en-US"> 27 <head> 28 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 29 <title>Collections Framework Overview</title> 30 <style> 31 #impls { 32 border: 1px solid black; 33 border-collapse: collapse; 34 margin: 0 auto; 35 } 36 #impls caption { 37 font-weight: bold; 38 font-size: smaller; 39 } 40 #impls, #impls th, #impls td { 41 border: 1px solid black; 42 padding: 2px .5em; 43 } 44 #impls tbody th { 45 font-weight: normal; 46 text-align:left; 47 } 48 </style> 49 </head> 50 <body> 51 <h1>Collections Framework Overview</h1> 52 <!-- Body text begins here --> 53 <h2>Introduction</h2> 54 The Java platform includes a <i>collections framework</i>. A 55 <i>collection</i> is an object that represents a group of objects 56 (such as the classic <a href="../ArrayList.html">ArrayList</a> class). 57 A collections framework is a unified architecture for representing 58 and manipulating collections, enabling collections to be 59 manipulated independently of implementation details. 60 <p>The primary advantages of a collections framework are that 61 it:</p> 62 <ul> 63 <li><strong>Reduces programming effort</strong> by providing data 64 structures and algorithms so you don't have to write them 65 yourself.</li> 66 <li><strong>Increases performance</strong> by providing 67 high-performance implementations of data structures and algorithms. 68 Because the various implementations of each interface are 71 <li><strong>Provides interoperability between unrelated 72 APIs</strong> by establishing a common language to pass collections 73 back and forth.</li> 74 <li><strong>Reduces the effort required to learn APIs</strong> by 75 requiring you to learn multiple ad hoc collection APIs.</li> 76 <li><strong>Reduces the effort required to design and implement 77 APIs</strong> by not requiring you to produce ad hoc collections 78 APIs.</li> 79 <li><strong>Fosters software reuse</strong> by providing a standard 80 interface for collections and algorithms with which to manipulate 81 them.</li> 82 </ul> 83 <p>The collections framework consists of:</p> 84 <ul> 85 <li><strong>Collection interfaces</strong>. Represent different 86 types of collections, such as sets, lists, and maps. These 87 interfaces form the basis of the framework.</li> 88 <li><strong>General-purpose implementations</strong>. Primary 89 implementations of the collection interfaces.</li> 90 <li><strong>Legacy implementations</strong>. The collection classes 91 from earlier releases, <code>Vector</code> and <code>Hashtable</code>, were 92 retrofitted to implement the collection interfaces.</li> 93 <li><strong>Special-purpose implementations</strong>. 94 Implementations designed for use in special situations. These 95 implementations display nonstandard performance characteristics, 96 usage restrictions, or behavior.</li> 97 <li><strong>Concurrent implementations</strong>. Implementations 98 designed for highly concurrent use.</li> 99 <li><strong>Wrapper implementations</strong>. Add functionality, 100 such as synchronization, to other implementations.</li> 101 <li><strong>Convenience implementations</strong>. High-performance 102 "mini-implementations" of the collection interfaces.</li> 103 <li><strong>Abstract implementations</strong>. Partial 104 implementations of the collection interfaces to facilitate custom 105 implementations.</li> 106 <li><strong>Algorithms</strong>. Static methods that perform useful 107 functions on collections, such as sorting a list.</li> 108 <li><strong>Infrastructure</strong>. Interfaces that provide 109 essential support for the collection interfaces.</li> 110 <li><strong>Array Utilities</strong>. Utility functions for arrays 111 of primitive types and reference objects. Not, strictly speaking, a 112 part of the collections framework, this feature was added to the 113 Java platform at the same time as the collections framework and 114 relies on some of the same infrastructure.</li> 115 </ul> 116 <hr /> 117 <h2>Collection Interfaces</h2> 118 <p>The <i>collection interfaces</i> are divided into two groups. 119 The most basic interface, <code><a href= 120 "../Collection.html">java.util.Collection</a></code>, 121 has the following descendants:</p> 122 <ul> 123 <li><code><a href= 124 "../Set.html">java.util.Set</a></code></li> 125 <li><code><a href= 126 "../SortedSet.html">java.util.SortedSet</a></code></li> 127 <li><code><a href= 128 "../NavigableSet.html">java.util.NavigableSet</a></code></li> 129 <li><code><a href= 130 "../Queue.html">java.util.Queue</a></code></li> 131 <li><code><a href= 132 "../concurrent/BlockingQueue.html">java.util.concurrent.BlockingQueue</a></code></li> 133 <li><code><a href= 134 "../concurrent/TransferQueue.html">java.util.concurrent.TransferQueue</a></code></li> 135 <li><code><a href= 136 "../Deque.html">java.util.Deque</a></code></li> 137 <li><code><a href= 138 "../concurrent/BlockingDeque.html">java.util.concurrent.BlockingDeque</a></code></li> 139 </ul> 140 <p>The other collection interfaces are based on <code><a href= 141 "../Map.html">java.util.Map</a></code> and are 142 not true collections. However, these interfaces contain 143 <i>collection-view</i> operations, which enable them to be 144 manipulated as collections. <code>Map</code> has the following 145 offspring:</p> 146 <ul> 147 <li><code><a href= 148 "../SortedMap.html">java.util.SortedMap</a></code></li> 149 <li><code><a href= 150 "../NavigableMap.html">java.util.NavigableMap</a></code></li> 151 <li><code><a href= 152 "../concurrent/ConcurrentMap.html">java.util.concurrent.ConcurrentMap</a></code></li> 153 <li><code><a href= 154 "../concurrent/ConcurrentNavigableMap.html">java.util.concurrent.ConcurrentNavigableMap</a></code></li> 155 </ul> 156 <p>Many of the modification methods in the collection interfaces 157 are labeled <i>optional</i>. Implementations are permitted to not 158 perform one or more of these operations, throwing a runtime 159 exception (<code>UnsupportedOperationException</code>) if they are 160 attempted. The documentation for each implementation must specify 161 which optional operations are supported. Several terms are 162 introduced to aid in this specification:</p> 163 <ul> 164 <li>Collections that do not support modification operations (such 165 as <code>add</code>, <code>remove</code> and <code>clear</code>) are referred 166 to as <i>unmodifiable</i>. Collections that are not unmodifiable 167 are <i>modifiable.</i></li> 168 <li>Collections that additionally guarantee that no change in the 169 <code>Collection</code> object will be visible are referred to as 170 <i>immutable</i>. Collections that are not immutable are 171 <i>mutable</i>.</li> 172 <li>Lists that guarantee that their size remains constant even 173 though the elements can change are referred to as 174 <i>fixed-size</i>. Lists that are not fixed-size are referred to as 175 <i>variable-size</i>.</li> 176 <li>Lists that support fast (generally constant time) indexed 177 element access are known as <i>random access</i> lists. Lists that 178 do not support fast indexed element access are known as 179 <i>sequential access</i> lists. The <code><a href= 180 "../RandomAccess.html">RandomAccess</a></code> 181 marker interface enables lists to advertise the fact that they 182 support random access. This enables generic algorithms to change 183 their behavior to provide good performance when applied to either 184 random or sequential access lists.</li> 185 </ul> 186 <p>Some implementations restrict what elements (or in the case of 187 <code>Maps</code>, keys and values) can be stored. Possible 188 restrictions include requiring elements to:</p> 189 <ul> 190 <li>Be of a particular type.</li> 191 <li>Be not null.</li> 192 <li>Obey some arbitrary predicate.</li> 193 </ul> 194 <p>Attempting to add an element that violates an implementation's 195 restrictions results in a runtime exception, typically a 196 <code>ClassCastException</code>, an <code>IllegalArgumentException</code>, 197 or a <code>NullPointerException</code>. Attempting to remove or test 198 for the presence of an element that violates an implementation's 199 restrictions can result in an exception. Some restricted 200 collections permit this usage.</p> 201 <hr> 202 <h2>Collection Implementations</h2> 203 <p>Classes that implement the collection interfaces typically have 204 names in the form of 205 <<em>Implementation-style</em>><<em>Interface</em>>. 206 The general purpose implementations are summarized in the following 207 table:</p> 208 <table id="impls"> 209 <caption>General purpose implementations</caption> 210 <thead> 211 <tr> 212 <th scope="col">Interface</th> 213 <th scope="col">Hash Table</th> 214 <th scope="col">Resizable Array</th> 215 <th scope="col">Balanced Tree</th> 216 <th scope="col">Linked List</th> 217 <th scope="col">Hash Table + Linked List</th> 218 </tr> 219 </thead> 220 <tbody> 221 <tr> 222 <th scope="row"><code>Set</code></th> 223 <td><a href="../HashSet.html"><code>HashSet</code></a></td> 224 <td> </td> 225 <td><a href="../TreeSet.html"><code>TreeSet</code></a></td> 226 <td> </td> 227 <td><a href= 228 "../LinkedHashSet.html"><code>LinkedHashSet</code></a></td> 229 </tr> 230 <tr> 231 <th scope="row"><code>List</code></th> 232 <td> </td> 233 <td><a href="../ArrayList.html"><code>ArrayList</code></a></td> 234 <td> </td> 235 <td><a href="../LinkedList.html"><code>LinkedList</code></a></td> 236 <td> </td> 237 </tr> 238 <tr> 239 <th scope="row"><code>Deque</code></th> 240 <td> </td> 241 <td><a href="../ArrayDeque.html"><code>ArrayDeque</code></a></td> 242 <td> </td> 243 <td><a href="../LinkedList.html"><code>LinkedList</code></a></td> 244 <td> </td> 245 </tr> 246 <tr> 247 <th scope="row"><code>Map</code></th> 248 <td><a href="../HashMap.html"><code>HashMap</code></a></td> 249 <td> </td> 250 <td><a href="../TreeMap.html"><code>TreeMap</code></a></td> 251 <td> </td> 252 <td><a href="../LinkedHashMap.html"><code>LinkedHashMap</code></a></td> 253 </tr> 254 </tbody> 255 </table> 256 <p>The general-purpose implementations support all of the 257 <i>optional operations</i> in the collection interfaces and have no 258 restrictions on the elements they may contain. They are 259 unsynchronized, but the <code>Collections</code> class contains static 260 factories called <a href= 261 "../Collections.html#synchronizedCollection-java.util.Collection-"> 262 <em>synchronization wrappers</em></a> that can be used to add 263 synchronization to many unsynchronized collections. All of the new 264 implementations have <i>fail-fast iterators</i>, which detect 265 invalid concurrent modification, and fail quickly and cleanly 266 (rather than behaving erratically).</p> 267 <p>The <code>AbstractCollection</code>, <code>AbstractSet</code>, 268 <code>AbstractList</code>, <code>AbstractSequentialList</code> and 269 <code>AbstractMap</code> classes provide basic implementations of the 270 core collection interfaces, to minimize the effort required to 271 implement them. The API documentation for these classes describes 272 precisely how each method is implemented so the implementer knows 273 which methods must be overridden, given the performance of the 274 basic operations of a specific implementation.</p> 275 <hr> 276 <h2>Concurrent Collections</h2> 277 <p>Applications that use collections from more than one thread must 278 be carefully programmed. In general, this is known as <i>concurrent 279 programming</i>. The Java platform includes extensive support for 280 concurrent programming. See <a href= 281 "../concurrent/package-summary.html">Java Concurrency 282 Utilities</a> for details.</p> 283 <p>Collections are so frequently used that various concurrent 284 friendly interfaces and implementations of collections are included 285 in the APIs. These types go beyond the synchronization wrappers 286 discussed previously to provide features that are frequently needed 287 in concurrent programming.</p> 288 <p>These concurrent-aware interfaces are available:</p> 289 <ul> 290 <li><code><a href= 291 "../concurrent/BlockingQueue.html">BlockingQueue</a></code></li> 292 <li><code><a href= 293 "../concurrent/TransferQueue.html">TransferQueue</a></code></li> 294 <li><code><a href= 295 "../concurrent/BlockingDeque.html">BlockingDeque</a></code></li> 296 <li><code><a href= 297 "../concurrent/ConcurrentMap.html">ConcurrentMap</a></code></li> 298 <li><code><a href= 299 "../concurrent/ConcurrentNavigableMap.html">ConcurrentNavigableMap</a></code></li> 300 </ul> 301 <p>The following concurrent-aware implementation classes are 302 available. See the API documentation for the correct usage of these 303 implementations.</p> 304 <ul> 305 <li><code><a href= 306 "../concurrent/LinkedBlockingQueue.html">LinkedBlockingQueue</a></code></li> 307 <li><code><a href= 308 "../concurrent/ArrayBlockingQueue.html">ArrayBlockingQueue</a></code></li> 309 <li><code><a href= 310 "../concurrent/PriorityBlockingQueue.html">PriorityBlockingQueue</a></code></li> 311 <li><code><a href= 312 "../concurrent/DelayQueue.html">DelayQueue</a></code></li> 313 <li><code><a href= 314 "../concurrent/SynchronousQueue.html">SynchronousQueue</a></code></li> 315 <li><a href= 316 "../concurrent/LinkedBlockingDeque.html"><code>LinkedBlockingDeque</code></a></li> 317 <li><a href= 318 "../concurrent/LinkedTransferQueue.html"><code>LinkedTransferQueue</code></a></li> 319 <li><code><a href= 320 "../concurrent/CopyOnWriteArrayList.html">CopyOnWriteArrayList</a></code></li> 321 <li><code><a href= 322 "../concurrent/CopyOnWriteArraySet.html">CopyOnWriteArraySet</a></code></li> 323 <li><code><a href= 324 "../concurrent/ConcurrentSkipListSet.html">ConcurrentSkipListSet</a></code></li> 325 <li><code><a href= 326 "../concurrent/ConcurrentHashMap.html">ConcurrentHashMap</a></code></li> 327 <li><code><a href= 328 "../concurrent/ConcurrentSkipListMap.html">ConcurrentSkipListMap</a></code></li> 329 </ul> 330 <hr> 331 <h2>Design Goals</h2> 332 <p>The main design goal was to produce an API that was small in 333 size and, more importantly, in "conceptual weight." It 334 was critical that the new functionality not seem too different to 335 current Java programmers; it had to augment current facilities, 336 rather than replace them. At the same time, the new API had to be 337 powerful enough to provide all the advantages described 338 previously.</p> 339 <p>To keep the number of core interfaces small, the interfaces do 340 not attempt to capture such subtle distinctions as mutability, 341 modifiability, and resizability. Instead, certain calls in the core 342 interfaces are <i>optional</i>, enabling implementations to throw 343 an <code>UnsupportedOperationException</code> to indicate that they do 344 not support a specified optional operation. Collection implementers 345 must clearly document which optional operations are supported by an 346 implementation.</p> 347 <p>To keep the number of methods in each core interface small, an 348 interface contains a method only if either:</p> 349 <ul> 350 <li>It is a truly <i>fundamental operation</i>: a basic operations 351 in terms of which others could be reasonably defined,</li> 352 <li>There is a compelling performance reason why an important 353 implementation would want to override it.</li> 354 </ul> 355 <p>It was critical that all reasonable representations of 356 collections interoperate well. This included arrays, which cannot 357 be made to implement the <code>Collection</code> interface directly 358 without changing the language. Thus, the framework includes methods 359 to enable collections to be moved into arrays, arrays to be viewed 360 as collections, and maps to be viewed as collections.</p> 361 <hr> 362 <p style="font-size:smaller"> 363 Copyright © 1998, 2017, Oracle and/or its affiliates. 500 Oracle Parkway<br> 364 Redwood Shores, CA 94065 USA. All rights reserved.</p> 365 <!-- Body text ends here --> 366 </body> 367 </html> |