1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/emul/compact/src/main/java/java/util/AbstractQueue.java Mon Jan 28 13:28:02 2013 +0100
1.3 @@ -0,0 +1,192 @@
1.4 +/*
1.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.6 + *
1.7 + * This code is free software; you can redistribute it and/or modify it
1.8 + * under the terms of the GNU General Public License version 2 only, as
1.9 + * published by the Free Software Foundation. Oracle designates this
1.10 + * particular file as subject to the "Classpath" exception as provided
1.11 + * by Oracle in the LICENSE file that accompanied this code.
1.12 + *
1.13 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.14 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.15 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.16 + * version 2 for more details (a copy is included in the LICENSE file that
1.17 + * accompanied this code).
1.18 + *
1.19 + * You should have received a copy of the GNU General Public License version
1.20 + * 2 along with this work; if not, write to the Free Software Foundation,
1.21 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.22 + *
1.23 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.24 + * or visit www.oracle.com if you need additional information or have any
1.25 + * questions.
1.26 + */
1.27 +
1.28 +/*
1.29 + * This file is available under and governed by the GNU General Public
1.30 + * License version 2 only, as published by the Free Software Foundation.
1.31 + * However, the following notice accompanied the original version of this
1.32 + * file:
1.33 + *
1.34 + * Written by Doug Lea with assistance from members of JCP JSR-166
1.35 + * Expert Group and released to the public domain, as explained at
1.36 + * http://creativecommons.org/publicdomain/zero/1.0/
1.37 + */
1.38 +
1.39 +package java.util;
1.40 +
1.41 +/**
1.42 + * This class provides skeletal implementations of some {@link Queue}
1.43 + * operations. The implementations in this class are appropriate when
1.44 + * the base implementation does <em>not</em> allow <tt>null</tt>
1.45 + * elements. Methods {@link #add add}, {@link #remove remove}, and
1.46 + * {@link #element element} are based on {@link #offer offer}, {@link
1.47 + * #poll poll}, and {@link #peek peek}, respectively, but throw
1.48 + * exceptions instead of indicating failure via <tt>false</tt> or
1.49 + * <tt>null</tt> returns.
1.50 + *
1.51 + * <p>A <tt>Queue</tt> implementation that extends this class must
1.52 + * minimally define a method {@link Queue#offer} which does not permit
1.53 + * insertion of <tt>null</tt> elements, along with methods {@link
1.54 + * Queue#peek}, {@link Queue#poll}, {@link Collection#size}, and
1.55 + * {@link Collection#iterator}. Typically, additional methods will be
1.56 + * overridden as well. If these requirements cannot be met, consider
1.57 + * instead subclassing {@link AbstractCollection}.
1.58 + *
1.59 + * <p>This class is a member of the
1.60 + * <a href="{@docRoot}/../technotes/guides/collections/index.html">
1.61 + * Java Collections Framework</a>.
1.62 + *
1.63 + * @since 1.5
1.64 + * @author Doug Lea
1.65 + * @param <E> the type of elements held in this collection
1.66 + */
1.67 +public abstract class AbstractQueue<E>
1.68 + extends AbstractCollection<E>
1.69 + implements Queue<E> {
1.70 +
1.71 + /**
1.72 + * Constructor for use by subclasses.
1.73 + */
1.74 + protected AbstractQueue() {
1.75 + }
1.76 +
1.77 + /**
1.78 + * Inserts the specified element into this queue if it is possible to do so
1.79 + * immediately without violating capacity restrictions, returning
1.80 + * <tt>true</tt> upon success and throwing an <tt>IllegalStateException</tt>
1.81 + * if no space is currently available.
1.82 + *
1.83 + * <p>This implementation returns <tt>true</tt> if <tt>offer</tt> succeeds,
1.84 + * else throws an <tt>IllegalStateException</tt>.
1.85 + *
1.86 + * @param e the element to add
1.87 + * @return <tt>true</tt> (as specified by {@link Collection#add})
1.88 + * @throws IllegalStateException if the element cannot be added at this
1.89 + * time due to capacity restrictions
1.90 + * @throws ClassCastException if the class of the specified element
1.91 + * prevents it from being added to this queue
1.92 + * @throws NullPointerException if the specified element is null and
1.93 + * this queue does not permit null elements
1.94 + * @throws IllegalArgumentException if some property of this element
1.95 + * prevents it from being added to this queue
1.96 + */
1.97 + public boolean add(E e) {
1.98 + if (offer(e))
1.99 + return true;
1.100 + else
1.101 + throw new IllegalStateException("Queue full");
1.102 + }
1.103 +
1.104 + /**
1.105 + * Retrieves and removes the head of this queue. This method differs
1.106 + * from {@link #poll poll} only in that it throws an exception if this
1.107 + * queue is empty.
1.108 + *
1.109 + * <p>This implementation returns the result of <tt>poll</tt>
1.110 + * unless the queue is empty.
1.111 + *
1.112 + * @return the head of this queue
1.113 + * @throws NoSuchElementException if this queue is empty
1.114 + */
1.115 + public E remove() {
1.116 + E x = poll();
1.117 + if (x != null)
1.118 + return x;
1.119 + else
1.120 + throw new NoSuchElementException();
1.121 + }
1.122 +
1.123 + /**
1.124 + * Retrieves, but does not remove, the head of this queue. This method
1.125 + * differs from {@link #peek peek} only in that it throws an exception if
1.126 + * this queue is empty.
1.127 + *
1.128 + * <p>This implementation returns the result of <tt>peek</tt>
1.129 + * unless the queue is empty.
1.130 + *
1.131 + * @return the head of this queue
1.132 + * @throws NoSuchElementException if this queue is empty
1.133 + */
1.134 + public E element() {
1.135 + E x = peek();
1.136 + if (x != null)
1.137 + return x;
1.138 + else
1.139 + throw new NoSuchElementException();
1.140 + }
1.141 +
1.142 + /**
1.143 + * Removes all of the elements from this queue.
1.144 + * The queue will be empty after this call returns.
1.145 + *
1.146 + * <p>This implementation repeatedly invokes {@link #poll poll} until it
1.147 + * returns <tt>null</tt>.
1.148 + */
1.149 + public void clear() {
1.150 + while (poll() != null)
1.151 + ;
1.152 + }
1.153 +
1.154 + /**
1.155 + * Adds all of the elements in the specified collection to this
1.156 + * queue. Attempts to addAll of a queue to itself result in
1.157 + * <tt>IllegalArgumentException</tt>. Further, the behavior of
1.158 + * this operation is undefined if the specified collection is
1.159 + * modified while the operation is in progress.
1.160 + *
1.161 + * <p>This implementation iterates over the specified collection,
1.162 + * and adds each element returned by the iterator to this
1.163 + * queue, in turn. A runtime exception encountered while
1.164 + * trying to add an element (including, in particular, a
1.165 + * <tt>null</tt> element) may result in only some of the elements
1.166 + * having been successfully added when the associated exception is
1.167 + * thrown.
1.168 + *
1.169 + * @param c collection containing elements to be added to this queue
1.170 + * @return <tt>true</tt> if this queue changed as a result of the call
1.171 + * @throws ClassCastException if the class of an element of the specified
1.172 + * collection prevents it from being added to this queue
1.173 + * @throws NullPointerException if the specified collection contains a
1.174 + * null element and this queue does not permit null elements,
1.175 + * or if the specified collection is null
1.176 + * @throws IllegalArgumentException if some property of an element of the
1.177 + * specified collection prevents it from being added to this
1.178 + * queue, or if the specified collection is this queue
1.179 + * @throws IllegalStateException if not all the elements can be added at
1.180 + * this time due to insertion restrictions
1.181 + * @see #add(Object)
1.182 + */
1.183 + public boolean addAll(Collection<? extends E> c) {
1.184 + if (c == null)
1.185 + throw new NullPointerException();
1.186 + if (c == this)
1.187 + throw new IllegalArgumentException();
1.188 + boolean modified = false;
1.189 + for (E e : c)
1.190 + if (add(e))
1.191 + modified = true;
1.192 + return modified;
1.193 + }
1.194 +
1.195 +}
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/emul/compact/src/main/java/java/util/AbstractSequentialList.java Mon Jan 28 13:28:02 2013 +0100
2.3 @@ -0,0 +1,253 @@
2.4 +/*
2.5 + * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
2.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
2.7 + *
2.8 + * This code is free software; you can redistribute it and/or modify it
2.9 + * under the terms of the GNU General Public License version 2 only, as
2.10 + * published by the Free Software Foundation. Oracle designates this
2.11 + * particular file as subject to the "Classpath" exception as provided
2.12 + * by Oracle in the LICENSE file that accompanied this code.
2.13 + *
2.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
2.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
2.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
2.17 + * version 2 for more details (a copy is included in the LICENSE file that
2.18 + * accompanied this code).
2.19 + *
2.20 + * You should have received a copy of the GNU General Public License version
2.21 + * 2 along with this work; if not, write to the Free Software Foundation,
2.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
2.23 + *
2.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
2.25 + * or visit www.oracle.com if you need additional information or have any
2.26 + * questions.
2.27 + */
2.28 +
2.29 +package java.util;
2.30 +
2.31 +/**
2.32 + * This class provides a skeletal implementation of the <tt>List</tt>
2.33 + * interface to minimize the effort required to implement this interface
2.34 + * backed by a "sequential access" data store (such as a linked list). For
2.35 + * random access data (such as an array), <tt>AbstractList</tt> should be used
2.36 + * in preference to this class.<p>
2.37 + *
2.38 + * This class is the opposite of the <tt>AbstractList</tt> class in the sense
2.39 + * that it implements the "random access" methods (<tt>get(int index)</tt>,
2.40 + * <tt>set(int index, E element)</tt>, <tt>add(int index, E element)</tt> and
2.41 + * <tt>remove(int index)</tt>) on top of the list's list iterator, instead of
2.42 + * the other way around.<p>
2.43 + *
2.44 + * To implement a list the programmer needs only to extend this class and
2.45 + * provide implementations for the <tt>listIterator</tt> and <tt>size</tt>
2.46 + * methods. For an unmodifiable list, the programmer need only implement the
2.47 + * list iterator's <tt>hasNext</tt>, <tt>next</tt>, <tt>hasPrevious</tt>,
2.48 + * <tt>previous</tt> and <tt>index</tt> methods.<p>
2.49 + *
2.50 + * For a modifiable list the programmer should additionally implement the list
2.51 + * iterator's <tt>set</tt> method. For a variable-size list the programmer
2.52 + * should additionally implement the list iterator's <tt>remove</tt> and
2.53 + * <tt>add</tt> methods.<p>
2.54 + *
2.55 + * The programmer should generally provide a void (no argument) and collection
2.56 + * constructor, as per the recommendation in the <tt>Collection</tt> interface
2.57 + * specification.<p>
2.58 + *
2.59 + * This class is a member of the
2.60 + * <a href="{@docRoot}/../technotes/guides/collections/index.html">
2.61 + * Java Collections Framework</a>.
2.62 + *
2.63 + * @author Josh Bloch
2.64 + * @author Neal Gafter
2.65 + * @see Collection
2.66 + * @see List
2.67 + * @see AbstractList
2.68 + * @see AbstractCollection
2.69 + * @since 1.2
2.70 + */
2.71 +
2.72 +public abstract class AbstractSequentialList<E> extends AbstractList<E> {
2.73 + /**
2.74 + * Sole constructor. (For invocation by subclass constructors, typically
2.75 + * implicit.)
2.76 + */
2.77 + protected AbstractSequentialList() {
2.78 + }
2.79 +
2.80 + /**
2.81 + * Returns the element at the specified position in this list.
2.82 + *
2.83 + * <p>This implementation first gets a list iterator pointing to the
2.84 + * indexed element (with <tt>listIterator(index)</tt>). Then, it gets
2.85 + * the element using <tt>ListIterator.next</tt> and returns it.
2.86 + *
2.87 + * @throws IndexOutOfBoundsException {@inheritDoc}
2.88 + */
2.89 + public E get(int index) {
2.90 + try {
2.91 + return listIterator(index).next();
2.92 + } catch (NoSuchElementException exc) {
2.93 + throw new IndexOutOfBoundsException("Index: "+index);
2.94 + }
2.95 + }
2.96 +
2.97 + /**
2.98 + * Replaces the element at the specified position in this list with the
2.99 + * specified element (optional operation).
2.100 + *
2.101 + * <p>This implementation first gets a list iterator pointing to the
2.102 + * indexed element (with <tt>listIterator(index)</tt>). Then, it gets
2.103 + * the current element using <tt>ListIterator.next</tt> and replaces it
2.104 + * with <tt>ListIterator.set</tt>.
2.105 + *
2.106 + * <p>Note that this implementation will throw an
2.107 + * <tt>UnsupportedOperationException</tt> if the list iterator does not
2.108 + * implement the <tt>set</tt> operation.
2.109 + *
2.110 + * @throws UnsupportedOperationException {@inheritDoc}
2.111 + * @throws ClassCastException {@inheritDoc}
2.112 + * @throws NullPointerException {@inheritDoc}
2.113 + * @throws IllegalArgumentException {@inheritDoc}
2.114 + * @throws IndexOutOfBoundsException {@inheritDoc}
2.115 + */
2.116 + public E set(int index, E element) {
2.117 + try {
2.118 + ListIterator<E> e = listIterator(index);
2.119 + E oldVal = e.next();
2.120 + e.set(element);
2.121 + return oldVal;
2.122 + } catch (NoSuchElementException exc) {
2.123 + throw new IndexOutOfBoundsException("Index: "+index);
2.124 + }
2.125 + }
2.126 +
2.127 + /**
2.128 + * Inserts the specified element at the specified position in this list
2.129 + * (optional operation). Shifts the element currently at that position
2.130 + * (if any) and any subsequent elements to the right (adds one to their
2.131 + * indices).
2.132 + *
2.133 + * <p>This implementation first gets a list iterator pointing to the
2.134 + * indexed element (with <tt>listIterator(index)</tt>). Then, it
2.135 + * inserts the specified element with <tt>ListIterator.add</tt>.
2.136 + *
2.137 + * <p>Note that this implementation will throw an
2.138 + * <tt>UnsupportedOperationException</tt> if the list iterator does not
2.139 + * implement the <tt>add</tt> operation.
2.140 + *
2.141 + * @throws UnsupportedOperationException {@inheritDoc}
2.142 + * @throws ClassCastException {@inheritDoc}
2.143 + * @throws NullPointerException {@inheritDoc}
2.144 + * @throws IllegalArgumentException {@inheritDoc}
2.145 + * @throws IndexOutOfBoundsException {@inheritDoc}
2.146 + */
2.147 + public void add(int index, E element) {
2.148 + try {
2.149 + listIterator(index).add(element);
2.150 + } catch (NoSuchElementException exc) {
2.151 + throw new IndexOutOfBoundsException("Index: "+index);
2.152 + }
2.153 + }
2.154 +
2.155 + /**
2.156 + * Removes the element at the specified position in this list (optional
2.157 + * operation). Shifts any subsequent elements to the left (subtracts one
2.158 + * from their indices). Returns the element that was removed from the
2.159 + * list.
2.160 + *
2.161 + * <p>This implementation first gets a list iterator pointing to the
2.162 + * indexed element (with <tt>listIterator(index)</tt>). Then, it removes
2.163 + * the element with <tt>ListIterator.remove</tt>.
2.164 + *
2.165 + * <p>Note that this implementation will throw an
2.166 + * <tt>UnsupportedOperationException</tt> if the list iterator does not
2.167 + * implement the <tt>remove</tt> operation.
2.168 + *
2.169 + * @throws UnsupportedOperationException {@inheritDoc}
2.170 + * @throws IndexOutOfBoundsException {@inheritDoc}
2.171 + */
2.172 + public E remove(int index) {
2.173 + try {
2.174 + ListIterator<E> e = listIterator(index);
2.175 + E outCast = e.next();
2.176 + e.remove();
2.177 + return outCast;
2.178 + } catch (NoSuchElementException exc) {
2.179 + throw new IndexOutOfBoundsException("Index: "+index);
2.180 + }
2.181 + }
2.182 +
2.183 +
2.184 + // Bulk Operations
2.185 +
2.186 + /**
2.187 + * Inserts all of the elements in the specified collection into this
2.188 + * list at the specified position (optional operation). Shifts the
2.189 + * element currently at that position (if any) and any subsequent
2.190 + * elements to the right (increases their indices). The new elements
2.191 + * will appear in this list in the order that they are returned by the
2.192 + * specified collection's iterator. The behavior of this operation is
2.193 + * undefined if the specified collection is modified while the
2.194 + * operation is in progress. (Note that this will occur if the specified
2.195 + * collection is this list, and it's nonempty.)
2.196 + *
2.197 + * <p>This implementation gets an iterator over the specified collection and
2.198 + * a list iterator over this list pointing to the indexed element (with
2.199 + * <tt>listIterator(index)</tt>). Then, it iterates over the specified
2.200 + * collection, inserting the elements obtained from the iterator into this
2.201 + * list, one at a time, using <tt>ListIterator.add</tt> followed by
2.202 + * <tt>ListIterator.next</tt> (to skip over the added element).
2.203 + *
2.204 + * <p>Note that this implementation will throw an
2.205 + * <tt>UnsupportedOperationException</tt> if the list iterator returned by
2.206 + * the <tt>listIterator</tt> method does not implement the <tt>add</tt>
2.207 + * operation.
2.208 + *
2.209 + * @throws UnsupportedOperationException {@inheritDoc}
2.210 + * @throws ClassCastException {@inheritDoc}
2.211 + * @throws NullPointerException {@inheritDoc}
2.212 + * @throws IllegalArgumentException {@inheritDoc}
2.213 + * @throws IndexOutOfBoundsException {@inheritDoc}
2.214 + */
2.215 + public boolean addAll(int index, Collection<? extends E> c) {
2.216 + try {
2.217 + boolean modified = false;
2.218 + ListIterator<E> e1 = listIterator(index);
2.219 + Iterator<? extends E> e2 = c.iterator();
2.220 + while (e2.hasNext()) {
2.221 + e1.add(e2.next());
2.222 + modified = true;
2.223 + }
2.224 + return modified;
2.225 + } catch (NoSuchElementException exc) {
2.226 + throw new IndexOutOfBoundsException("Index: "+index);
2.227 + }
2.228 + }
2.229 +
2.230 +
2.231 + // Iterators
2.232 +
2.233 + /**
2.234 + * Returns an iterator over the elements in this list (in proper
2.235 + * sequence).<p>
2.236 + *
2.237 + * This implementation merely returns a list iterator over the list.
2.238 + *
2.239 + * @return an iterator over the elements in this list (in proper sequence)
2.240 + */
2.241 + public Iterator<E> iterator() {
2.242 + return listIterator();
2.243 + }
2.244 +
2.245 + /**
2.246 + * Returns a list iterator over the elements in this list (in proper
2.247 + * sequence).
2.248 + *
2.249 + * @param index index of first element to be returned from the list
2.250 + * iterator (by a call to the <code>next</code> method)
2.251 + * @return a list iterator over the elements in this list (in proper
2.252 + * sequence)
2.253 + * @throws IndexOutOfBoundsException {@inheritDoc}
2.254 + */
2.255 + public abstract ListIterator<E> listIterator(int index);
2.256 +}
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/emul/compact/src/main/java/java/util/ArrayDeque.java Mon Jan 28 13:28:02 2013 +0100
3.3 @@ -0,0 +1,866 @@
3.4 +/*
3.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3.6 + *
3.7 + * This code is free software; you can redistribute it and/or modify it
3.8 + * under the terms of the GNU General Public License version 2 only, as
3.9 + * published by the Free Software Foundation. Oracle designates this
3.10 + * particular file as subject to the "Classpath" exception as provided
3.11 + * by Oracle in the LICENSE file that accompanied this code.
3.12 + *
3.13 + * This code is distributed in the hope that it will be useful, but WITHOUT
3.14 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
3.15 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
3.16 + * version 2 for more details (a copy is included in the LICENSE file that
3.17 + * accompanied this code).
3.18 + *
3.19 + * You should have received a copy of the GNU General Public License version
3.20 + * 2 along with this work; if not, write to the Free Software Foundation,
3.21 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
3.22 + *
3.23 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
3.24 + * or visit www.oracle.com if you need additional information or have any
3.25 + * questions.
3.26 + */
3.27 +
3.28 +/*
3.29 + * This file is available under and governed by the GNU General Public
3.30 + * License version 2 only, as published by the Free Software Foundation.
3.31 + * However, the following notice accompanied the original version of this
3.32 + * file:
3.33 + *
3.34 + * Written by Josh Bloch of Google Inc. and released to the public domain,
3.35 + * as explained at http://creativecommons.org/publicdomain/zero/1.0/.
3.36 + */
3.37 +
3.38 +package java.util;
3.39 +import java.io.*;
3.40 +
3.41 +/**
3.42 + * Resizable-array implementation of the {@link Deque} interface. Array
3.43 + * deques have no capacity restrictions; they grow as necessary to support
3.44 + * usage. They are not thread-safe; in the absence of external
3.45 + * synchronization, they do not support concurrent access by multiple threads.
3.46 + * Null elements are prohibited. This class is likely to be faster than
3.47 + * {@link Stack} when used as a stack, and faster than {@link LinkedList}
3.48 + * when used as a queue.
3.49 + *
3.50 + * <p>Most <tt>ArrayDeque</tt> operations run in amortized constant time.
3.51 + * Exceptions include {@link #remove(Object) remove}, {@link
3.52 + * #removeFirstOccurrence removeFirstOccurrence}, {@link #removeLastOccurrence
3.53 + * removeLastOccurrence}, {@link #contains contains}, {@link #iterator
3.54 + * iterator.remove()}, and the bulk operations, all of which run in linear
3.55 + * time.
3.56 + *
3.57 + * <p>The iterators returned by this class's <tt>iterator</tt> method are
3.58 + * <i>fail-fast</i>: If the deque is modified at any time after the iterator
3.59 + * is created, in any way except through the iterator's own <tt>remove</tt>
3.60 + * method, the iterator will generally throw a {@link
3.61 + * ConcurrentModificationException}. Thus, in the face of concurrent
3.62 + * modification, the iterator fails quickly and cleanly, rather than risking
3.63 + * arbitrary, non-deterministic behavior at an undetermined time in the
3.64 + * future.
3.65 + *
3.66 + * <p>Note that the fail-fast behavior of an iterator cannot be guaranteed
3.67 + * as it is, generally speaking, impossible to make any hard guarantees in the
3.68 + * presence of unsynchronized concurrent modification. Fail-fast iterators
3.69 + * throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
3.70 + * Therefore, it would be wrong to write a program that depended on this
3.71 + * exception for its correctness: <i>the fail-fast behavior of iterators
3.72 + * should be used only to detect bugs.</i>
3.73 + *
3.74 + * <p>This class and its iterator implement all of the
3.75 + * <em>optional</em> methods of the {@link Collection} and {@link
3.76 + * Iterator} interfaces.
3.77 + *
3.78 + * <p>This class is a member of the
3.79 + * <a href="{@docRoot}/../technotes/guides/collections/index.html">
3.80 + * Java Collections Framework</a>.
3.81 + *
3.82 + * @author Josh Bloch and Doug Lea
3.83 + * @since 1.6
3.84 + * @param <E> the type of elements held in this collection
3.85 + */
3.86 +public class ArrayDeque<E> extends AbstractCollection<E>
3.87 + implements Deque<E>, Cloneable, Serializable
3.88 +{
3.89 + /**
3.90 + * The array in which the elements of the deque are stored.
3.91 + * The capacity of the deque is the length of this array, which is
3.92 + * always a power of two. The array is never allowed to become
3.93 + * full, except transiently within an addX method where it is
3.94 + * resized (see doubleCapacity) immediately upon becoming full,
3.95 + * thus avoiding head and tail wrapping around to equal each
3.96 + * other. We also guarantee that all array cells not holding
3.97 + * deque elements are always null.
3.98 + */
3.99 + private transient E[] elements;
3.100 +
3.101 + /**
3.102 + * The index of the element at the head of the deque (which is the
3.103 + * element that would be removed by remove() or pop()); or an
3.104 + * arbitrary number equal to tail if the deque is empty.
3.105 + */
3.106 + private transient int head;
3.107 +
3.108 + /**
3.109 + * The index at which the next element would be added to the tail
3.110 + * of the deque (via addLast(E), add(E), or push(E)).
3.111 + */
3.112 + private transient int tail;
3.113 +
3.114 + /**
3.115 + * The minimum capacity that we'll use for a newly created deque.
3.116 + * Must be a power of 2.
3.117 + */
3.118 + private static final int MIN_INITIAL_CAPACITY = 8;
3.119 +
3.120 + // ****** Array allocation and resizing utilities ******
3.121 +
3.122 + /**
3.123 + * Allocate empty array to hold the given number of elements.
3.124 + *
3.125 + * @param numElements the number of elements to hold
3.126 + */
3.127 + private void allocateElements(int numElements) {
3.128 + int initialCapacity = MIN_INITIAL_CAPACITY;
3.129 + // Find the best power of two to hold elements.
3.130 + // Tests "<=" because arrays aren't kept full.
3.131 + if (numElements >= initialCapacity) {
3.132 + initialCapacity = numElements;
3.133 + initialCapacity |= (initialCapacity >>> 1);
3.134 + initialCapacity |= (initialCapacity >>> 2);
3.135 + initialCapacity |= (initialCapacity >>> 4);
3.136 + initialCapacity |= (initialCapacity >>> 8);
3.137 + initialCapacity |= (initialCapacity >>> 16);
3.138 + initialCapacity++;
3.139 +
3.140 + if (initialCapacity < 0) // Too many elements, must back off
3.141 + initialCapacity >>>= 1;// Good luck allocating 2 ^ 30 elements
3.142 + }
3.143 + elements = (E[]) new Object[initialCapacity];
3.144 + }
3.145 +
3.146 + /**
3.147 + * Double the capacity of this deque. Call only when full, i.e.,
3.148 + * when head and tail have wrapped around to become equal.
3.149 + */
3.150 + private void doubleCapacity() {
3.151 + assert head == tail;
3.152 + int p = head;
3.153 + int n = elements.length;
3.154 + int r = n - p; // number of elements to the right of p
3.155 + int newCapacity = n << 1;
3.156 + if (newCapacity < 0)
3.157 + throw new IllegalStateException("Sorry, deque too big");
3.158 + Object[] a = new Object[newCapacity];
3.159 + System.arraycopy(elements, p, a, 0, r);
3.160 + System.arraycopy(elements, 0, a, r, p);
3.161 + elements = (E[])a;
3.162 + head = 0;
3.163 + tail = n;
3.164 + }
3.165 +
3.166 + /**
3.167 + * Copies the elements from our element array into the specified array,
3.168 + * in order (from first to last element in the deque). It is assumed
3.169 + * that the array is large enough to hold all elements in the deque.
3.170 + *
3.171 + * @return its argument
3.172 + */
3.173 + private <T> T[] copyElements(T[] a) {
3.174 + if (head < tail) {
3.175 + System.arraycopy(elements, head, a, 0, size());
3.176 + } else if (head > tail) {
3.177 + int headPortionLen = elements.length - head;
3.178 + System.arraycopy(elements, head, a, 0, headPortionLen);
3.179 + System.arraycopy(elements, 0, a, headPortionLen, tail);
3.180 + }
3.181 + return a;
3.182 + }
3.183 +
3.184 + /**
3.185 + * Constructs an empty array deque with an initial capacity
3.186 + * sufficient to hold 16 elements.
3.187 + */
3.188 + public ArrayDeque() {
3.189 + elements = (E[]) new Object[16];
3.190 + }
3.191 +
3.192 + /**
3.193 + * Constructs an empty array deque with an initial capacity
3.194 + * sufficient to hold the specified number of elements.
3.195 + *
3.196 + * @param numElements lower bound on initial capacity of the deque
3.197 + */
3.198 + public ArrayDeque(int numElements) {
3.199 + allocateElements(numElements);
3.200 + }
3.201 +
3.202 + /**
3.203 + * Constructs a deque containing the elements of the specified
3.204 + * collection, in the order they are returned by the collection's
3.205 + * iterator. (The first element returned by the collection's
3.206 + * iterator becomes the first element, or <i>front</i> of the
3.207 + * deque.)
3.208 + *
3.209 + * @param c the collection whose elements are to be placed into the deque
3.210 + * @throws NullPointerException if the specified collection is null
3.211 + */
3.212 + public ArrayDeque(Collection<? extends E> c) {
3.213 + allocateElements(c.size());
3.214 + addAll(c);
3.215 + }
3.216 +
3.217 + // The main insertion and extraction methods are addFirst,
3.218 + // addLast, pollFirst, pollLast. The other methods are defined in
3.219 + // terms of these.
3.220 +
3.221 + /**
3.222 + * Inserts the specified element at the front of this deque.
3.223 + *
3.224 + * @param e the element to add
3.225 + * @throws NullPointerException if the specified element is null
3.226 + */
3.227 + public void addFirst(E e) {
3.228 + if (e == null)
3.229 + throw new NullPointerException();
3.230 + elements[head = (head - 1) & (elements.length - 1)] = e;
3.231 + if (head == tail)
3.232 + doubleCapacity();
3.233 + }
3.234 +
3.235 + /**
3.236 + * Inserts the specified element at the end of this deque.
3.237 + *
3.238 + * <p>This method is equivalent to {@link #add}.
3.239 + *
3.240 + * @param e the element to add
3.241 + * @throws NullPointerException if the specified element is null
3.242 + */
3.243 + public void addLast(E e) {
3.244 + if (e == null)
3.245 + throw new NullPointerException();
3.246 + elements[tail] = e;
3.247 + if ( (tail = (tail + 1) & (elements.length - 1)) == head)
3.248 + doubleCapacity();
3.249 + }
3.250 +
3.251 + /**
3.252 + * Inserts the specified element at the front of this deque.
3.253 + *
3.254 + * @param e the element to add
3.255 + * @return <tt>true</tt> (as specified by {@link Deque#offerFirst})
3.256 + * @throws NullPointerException if the specified element is null
3.257 + */
3.258 + public boolean offerFirst(E e) {
3.259 + addFirst(e);
3.260 + return true;
3.261 + }
3.262 +
3.263 + /**
3.264 + * Inserts the specified element at the end of this deque.
3.265 + *
3.266 + * @param e the element to add
3.267 + * @return <tt>true</tt> (as specified by {@link Deque#offerLast})
3.268 + * @throws NullPointerException if the specified element is null
3.269 + */
3.270 + public boolean offerLast(E e) {
3.271 + addLast(e);
3.272 + return true;
3.273 + }
3.274 +
3.275 + /**
3.276 + * @throws NoSuchElementException {@inheritDoc}
3.277 + */
3.278 + public E removeFirst() {
3.279 + E x = pollFirst();
3.280 + if (x == null)
3.281 + throw new NoSuchElementException();
3.282 + return x;
3.283 + }
3.284 +
3.285 + /**
3.286 + * @throws NoSuchElementException {@inheritDoc}
3.287 + */
3.288 + public E removeLast() {
3.289 + E x = pollLast();
3.290 + if (x == null)
3.291 + throw new NoSuchElementException();
3.292 + return x;
3.293 + }
3.294 +
3.295 + public E pollFirst() {
3.296 + int h = head;
3.297 + E result = elements[h]; // Element is null if deque empty
3.298 + if (result == null)
3.299 + return null;
3.300 + elements[h] = null; // Must null out slot
3.301 + head = (h + 1) & (elements.length - 1);
3.302 + return result;
3.303 + }
3.304 +
3.305 + public E pollLast() {
3.306 + int t = (tail - 1) & (elements.length - 1);
3.307 + E result = elements[t];
3.308 + if (result == null)
3.309 + return null;
3.310 + elements[t] = null;
3.311 + tail = t;
3.312 + return result;
3.313 + }
3.314 +
3.315 + /**
3.316 + * @throws NoSuchElementException {@inheritDoc}
3.317 + */
3.318 + public E getFirst() {
3.319 + E x = elements[head];
3.320 + if (x == null)
3.321 + throw new NoSuchElementException();
3.322 + return x;
3.323 + }
3.324 +
3.325 + /**
3.326 + * @throws NoSuchElementException {@inheritDoc}
3.327 + */
3.328 + public E getLast() {
3.329 + E x = elements[(tail - 1) & (elements.length - 1)];
3.330 + if (x == null)
3.331 + throw new NoSuchElementException();
3.332 + return x;
3.333 + }
3.334 +
3.335 + public E peekFirst() {
3.336 + return elements[head]; // elements[head] is null if deque empty
3.337 + }
3.338 +
3.339 + public E peekLast() {
3.340 + return elements[(tail - 1) & (elements.length - 1)];
3.341 + }
3.342 +
3.343 + /**
3.344 + * Removes the first occurrence of the specified element in this
3.345 + * deque (when traversing the deque from head to tail).
3.346 + * If the deque does not contain the element, it is unchanged.
3.347 + * More formally, removes the first element <tt>e</tt> such that
3.348 + * <tt>o.equals(e)</tt> (if such an element exists).
3.349 + * Returns <tt>true</tt> if this deque contained the specified element
3.350 + * (or equivalently, if this deque changed as a result of the call).
3.351 + *
3.352 + * @param o element to be removed from this deque, if present
3.353 + * @return <tt>true</tt> if the deque contained the specified element
3.354 + */
3.355 + public boolean removeFirstOccurrence(Object o) {
3.356 + if (o == null)
3.357 + return false;
3.358 + int mask = elements.length - 1;
3.359 + int i = head;
3.360 + E x;
3.361 + while ( (x = elements[i]) != null) {
3.362 + if (o.equals(x)) {
3.363 + delete(i);
3.364 + return true;
3.365 + }
3.366 + i = (i + 1) & mask;
3.367 + }
3.368 + return false;
3.369 + }
3.370 +
3.371 + /**
3.372 + * Removes the last occurrence of the specified element in this
3.373 + * deque (when traversing the deque from head to tail).
3.374 + * If the deque does not contain the element, it is unchanged.
3.375 + * More formally, removes the last element <tt>e</tt> such that
3.376 + * <tt>o.equals(e)</tt> (if such an element exists).
3.377 + * Returns <tt>true</tt> if this deque contained the specified element
3.378 + * (or equivalently, if this deque changed as a result of the call).
3.379 + *
3.380 + * @param o element to be removed from this deque, if present
3.381 + * @return <tt>true</tt> if the deque contained the specified element
3.382 + */
3.383 + public boolean removeLastOccurrence(Object o) {
3.384 + if (o == null)
3.385 + return false;
3.386 + int mask = elements.length - 1;
3.387 + int i = (tail - 1) & mask;
3.388 + E x;
3.389 + while ( (x = elements[i]) != null) {
3.390 + if (o.equals(x)) {
3.391 + delete(i);
3.392 + return true;
3.393 + }
3.394 + i = (i - 1) & mask;
3.395 + }
3.396 + return false;
3.397 + }
3.398 +
3.399 + // *** Queue methods ***
3.400 +
3.401 + /**
3.402 + * Inserts the specified element at the end of this deque.
3.403 + *
3.404 + * <p>This method is equivalent to {@link #addLast}.
3.405 + *
3.406 + * @param e the element to add
3.407 + * @return <tt>true</tt> (as specified by {@link Collection#add})
3.408 + * @throws NullPointerException if the specified element is null
3.409 + */
3.410 + public boolean add(E e) {
3.411 + addLast(e);
3.412 + return true;
3.413 + }
3.414 +
3.415 + /**
3.416 + * Inserts the specified element at the end of this deque.
3.417 + *
3.418 + * <p>This method is equivalent to {@link #offerLast}.
3.419 + *
3.420 + * @param e the element to add
3.421 + * @return <tt>true</tt> (as specified by {@link Queue#offer})
3.422 + * @throws NullPointerException if the specified element is null
3.423 + */
3.424 + public boolean offer(E e) {
3.425 + return offerLast(e);
3.426 + }
3.427 +
3.428 + /**
3.429 + * Retrieves and removes the head of the queue represented by this deque.
3.430 + *
3.431 + * This method differs from {@link #poll poll} only in that it throws an
3.432 + * exception if this deque is empty.
3.433 + *
3.434 + * <p>This method is equivalent to {@link #removeFirst}.
3.435 + *
3.436 + * @return the head of the queue represented by this deque
3.437 + * @throws NoSuchElementException {@inheritDoc}
3.438 + */
3.439 + public E remove() {
3.440 + return removeFirst();
3.441 + }
3.442 +
3.443 + /**
3.444 + * Retrieves and removes the head of the queue represented by this deque
3.445 + * (in other words, the first element of this deque), or returns
3.446 + * <tt>null</tt> if this deque is empty.
3.447 + *
3.448 + * <p>This method is equivalent to {@link #pollFirst}.
3.449 + *
3.450 + * @return the head of the queue represented by this deque, or
3.451 + * <tt>null</tt> if this deque is empty
3.452 + */
3.453 + public E poll() {
3.454 + return pollFirst();
3.455 + }
3.456 +
3.457 + /**
3.458 + * Retrieves, but does not remove, the head of the queue represented by
3.459 + * this deque. This method differs from {@link #peek peek} only in
3.460 + * that it throws an exception if this deque is empty.
3.461 + *
3.462 + * <p>This method is equivalent to {@link #getFirst}.
3.463 + *
3.464 + * @return the head of the queue represented by this deque
3.465 + * @throws NoSuchElementException {@inheritDoc}
3.466 + */
3.467 + public E element() {
3.468 + return getFirst();
3.469 + }
3.470 +
3.471 + /**
3.472 + * Retrieves, but does not remove, the head of the queue represented by
3.473 + * this deque, or returns <tt>null</tt> if this deque is empty.
3.474 + *
3.475 + * <p>This method is equivalent to {@link #peekFirst}.
3.476 + *
3.477 + * @return the head of the queue represented by this deque, or
3.478 + * <tt>null</tt> if this deque is empty
3.479 + */
3.480 + public E peek() {
3.481 + return peekFirst();
3.482 + }
3.483 +
3.484 + // *** Stack methods ***
3.485 +
3.486 + /**
3.487 + * Pushes an element onto the stack represented by this deque. In other
3.488 + * words, inserts the element at the front of this deque.
3.489 + *
3.490 + * <p>This method is equivalent to {@link #addFirst}.
3.491 + *
3.492 + * @param e the element to push
3.493 + * @throws NullPointerException if the specified element is null
3.494 + */
3.495 + public void push(E e) {
3.496 + addFirst(e);
3.497 + }
3.498 +
3.499 + /**
3.500 + * Pops an element from the stack represented by this deque. In other
3.501 + * words, removes and returns the first element of this deque.
3.502 + *
3.503 + * <p>This method is equivalent to {@link #removeFirst()}.
3.504 + *
3.505 + * @return the element at the front of this deque (which is the top
3.506 + * of the stack represented by this deque)
3.507 + * @throws NoSuchElementException {@inheritDoc}
3.508 + */
3.509 + public E pop() {
3.510 + return removeFirst();
3.511 + }
3.512 +
3.513 + private void checkInvariants() {
3.514 + assert elements[tail] == null;
3.515 + assert head == tail ? elements[head] == null :
3.516 + (elements[head] != null &&
3.517 + elements[(tail - 1) & (elements.length - 1)] != null);
3.518 + assert elements[(head - 1) & (elements.length - 1)] == null;
3.519 + }
3.520 +
3.521 + /**
3.522 + * Removes the element at the specified position in the elements array,
3.523 + * adjusting head and tail as necessary. This can result in motion of
3.524 + * elements backwards or forwards in the array.
3.525 + *
3.526 + * <p>This method is called delete rather than remove to emphasize
3.527 + * that its semantics differ from those of {@link List#remove(int)}.
3.528 + *
3.529 + * @return true if elements moved backwards
3.530 + */
3.531 + private boolean delete(int i) {
3.532 + checkInvariants();
3.533 + final E[] elements = this.elements;
3.534 + final int mask = elements.length - 1;
3.535 + final int h = head;
3.536 + final int t = tail;
3.537 + final int front = (i - h) & mask;
3.538 + final int back = (t - i) & mask;
3.539 +
3.540 + // Invariant: head <= i < tail mod circularity
3.541 + if (front >= ((t - h) & mask))
3.542 + throw new ConcurrentModificationException();
3.543 +
3.544 + // Optimize for least element motion
3.545 + if (front < back) {
3.546 + if (h <= i) {
3.547 + System.arraycopy(elements, h, elements, h + 1, front);
3.548 + } else { // Wrap around
3.549 + System.arraycopy(elements, 0, elements, 1, i);
3.550 + elements[0] = elements[mask];
3.551 + System.arraycopy(elements, h, elements, h + 1, mask - h);
3.552 + }
3.553 + elements[h] = null;
3.554 + head = (h + 1) & mask;
3.555 + return false;
3.556 + } else {
3.557 + if (i < t) { // Copy the null tail as well
3.558 + System.arraycopy(elements, i + 1, elements, i, back);
3.559 + tail = t - 1;
3.560 + } else { // Wrap around
3.561 + System.arraycopy(elements, i + 1, elements, i, mask - i);
3.562 + elements[mask] = elements[0];
3.563 + System.arraycopy(elements, 1, elements, 0, t);
3.564 + tail = (t - 1) & mask;
3.565 + }
3.566 + return true;
3.567 + }
3.568 + }
3.569 +
3.570 + // *** Collection Methods ***
3.571 +
3.572 + /**
3.573 + * Returns the number of elements in this deque.
3.574 + *
3.575 + * @return the number of elements in this deque
3.576 + */
3.577 + public int size() {
3.578 + return (tail - head) & (elements.length - 1);
3.579 + }
3.580 +
3.581 + /**
3.582 + * Returns <tt>true</tt> if this deque contains no elements.
3.583 + *
3.584 + * @return <tt>true</tt> if this deque contains no elements
3.585 + */
3.586 + public boolean isEmpty() {
3.587 + return head == tail;
3.588 + }
3.589 +
3.590 + /**
3.591 + * Returns an iterator over the elements in this deque. The elements
3.592 + * will be ordered from first (head) to last (tail). This is the same
3.593 + * order that elements would be dequeued (via successive calls to
3.594 + * {@link #remove} or popped (via successive calls to {@link #pop}).
3.595 + *
3.596 + * @return an iterator over the elements in this deque
3.597 + */
3.598 + public Iterator<E> iterator() {
3.599 + return new DeqIterator();
3.600 + }
3.601 +
3.602 + public Iterator<E> descendingIterator() {
3.603 + return new DescendingIterator();
3.604 + }
3.605 +
3.606 + private class DeqIterator implements Iterator<E> {
3.607 + /**
3.608 + * Index of element to be returned by subsequent call to next.
3.609 + */
3.610 + private int cursor = head;
3.611 +
3.612 + /**
3.613 + * Tail recorded at construction (also in remove), to stop
3.614 + * iterator and also to check for comodification.
3.615 + */
3.616 + private int fence = tail;
3.617 +
3.618 + /**
3.619 + * Index of element returned by most recent call to next.
3.620 + * Reset to -1 if element is deleted by a call to remove.
3.621 + */
3.622 + private int lastRet = -1;
3.623 +
3.624 + public boolean hasNext() {
3.625 + return cursor != fence;
3.626 + }
3.627 +
3.628 + public E next() {
3.629 + if (cursor == fence)
3.630 + throw new NoSuchElementException();
3.631 + E result = elements[cursor];
3.632 + // This check doesn't catch all possible comodifications,
3.633 + // but does catch the ones that corrupt traversal
3.634 + if (tail != fence || result == null)
3.635 + throw new ConcurrentModificationException();
3.636 + lastRet = cursor;
3.637 + cursor = (cursor + 1) & (elements.length - 1);
3.638 + return result;
3.639 + }
3.640 +
3.641 + public void remove() {
3.642 + if (lastRet < 0)
3.643 + throw new IllegalStateException();
3.644 + if (delete(lastRet)) { // if left-shifted, undo increment in next()
3.645 + cursor = (cursor - 1) & (elements.length - 1);
3.646 + fence = tail;
3.647 + }
3.648 + lastRet = -1;
3.649 + }
3.650 + }
3.651 +
3.652 + private class DescendingIterator implements Iterator<E> {
3.653 + /*
3.654 + * This class is nearly a mirror-image of DeqIterator, using
3.655 + * tail instead of head for initial cursor, and head instead of
3.656 + * tail for fence.
3.657 + */
3.658 + private int cursor = tail;
3.659 + private int fence = head;
3.660 + private int lastRet = -1;
3.661 +
3.662 + public boolean hasNext() {
3.663 + return cursor != fence;
3.664 + }
3.665 +
3.666 + public E next() {
3.667 + if (cursor == fence)
3.668 + throw new NoSuchElementException();
3.669 + cursor = (cursor - 1) & (elements.length - 1);
3.670 + E result = elements[cursor];
3.671 + if (head != fence || result == null)
3.672 + throw new ConcurrentModificationException();
3.673 + lastRet = cursor;
3.674 + return result;
3.675 + }
3.676 +
3.677 + public void remove() {
3.678 + if (lastRet < 0)
3.679 + throw new IllegalStateException();
3.680 + if (!delete(lastRet)) {
3.681 + cursor = (cursor + 1) & (elements.length - 1);
3.682 + fence = head;
3.683 + }
3.684 + lastRet = -1;
3.685 + }
3.686 + }
3.687 +
3.688 + /**
3.689 + * Returns <tt>true</tt> if this deque contains the specified element.
3.690 + * More formally, returns <tt>true</tt> if and only if this deque contains
3.691 + * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>.
3.692 + *
3.693 + * @param o object to be checked for containment in this deque
3.694 + * @return <tt>true</tt> if this deque contains the specified element
3.695 + */
3.696 + public boolean contains(Object o) {
3.697 + if (o == null)
3.698 + return false;
3.699 + int mask = elements.length - 1;
3.700 + int i = head;
3.701 + E x;
3.702 + while ( (x = elements[i]) != null) {
3.703 + if (o.equals(x))
3.704 + return true;
3.705 + i = (i + 1) & mask;
3.706 + }
3.707 + return false;
3.708 + }
3.709 +
3.710 + /**
3.711 + * Removes a single instance of the specified element from this deque.
3.712 + * If the deque does not contain the element, it is unchanged.
3.713 + * More formally, removes the first element <tt>e</tt> such that
3.714 + * <tt>o.equals(e)</tt> (if such an element exists).
3.715 + * Returns <tt>true</tt> if this deque contained the specified element
3.716 + * (or equivalently, if this deque changed as a result of the call).
3.717 + *
3.718 + * <p>This method is equivalent to {@link #removeFirstOccurrence}.
3.719 + *
3.720 + * @param o element to be removed from this deque, if present
3.721 + * @return <tt>true</tt> if this deque contained the specified element
3.722 + */
3.723 + public boolean remove(Object o) {
3.724 + return removeFirstOccurrence(o);
3.725 + }
3.726 +
3.727 + /**
3.728 + * Removes all of the elements from this deque.
3.729 + * The deque will be empty after this call returns.
3.730 + */
3.731 + public void clear() {
3.732 + int h = head;
3.733 + int t = tail;
3.734 + if (h != t) { // clear all cells
3.735 + head = tail = 0;
3.736 + int i = h;
3.737 + int mask = elements.length - 1;
3.738 + do {
3.739 + elements[i] = null;
3.740 + i = (i + 1) & mask;
3.741 + } while (i != t);
3.742 + }
3.743 + }
3.744 +
3.745 + /**
3.746 + * Returns an array containing all of the elements in this deque
3.747 + * in proper sequence (from first to last element).
3.748 + *
3.749 + * <p>The returned array will be "safe" in that no references to it are
3.750 + * maintained by this deque. (In other words, this method must allocate
3.751 + * a new array). The caller is thus free to modify the returned array.
3.752 + *
3.753 + * <p>This method acts as bridge between array-based and collection-based
3.754 + * APIs.
3.755 + *
3.756 + * @return an array containing all of the elements in this deque
3.757 + */
3.758 + public Object[] toArray() {
3.759 + return copyElements(new Object[size()]);
3.760 + }
3.761 +
3.762 + /**
3.763 + * Returns an array containing all of the elements in this deque in
3.764 + * proper sequence (from first to last element); the runtime type of the
3.765 + * returned array is that of the specified array. If the deque fits in
3.766 + * the specified array, it is returned therein. Otherwise, a new array
3.767 + * is allocated with the runtime type of the specified array and the
3.768 + * size of this deque.
3.769 + *
3.770 + * <p>If this deque fits in the specified array with room to spare
3.771 + * (i.e., the array has more elements than this deque), the element in
3.772 + * the array immediately following the end of the deque is set to
3.773 + * <tt>null</tt>.
3.774 + *
3.775 + * <p>Like the {@link #toArray()} method, this method acts as bridge between
3.776 + * array-based and collection-based APIs. Further, this method allows
3.777 + * precise control over the runtime type of the output array, and may,
3.778 + * under certain circumstances, be used to save allocation costs.
3.779 + *
3.780 + * <p>Suppose <tt>x</tt> is a deque known to contain only strings.
3.781 + * The following code can be used to dump the deque into a newly
3.782 + * allocated array of <tt>String</tt>:
3.783 + *
3.784 + * <pre>
3.785 + * String[] y = x.toArray(new String[0]);</pre>
3.786 + *
3.787 + * Note that <tt>toArray(new Object[0])</tt> is identical in function to
3.788 + * <tt>toArray()</tt>.
3.789 + *
3.790 + * @param a the array into which the elements of the deque are to
3.791 + * be stored, if it is big enough; otherwise, a new array of the
3.792 + * same runtime type is allocated for this purpose
3.793 + * @return an array containing all of the elements in this deque
3.794 + * @throws ArrayStoreException if the runtime type of the specified array
3.795 + * is not a supertype of the runtime type of every element in
3.796 + * this deque
3.797 + * @throws NullPointerException if the specified array is null
3.798 + */
3.799 + public <T> T[] toArray(T[] a) {
3.800 + int size = size();
3.801 + if (a.length < size)
3.802 + a = (T[])java.lang.reflect.Array.newInstance(
3.803 + a.getClass().getComponentType(), size);
3.804 + copyElements(a);
3.805 + if (a.length > size)
3.806 + a[size] = null;
3.807 + return a;
3.808 + }
3.809 +
3.810 + // *** Object methods ***
3.811 +
3.812 + /**
3.813 + * Returns a copy of this deque.
3.814 + *
3.815 + * @return a copy of this deque
3.816 + */
3.817 + public ArrayDeque<E> clone() {
3.818 + try {
3.819 + ArrayDeque<E> result = (ArrayDeque<E>) super.clone();
3.820 + result.elements = Arrays.copyOf(elements, elements.length);
3.821 + return result;
3.822 +
3.823 + } catch (CloneNotSupportedException e) {
3.824 + throw new AssertionError();
3.825 + }
3.826 + }
3.827 +
3.828 + /**
3.829 + * Appease the serialization gods.
3.830 + */
3.831 + private static final long serialVersionUID = 2340985798034038923L;
3.832 +
3.833 + /**
3.834 + * Serialize this deque.
3.835 + *
3.836 + * @serialData The current size (<tt>int</tt>) of the deque,
3.837 + * followed by all of its elements (each an object reference) in
3.838 + * first-to-last order.
3.839 + */
3.840 + private void writeObject(ObjectOutputStream s) throws IOException {
3.841 + s.defaultWriteObject();
3.842 +
3.843 + // Write out size
3.844 + s.writeInt(size());
3.845 +
3.846 + // Write out elements in order.
3.847 + int mask = elements.length - 1;
3.848 + for (int i = head; i != tail; i = (i + 1) & mask)
3.849 + s.writeObject(elements[i]);
3.850 + }
3.851 +
3.852 + /**
3.853 + * Deserialize this deque.
3.854 + */
3.855 + private void readObject(ObjectInputStream s)
3.856 + throws IOException, ClassNotFoundException {
3.857 + s.defaultReadObject();
3.858 +
3.859 + // Read in size and allocate array
3.860 + int size = s.readInt();
3.861 + allocateElements(size);
3.862 + head = 0;
3.863 + tail = size;
3.864 +
3.865 + // Read in all elements in the proper order.
3.866 + for (int i = 0; i < size; i++)
3.867 + elements[i] = (E)s.readObject();
3.868 + }
3.869 +}
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/emul/compact/src/main/java/java/util/Collections.java Mon Jan 28 13:28:02 2013 +0100
4.3 @@ -0,0 +1,3966 @@
4.4 +/*
4.5 + * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
4.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4.7 + *
4.8 + * This code is free software; you can redistribute it and/or modify it
4.9 + * under the terms of the GNU General Public License version 2 only, as
4.10 + * published by the Free Software Foundation. Oracle designates this
4.11 + * particular file as subject to the "Classpath" exception as provided
4.12 + * by Oracle in the LICENSE file that accompanied this code.
4.13 + *
4.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
4.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
4.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
4.17 + * version 2 for more details (a copy is included in the LICENSE file that
4.18 + * accompanied this code).
4.19 + *
4.20 + * You should have received a copy of the GNU General Public License version
4.21 + * 2 along with this work; if not, write to the Free Software Foundation,
4.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
4.23 + *
4.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
4.25 + * or visit www.oracle.com if you need additional information or have any
4.26 + * questions.
4.27 + */
4.28 +
4.29 +package java.util;
4.30 +import java.io.Serializable;
4.31 +import java.io.ObjectOutputStream;
4.32 +import java.io.IOException;
4.33 +import java.lang.reflect.Array;
4.34 +
4.35 +/**
4.36 + * This class consists exclusively of static methods that operate on or return
4.37 + * collections. It contains polymorphic algorithms that operate on
4.38 + * collections, "wrappers", which return a new collection backed by a
4.39 + * specified collection, and a few other odds and ends.
4.40 + *
4.41 + * <p>The methods of this class all throw a <tt>NullPointerException</tt>
4.42 + * if the collections or class objects provided to them are null.
4.43 + *
4.44 + * <p>The documentation for the polymorphic algorithms contained in this class
4.45 + * generally includes a brief description of the <i>implementation</i>. Such
4.46 + * descriptions should be regarded as <i>implementation notes</i>, rather than
4.47 + * parts of the <i>specification</i>. Implementors should feel free to
4.48 + * substitute other algorithms, so long as the specification itself is adhered
4.49 + * to. (For example, the algorithm used by <tt>sort</tt> does not have to be
4.50 + * a mergesort, but it does have to be <i>stable</i>.)
4.51 + *
4.52 + * <p>The "destructive" algorithms contained in this class, that is, the
4.53 + * algorithms that modify the collection on which they operate, are specified
4.54 + * to throw <tt>UnsupportedOperationException</tt> if the collection does not
4.55 + * support the appropriate mutation primitive(s), such as the <tt>set</tt>
4.56 + * method. These algorithms may, but are not required to, throw this
4.57 + * exception if an invocation would have no effect on the collection. For
4.58 + * example, invoking the <tt>sort</tt> method on an unmodifiable list that is
4.59 + * already sorted may or may not throw <tt>UnsupportedOperationException</tt>.
4.60 + *
4.61 + * <p>This class is a member of the
4.62 + * <a href="{@docRoot}/../technotes/guides/collections/index.html">
4.63 + * Java Collections Framework</a>.
4.64 + *
4.65 + * @author Josh Bloch
4.66 + * @author Neal Gafter
4.67 + * @see Collection
4.68 + * @see Set
4.69 + * @see List
4.70 + * @see Map
4.71 + * @since 1.2
4.72 + */
4.73 +
4.74 +public class Collections {
4.75 + // Suppresses default constructor, ensuring non-instantiability.
4.76 + private Collections() {
4.77 + }
4.78 +
4.79 + // Algorithms
4.80 +
4.81 + /*
4.82 + * Tuning parameters for algorithms - Many of the List algorithms have
4.83 + * two implementations, one of which is appropriate for RandomAccess
4.84 + * lists, the other for "sequential." Often, the random access variant
4.85 + * yields better performance on small sequential access lists. The
4.86 + * tuning parameters below determine the cutoff point for what constitutes
4.87 + * a "small" sequential access list for each algorithm. The values below
4.88 + * were empirically determined to work well for LinkedList. Hopefully
4.89 + * they should be reasonable for other sequential access List
4.90 + * implementations. Those doing performance work on this code would
4.91 + * do well to validate the values of these parameters from time to time.
4.92 + * (The first word of each tuning parameter name is the algorithm to which
4.93 + * it applies.)
4.94 + */
4.95 + private static final int BINARYSEARCH_THRESHOLD = 5000;
4.96 + private static final int REVERSE_THRESHOLD = 18;
4.97 + private static final int SHUFFLE_THRESHOLD = 5;
4.98 + private static final int FILL_THRESHOLD = 25;
4.99 + private static final int ROTATE_THRESHOLD = 100;
4.100 + private static final int COPY_THRESHOLD = 10;
4.101 + private static final int REPLACEALL_THRESHOLD = 11;
4.102 + private static final int INDEXOFSUBLIST_THRESHOLD = 35;
4.103 +
4.104 + /**
4.105 + * Sorts the specified list into ascending order, according to the
4.106 + * {@linkplain Comparable natural ordering} of its elements.
4.107 + * All elements in the list must implement the {@link Comparable}
4.108 + * interface. Furthermore, all elements in the list must be
4.109 + * <i>mutually comparable</i> (that is, {@code e1.compareTo(e2)}
4.110 + * must not throw a {@code ClassCastException} for any elements
4.111 + * {@code e1} and {@code e2} in the list).
4.112 + *
4.113 + * <p>This sort is guaranteed to be <i>stable</i>: equal elements will
4.114 + * not be reordered as a result of the sort.
4.115 + *
4.116 + * <p>The specified list must be modifiable, but need not be resizable.
4.117 + *
4.118 + * <p>Implementation note: This implementation is a stable, adaptive,
4.119 + * iterative mergesort that requires far fewer than n lg(n) comparisons
4.120 + * when the input array is partially sorted, while offering the
4.121 + * performance of a traditional mergesort when the input array is
4.122 + * randomly ordered. If the input array is nearly sorted, the
4.123 + * implementation requires approximately n comparisons. Temporary
4.124 + * storage requirements vary from a small constant for nearly sorted
4.125 + * input arrays to n/2 object references for randomly ordered input
4.126 + * arrays.
4.127 + *
4.128 + * <p>The implementation takes equal advantage of ascending and
4.129 + * descending order in its input array, and can take advantage of
4.130 + * ascending and descending order in different parts of the same
4.131 + * input array. It is well-suited to merging two or more sorted arrays:
4.132 + * simply concatenate the arrays and sort the resulting array.
4.133 + *
4.134 + * <p>The implementation was adapted from Tim Peters's list sort for Python
4.135 + * (<a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt">
4.136 + * TimSort</a>). It uses techiques from Peter McIlroy's "Optimistic
4.137 + * Sorting and Information Theoretic Complexity", in Proceedings of the
4.138 + * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
4.139 + * January 1993.
4.140 + *
4.141 + * <p>This implementation dumps the specified list into an array, sorts
4.142 + * the array, and iterates over the list resetting each element
4.143 + * from the corresponding position in the array. This avoids the
4.144 + * n<sup>2</sup> log(n) performance that would result from attempting
4.145 + * to sort a linked list in place.
4.146 + *
4.147 + * @param list the list to be sorted.
4.148 + * @throws ClassCastException if the list contains elements that are not
4.149 + * <i>mutually comparable</i> (for example, strings and integers).
4.150 + * @throws UnsupportedOperationException if the specified list's
4.151 + * list-iterator does not support the {@code set} operation.
4.152 + * @throws IllegalArgumentException (optional) if the implementation
4.153 + * detects that the natural ordering of the list elements is
4.154 + * found to violate the {@link Comparable} contract
4.155 + */
4.156 + public static <T extends Comparable<? super T>> void sort(List<T> list) {
4.157 + Object[] a = list.toArray();
4.158 + Arrays.sort(a);
4.159 + ListIterator<T> i = list.listIterator();
4.160 + for (int j=0; j<a.length; j++) {
4.161 + i.next();
4.162 + i.set((T)a[j]);
4.163 + }
4.164 + }
4.165 +
4.166 + /**
4.167 + * Sorts the specified list according to the order induced by the
4.168 + * specified comparator. All elements in the list must be <i>mutually
4.169 + * comparable</i> using the specified comparator (that is,
4.170 + * {@code c.compare(e1, e2)} must not throw a {@code ClassCastException}
4.171 + * for any elements {@code e1} and {@code e2} in the list).
4.172 + *
4.173 + * <p>This sort is guaranteed to be <i>stable</i>: equal elements will
4.174 + * not be reordered as a result of the sort.
4.175 + *
4.176 + * <p>The specified list must be modifiable, but need not be resizable.
4.177 + *
4.178 + * <p>Implementation note: This implementation is a stable, adaptive,
4.179 + * iterative mergesort that requires far fewer than n lg(n) comparisons
4.180 + * when the input array is partially sorted, while offering the
4.181 + * performance of a traditional mergesort when the input array is
4.182 + * randomly ordered. If the input array is nearly sorted, the
4.183 + * implementation requires approximately n comparisons. Temporary
4.184 + * storage requirements vary from a small constant for nearly sorted
4.185 + * input arrays to n/2 object references for randomly ordered input
4.186 + * arrays.
4.187 + *
4.188 + * <p>The implementation takes equal advantage of ascending and
4.189 + * descending order in its input array, and can take advantage of
4.190 + * ascending and descending order in different parts of the same
4.191 + * input array. It is well-suited to merging two or more sorted arrays:
4.192 + * simply concatenate the arrays and sort the resulting array.
4.193 + *
4.194 + * <p>The implementation was adapted from Tim Peters's list sort for Python
4.195 + * (<a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt">
4.196 + * TimSort</a>). It uses techiques from Peter McIlroy's "Optimistic
4.197 + * Sorting and Information Theoretic Complexity", in Proceedings of the
4.198 + * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
4.199 + * January 1993.
4.200 + *
4.201 + * <p>This implementation dumps the specified list into an array, sorts
4.202 + * the array, and iterates over the list resetting each element
4.203 + * from the corresponding position in the array. This avoids the
4.204 + * n<sup>2</sup> log(n) performance that would result from attempting
4.205 + * to sort a linked list in place.
4.206 + *
4.207 + * @param list the list to be sorted.
4.208 + * @param c the comparator to determine the order of the list. A
4.209 + * {@code null} value indicates that the elements' <i>natural
4.210 + * ordering</i> should be used.
4.211 + * @throws ClassCastException if the list contains elements that are not
4.212 + * <i>mutually comparable</i> using the specified comparator.
4.213 + * @throws UnsupportedOperationException if the specified list's
4.214 + * list-iterator does not support the {@code set} operation.
4.215 + * @throws IllegalArgumentException (optional) if the comparator is
4.216 + * found to violate the {@link Comparator} contract
4.217 + */
4.218 + public static <T> void sort(List<T> list, Comparator<? super T> c) {
4.219 + Object[] a = list.toArray();
4.220 + Arrays.sort(a, (Comparator)c);
4.221 + ListIterator i = list.listIterator();
4.222 + for (int j=0; j<a.length; j++) {
4.223 + i.next();
4.224 + i.set(a[j]);
4.225 + }
4.226 + }
4.227 +
4.228 +
4.229 + /**
4.230 + * Searches the specified list for the specified object using the binary
4.231 + * search algorithm. The list must be sorted into ascending order
4.232 + * according to the {@linkplain Comparable natural ordering} of its
4.233 + * elements (as by the {@link #sort(List)} method) prior to making this
4.234 + * call. If it is not sorted, the results are undefined. If the list
4.235 + * contains multiple elements equal to the specified object, there is no
4.236 + * guarantee which one will be found.
4.237 + *
4.238 + * <p>This method runs in log(n) time for a "random access" list (which
4.239 + * provides near-constant-time positional access). If the specified list
4.240 + * does not implement the {@link RandomAccess} interface and is large,
4.241 + * this method will do an iterator-based binary search that performs
4.242 + * O(n) link traversals and O(log n) element comparisons.
4.243 + *
4.244 + * @param list the list to be searched.
4.245 + * @param key the key to be searched for.
4.246 + * @return the index of the search key, if it is contained in the list;
4.247 + * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
4.248 + * <i>insertion point</i> is defined as the point at which the
4.249 + * key would be inserted into the list: the index of the first
4.250 + * element greater than the key, or <tt>list.size()</tt> if all
4.251 + * elements in the list are less than the specified key. Note
4.252 + * that this guarantees that the return value will be >= 0 if
4.253 + * and only if the key is found.
4.254 + * @throws ClassCastException if the list contains elements that are not
4.255 + * <i>mutually comparable</i> (for example, strings and
4.256 + * integers), or the search key is not mutually comparable
4.257 + * with the elements of the list.
4.258 + */
4.259 + public static <T>
4.260 + int binarySearch(List<? extends Comparable<? super T>> list, T key) {
4.261 + if (list instanceof RandomAccess || list.size()<BINARYSEARCH_THRESHOLD)
4.262 + return Collections.indexedBinarySearch(list, key);
4.263 + else
4.264 + return Collections.iteratorBinarySearch(list, key);
4.265 + }
4.266 +
4.267 + private static <T>
4.268 + int indexedBinarySearch(List<? extends Comparable<? super T>> list, T key)
4.269 + {
4.270 + int low = 0;
4.271 + int high = list.size()-1;
4.272 +
4.273 + while (low <= high) {
4.274 + int mid = (low + high) >>> 1;
4.275 + Comparable<? super T> midVal = list.get(mid);
4.276 + int cmp = midVal.compareTo(key);
4.277 +
4.278 + if (cmp < 0)
4.279 + low = mid + 1;
4.280 + else if (cmp > 0)
4.281 + high = mid - 1;
4.282 + else
4.283 + return mid; // key found
4.284 + }
4.285 + return -(low + 1); // key not found
4.286 + }
4.287 +
4.288 + private static <T>
4.289 + int iteratorBinarySearch(List<? extends Comparable<? super T>> list, T key)
4.290 + {
4.291 + int low = 0;
4.292 + int high = list.size()-1;
4.293 + ListIterator<? extends Comparable<? super T>> i = list.listIterator();
4.294 +
4.295 + while (low <= high) {
4.296 + int mid = (low + high) >>> 1;
4.297 + Comparable<? super T> midVal = get(i, mid);
4.298 + int cmp = midVal.compareTo(key);
4.299 +
4.300 + if (cmp < 0)
4.301 + low = mid + 1;
4.302 + else if (cmp > 0)
4.303 + high = mid - 1;
4.304 + else
4.305 + return mid; // key found
4.306 + }
4.307 + return -(low + 1); // key not found
4.308 + }
4.309 +
4.310 + /**
4.311 + * Gets the ith element from the given list by repositioning the specified
4.312 + * list listIterator.
4.313 + */
4.314 + private static <T> T get(ListIterator<? extends T> i, int index) {
4.315 + T obj = null;
4.316 + int pos = i.nextIndex();
4.317 + if (pos <= index) {
4.318 + do {
4.319 + obj = i.next();
4.320 + } while (pos++ < index);
4.321 + } else {
4.322 + do {
4.323 + obj = i.previous();
4.324 + } while (--pos > index);
4.325 + }
4.326 + return obj;
4.327 + }
4.328 +
4.329 + /**
4.330 + * Searches the specified list for the specified object using the binary
4.331 + * search algorithm. The list must be sorted into ascending order
4.332 + * according to the specified comparator (as by the
4.333 + * {@link #sort(List, Comparator) sort(List, Comparator)}
4.334 + * method), prior to making this call. If it is
4.335 + * not sorted, the results are undefined. If the list contains multiple
4.336 + * elements equal to the specified object, there is no guarantee which one
4.337 + * will be found.
4.338 + *
4.339 + * <p>This method runs in log(n) time for a "random access" list (which
4.340 + * provides near-constant-time positional access). If the specified list
4.341 + * does not implement the {@link RandomAccess} interface and is large,
4.342 + * this method will do an iterator-based binary search that performs
4.343 + * O(n) link traversals and O(log n) element comparisons.
4.344 + *
4.345 + * @param list the list to be searched.
4.346 + * @param key the key to be searched for.
4.347 + * @param c the comparator by which the list is ordered.
4.348 + * A <tt>null</tt> value indicates that the elements'
4.349 + * {@linkplain Comparable natural ordering} should be used.
4.350 + * @return the index of the search key, if it is contained in the list;
4.351 + * otherwise, <tt>(-(<i>insertion point</i>) - 1)</tt>. The
4.352 + * <i>insertion point</i> is defined as the point at which the
4.353 + * key would be inserted into the list: the index of the first
4.354 + * element greater than the key, or <tt>list.size()</tt> if all
4.355 + * elements in the list are less than the specified key. Note
4.356 + * that this guarantees that the return value will be >= 0 if
4.357 + * and only if the key is found.
4.358 + * @throws ClassCastException if the list contains elements that are not
4.359 + * <i>mutually comparable</i> using the specified comparator,
4.360 + * or the search key is not mutually comparable with the
4.361 + * elements of the list using this comparator.
4.362 + */
4.363 + public static <T> int binarySearch(List<? extends T> list, T key, Comparator<? super T> c) {
4.364 + if (c==null)
4.365 + return binarySearch((List) list, key);
4.366 +
4.367 + if (list instanceof RandomAccess || list.size()<BINARYSEARCH_THRESHOLD)
4.368 + return Collections.indexedBinarySearch(list, key, c);
4.369 + else
4.370 + return Collections.iteratorBinarySearch(list, key, c);
4.371 + }
4.372 +
4.373 + private static <T> int indexedBinarySearch(List<? extends T> l, T key, Comparator<? super T> c) {
4.374 + int low = 0;
4.375 + int high = l.size()-1;
4.376 +
4.377 + while (low <= high) {
4.378 + int mid = (low + high) >>> 1;
4.379 + T midVal = l.get(mid);
4.380 + int cmp = c.compare(midVal, key);
4.381 +
4.382 + if (cmp < 0)
4.383 + low = mid + 1;
4.384 + else if (cmp > 0)
4.385 + high = mid - 1;
4.386 + else
4.387 + return mid; // key found
4.388 + }
4.389 + return -(low + 1); // key not found
4.390 + }
4.391 +
4.392 + private static <T> int iteratorBinarySearch(List<? extends T> l, T key, Comparator<? super T> c) {
4.393 + int low = 0;
4.394 + int high = l.size()-1;
4.395 + ListIterator<? extends T> i = l.listIterator();
4.396 +
4.397 + while (low <= high) {
4.398 + int mid = (low + high) >>> 1;
4.399 + T midVal = get(i, mid);
4.400 + int cmp = c.compare(midVal, key);
4.401 +
4.402 + if (cmp < 0)
4.403 + low = mid + 1;
4.404 + else if (cmp > 0)
4.405 + high = mid - 1;
4.406 + else
4.407 + return mid; // key found
4.408 + }
4.409 + return -(low + 1); // key not found
4.410 + }
4.411 +
4.412 + private interface SelfComparable extends Comparable<SelfComparable> {}
4.413 +
4.414 +
4.415 + /**
4.416 + * Reverses the order of the elements in the specified list.<p>
4.417 + *
4.418 + * This method runs in linear time.
4.419 + *
4.420 + * @param list the list whose elements are to be reversed.
4.421 + * @throws UnsupportedOperationException if the specified list or
4.422 + * its list-iterator does not support the <tt>set</tt> operation.
4.423 + */
4.424 + public static void reverse(List<?> list) {
4.425 + int size = list.size();
4.426 + if (size < REVERSE_THRESHOLD || list instanceof RandomAccess) {
4.427 + for (int i=0, mid=size>>1, j=size-1; i<mid; i++, j--)
4.428 + swap(list, i, j);
4.429 + } else {
4.430 + ListIterator fwd = list.listIterator();
4.431 + ListIterator rev = list.listIterator(size);
4.432 + for (int i=0, mid=list.size()>>1; i<mid; i++) {
4.433 + Object tmp = fwd.next();
4.434 + fwd.set(rev.previous());
4.435 + rev.set(tmp);
4.436 + }
4.437 + }
4.438 + }
4.439 +
4.440 + /**
4.441 + * Randomly permutes the specified list using a default source of
4.442 + * randomness. All permutations occur with approximately equal
4.443 + * likelihood.<p>
4.444 + *
4.445 + * The hedge "approximately" is used in the foregoing description because
4.446 + * default source of randomness is only approximately an unbiased source
4.447 + * of independently chosen bits. If it were a perfect source of randomly
4.448 + * chosen bits, then the algorithm would choose permutations with perfect
4.449 + * uniformity.<p>
4.450 + *
4.451 + * This implementation traverses the list backwards, from the last element
4.452 + * up to the second, repeatedly swapping a randomly selected element into
4.453 + * the "current position". Elements are randomly selected from the
4.454 + * portion of the list that runs from the first element to the current
4.455 + * position, inclusive.<p>
4.456 + *
4.457 + * This method runs in linear time. If the specified list does not
4.458 + * implement the {@link RandomAccess} interface and is large, this
4.459 + * implementation dumps the specified list into an array before shuffling
4.460 + * it, and dumps the shuffled array back into the list. This avoids the
4.461 + * quadratic behavior that would result from shuffling a "sequential
4.462 + * access" list in place.
4.463 + *
4.464 + * @param list the list to be shuffled.
4.465 + * @throws UnsupportedOperationException if the specified list or
4.466 + * its list-iterator does not support the <tt>set</tt> operation.
4.467 + */
4.468 + public static void shuffle(List<?> list) {
4.469 + Random rnd = r;
4.470 + if (rnd == null)
4.471 + r = rnd = new Random();
4.472 + shuffle(list, rnd);
4.473 + }
4.474 + private static Random r;
4.475 +
4.476 + /**
4.477 + * Randomly permute the specified list using the specified source of
4.478 + * randomness. All permutations occur with equal likelihood
4.479 + * assuming that the source of randomness is fair.<p>
4.480 + *
4.481 + * This implementation traverses the list backwards, from the last element
4.482 + * up to the second, repeatedly swapping a randomly selected element into
4.483 + * the "current position". Elements are randomly selected from the
4.484 + * portion of the list that runs from the first element to the current
4.485 + * position, inclusive.<p>
4.486 + *
4.487 + * This method runs in linear time. If the specified list does not
4.488 + * implement the {@link RandomAccess} interface and is large, this
4.489 + * implementation dumps the specified list into an array before shuffling
4.490 + * it, and dumps the shuffled array back into the list. This avoids the
4.491 + * quadratic behavior that would result from shuffling a "sequential
4.492 + * access" list in place.
4.493 + *
4.494 + * @param list the list to be shuffled.
4.495 + * @param rnd the source of randomness to use to shuffle the list.
4.496 + * @throws UnsupportedOperationException if the specified list or its
4.497 + * list-iterator does not support the <tt>set</tt> operation.
4.498 + */
4.499 + public static void shuffle(List<?> list, Random rnd) {
4.500 + int size = list.size();
4.501 + if (size < SHUFFLE_THRESHOLD || list instanceof RandomAccess) {
4.502 + for (int i=size; i>1; i--)
4.503 + swap(list, i-1, rnd.nextInt(i));
4.504 + } else {
4.505 + Object arr[] = list.toArray();
4.506 +
4.507 + // Shuffle array
4.508 + for (int i=size; i>1; i--)
4.509 + swap(arr, i-1, rnd.nextInt(i));
4.510 +
4.511 + // Dump array back into list
4.512 + ListIterator it = list.listIterator();
4.513 + for (int i=0; i<arr.length; i++) {
4.514 + it.next();
4.515 + it.set(arr[i]);
4.516 + }
4.517 + }
4.518 + }
4.519 +
4.520 + /**
4.521 + * Swaps the elements at the specified positions in the specified list.
4.522 + * (If the specified positions are equal, invoking this method leaves
4.523 + * the list unchanged.)
4.524 + *
4.525 + * @param list The list in which to swap elements.
4.526 + * @param i the index of one element to be swapped.
4.527 + * @param j the index of the other element to be swapped.
4.528 + * @throws IndexOutOfBoundsException if either <tt>i</tt> or <tt>j</tt>
4.529 + * is out of range (i < 0 || i >= list.size()
4.530 + * || j < 0 || j >= list.size()).
4.531 + * @since 1.4
4.532 + */
4.533 + public static void swap(List<?> list, int i, int j) {
4.534 + final List l = list;
4.535 + l.set(i, l.set(j, l.get(i)));
4.536 + }
4.537 +
4.538 + /**
4.539 + * Swaps the two specified elements in the specified array.
4.540 + */
4.541 + private static void swap(Object[] arr, int i, int j) {
4.542 + Object tmp = arr[i];
4.543 + arr[i] = arr[j];
4.544 + arr[j] = tmp;
4.545 + }
4.546 +
4.547 + /**
4.548 + * Replaces all of the elements of the specified list with the specified
4.549 + * element. <p>
4.550 + *
4.551 + * This method runs in linear time.
4.552 + *
4.553 + * @param list the list to be filled with the specified element.
4.554 + * @param obj The element with which to fill the specified list.
4.555 + * @throws UnsupportedOperationException if the specified list or its
4.556 + * list-iterator does not support the <tt>set</tt> operation.
4.557 + */
4.558 + public static <T> void fill(List<? super T> list, T obj) {
4.559 + int size = list.size();
4.560 +
4.561 + if (size < FILL_THRESHOLD || list instanceof RandomAccess) {
4.562 + for (int i=0; i<size; i++)
4.563 + list.set(i, obj);
4.564 + } else {
4.565 + ListIterator<? super T> itr = list.listIterator();
4.566 + for (int i=0; i<size; i++) {
4.567 + itr.next();
4.568 + itr.set(obj);
4.569 + }
4.570 + }
4.571 + }
4.572 +
4.573 + /**
4.574 + * Copies all of the elements from one list into another. After the
4.575 + * operation, the index of each copied element in the destination list
4.576 + * will be identical to its index in the source list. The destination
4.577 + * list must be at least as long as the source list. If it is longer, the
4.578 + * remaining elements in the destination list are unaffected. <p>
4.579 + *
4.580 + * This method runs in linear time.
4.581 + *
4.582 + * @param dest The destination list.
4.583 + * @param src The source list.
4.584 + * @throws IndexOutOfBoundsException if the destination list is too small
4.585 + * to contain the entire source List.
4.586 + * @throws UnsupportedOperationException if the destination list's
4.587 + * list-iterator does not support the <tt>set</tt> operation.
4.588 + */
4.589 + public static <T> void copy(List<? super T> dest, List<? extends T> src) {
4.590 + int srcSize = src.size();
4.591 + if (srcSize > dest.size())
4.592 + throw new IndexOutOfBoundsException("Source does not fit in dest");
4.593 +
4.594 + if (srcSize < COPY_THRESHOLD ||
4.595 + (src instanceof RandomAccess && dest instanceof RandomAccess)) {
4.596 + for (int i=0; i<srcSize; i++)
4.597 + dest.set(i, src.get(i));
4.598 + } else {
4.599 + ListIterator<? super T> di=dest.listIterator();
4.600 + ListIterator<? extends T> si=src.listIterator();
4.601 + for (int i=0; i<srcSize; i++) {
4.602 + di.next();
4.603 + di.set(si.next());
4.604 + }
4.605 + }
4.606 + }
4.607 +
4.608 + /**
4.609 + * Returns the minimum element of the given collection, according to the
4.610 + * <i>natural ordering</i> of its elements. All elements in the
4.611 + * collection must implement the <tt>Comparable</tt> interface.
4.612 + * Furthermore, all elements in the collection must be <i>mutually
4.613 + * comparable</i> (that is, <tt>e1.compareTo(e2)</tt> must not throw a
4.614 + * <tt>ClassCastException</tt> for any elements <tt>e1</tt> and
4.615 + * <tt>e2</tt> in the collection).<p>
4.616 + *
4.617 + * This method iterates over the entire collection, hence it requires
4.618 + * time proportional to the size of the collection.
4.619 + *
4.620 + * @param coll the collection whose minimum element is to be determined.
4.621 + * @return the minimum element of the given collection, according
4.622 + * to the <i>natural ordering</i> of its elements.
4.623 + * @throws ClassCastException if the collection contains elements that are
4.624 + * not <i>mutually comparable</i> (for example, strings and
4.625 + * integers).
4.626 + * @throws NoSuchElementException if the collection is empty.
4.627 + * @see Comparable
4.628 + */
4.629 + public static <T extends Object & Comparable<? super T>> T min(Collection<? extends T> coll) {
4.630 + Iterator<? extends T> i = coll.iterator();
4.631 + T candidate = i.next();
4.632 +
4.633 + while (i.hasNext()) {
4.634 + T next = i.next();
4.635 + if (next.compareTo(candidate) < 0)
4.636 + candidate = next;
4.637 + }
4.638 + return candidate;
4.639 + }
4.640 +
4.641 + /**
4.642 + * Returns the minimum element of the given collection, according to the
4.643 + * order induced by the specified comparator. All elements in the
4.644 + * collection must be <i>mutually comparable</i> by the specified
4.645 + * comparator (that is, <tt>comp.compare(e1, e2)</tt> must not throw a
4.646 + * <tt>ClassCastException</tt> for any elements <tt>e1</tt> and
4.647 + * <tt>e2</tt> in the collection).<p>
4.648 + *
4.649 + * This method iterates over the entire collection, hence it requires
4.650 + * time proportional to the size of the collection.
4.651 + *
4.652 + * @param coll the collection whose minimum element is to be determined.
4.653 + * @param comp the comparator with which to determine the minimum element.
4.654 + * A <tt>null</tt> value indicates that the elements' <i>natural
4.655 + * ordering</i> should be used.
4.656 + * @return the minimum element of the given collection, according
4.657 + * to the specified comparator.
4.658 + * @throws ClassCastException if the collection contains elements that are
4.659 + * not <i>mutually comparable</i> using the specified comparator.
4.660 + * @throws NoSuchElementException if the collection is empty.
4.661 + * @see Comparable
4.662 + */
4.663 + public static <T> T min(Collection<? extends T> coll, Comparator<? super T> comp) {
4.664 + if (comp==null)
4.665 + return (T)min((Collection<SelfComparable>) (Collection) coll);
4.666 +
4.667 + Iterator<? extends T> i = coll.iterator();
4.668 + T candidate = i.next();
4.669 +
4.670 + while (i.hasNext()) {
4.671 + T next = i.next();
4.672 + if (comp.compare(next, candidate) < 0)
4.673 + candidate = next;
4.674 + }
4.675 + return candidate;
4.676 + }
4.677 +
4.678 + /**
4.679 + * Returns the maximum element of the given collection, according to the
4.680 + * <i>natural ordering</i> of its elements. All elements in the
4.681 + * collection must implement the <tt>Comparable</tt> interface.
4.682 + * Furthermore, all elements in the collection must be <i>mutually
4.683 + * comparable</i> (that is, <tt>e1.compareTo(e2)</tt> must not throw a
4.684 + * <tt>ClassCastException</tt> for any elements <tt>e1</tt> and
4.685 + * <tt>e2</tt> in the collection).<p>
4.686 + *
4.687 + * This method iterates over the entire collection, hence it requires
4.688 + * time proportional to the size of the collection.
4.689 + *
4.690 + * @param coll the collection whose maximum element is to be determined.
4.691 + * @return the maximum element of the given collection, according
4.692 + * to the <i>natural ordering</i> of its elements.
4.693 + * @throws ClassCastException if the collection contains elements that are
4.694 + * not <i>mutually comparable</i> (for example, strings and
4.695 + * integers).
4.696 + * @throws NoSuchElementException if the collection is empty.
4.697 + * @see Comparable
4.698 + */
4.699 + public static <T extends Object & Comparable<? super T>> T max(Collection<? extends T> coll) {
4.700 + Iterator<? extends T> i = coll.iterator();
4.701 + T candidate = i.next();
4.702 +
4.703 + while (i.hasNext()) {
4.704 + T next = i.next();
4.705 + if (next.compareTo(candidate) > 0)
4.706 + candidate = next;
4.707 + }
4.708 + return candidate;
4.709 + }
4.710 +
4.711 + /**
4.712 + * Returns the maximum element of the given collection, according to the
4.713 + * order induced by the specified comparator. All elements in the
4.714 + * collection must be <i>mutually comparable</i> by the specified
4.715 + * comparator (that is, <tt>comp.compare(e1, e2)</tt> must not throw a
4.716 + * <tt>ClassCastException</tt> for any elements <tt>e1</tt> and
4.717 + * <tt>e2</tt> in the collection).<p>
4.718 + *
4.719 + * This method iterates over the entire collection, hence it requires
4.720 + * time proportional to the size of the collection.
4.721 + *
4.722 + * @param coll the collection whose maximum element is to be determined.
4.723 + * @param comp the comparator with which to determine the maximum element.
4.724 + * A <tt>null</tt> value indicates that the elements' <i>natural
4.725 + * ordering</i> should be used.
4.726 + * @return the maximum element of the given collection, according
4.727 + * to the specified comparator.
4.728 + * @throws ClassCastException if the collection contains elements that are
4.729 + * not <i>mutually comparable</i> using the specified comparator.
4.730 + * @throws NoSuchElementException if the collection is empty.
4.731 + * @see Comparable
4.732 + */
4.733 + public static <T> T max(Collection<? extends T> coll, Comparator<? super T> comp) {
4.734 + if (comp==null)
4.735 + return (T)max((Collection<SelfComparable>) (Collection) coll);
4.736 +
4.737 + Iterator<? extends T> i = coll.iterator();
4.738 + T candidate = i.next();
4.739 +
4.740 + while (i.hasNext()) {
4.741 + T next = i.next();
4.742 + if (comp.compare(next, candidate) > 0)
4.743 + candidate = next;
4.744 + }
4.745 + return candidate;
4.746 + }
4.747 +
4.748 + /**
4.749 + * Rotates the elements in the specified list by the specified distance.
4.750 + * After calling this method, the element at index <tt>i</tt> will be
4.751 + * the element previously at index <tt>(i - distance)</tt> mod
4.752 + * <tt>list.size()</tt>, for all values of <tt>i</tt> between <tt>0</tt>
4.753 + * and <tt>list.size()-1</tt>, inclusive. (This method has no effect on
4.754 + * the size of the list.)
4.755 + *
4.756 + * <p>For example, suppose <tt>list</tt> comprises<tt> [t, a, n, k, s]</tt>.
4.757 + * After invoking <tt>Collections.rotate(list, 1)</tt> (or
4.758 + * <tt>Collections.rotate(list, -4)</tt>), <tt>list</tt> will comprise
4.759 + * <tt>[s, t, a, n, k]</tt>.
4.760 + *
4.761 + * <p>Note that this method can usefully be applied to sublists to
4.762 + * move one or more elements within a list while preserving the
4.763 + * order of the remaining elements. For example, the following idiom
4.764 + * moves the element at index <tt>j</tt> forward to position
4.765 + * <tt>k</tt> (which must be greater than or equal to <tt>j</tt>):
4.766 + * <pre>
4.767 + * Collections.rotate(list.subList(j, k+1), -1);
4.768 + * </pre>
4.769 + * To make this concrete, suppose <tt>list</tt> comprises
4.770 + * <tt>[a, b, c, d, e]</tt>. To move the element at index <tt>1</tt>
4.771 + * (<tt>b</tt>) forward two positions, perform the following invocation:
4.772 + * <pre>
4.773 + * Collections.rotate(l.subList(1, 4), -1);
4.774 + * </pre>
4.775 + * The resulting list is <tt>[a, c, d, b, e]</tt>.
4.776 + *
4.777 + * <p>To move more than one element forward, increase the absolute value
4.778 + * of the rotation distance. To move elements backward, use a positive
4.779 + * shift distance.
4.780 + *
4.781 + * <p>If the specified list is small or implements the {@link
4.782 + * RandomAccess} interface, this implementation exchanges the first
4.783 + * element into the location it should go, and then repeatedly exchanges
4.784 + * the displaced element into the location it should go until a displaced
4.785 + * element is swapped into the first element. If necessary, the process
4.786 + * is repeated on the second and successive elements, until the rotation
4.787 + * is complete. If the specified list is large and doesn't implement the
4.788 + * <tt>RandomAccess</tt> interface, this implementation breaks the
4.789 + * list into two sublist views around index <tt>-distance mod size</tt>.
4.790 + * Then the {@link #reverse(List)} method is invoked on each sublist view,
4.791 + * and finally it is invoked on the entire list. For a more complete
4.792 + * description of both algorithms, see Section 2.3 of Jon Bentley's
4.793 + * <i>Programming Pearls</i> (Addison-Wesley, 1986).
4.794 + *
4.795 + * @param list the list to be rotated.
4.796 + * @param distance the distance to rotate the list. There are no
4.797 + * constraints on this value; it may be zero, negative, or
4.798 + * greater than <tt>list.size()</tt>.
4.799 + * @throws UnsupportedOperationException if the specified list or
4.800 + * its list-iterator does not support the <tt>set</tt> operation.
4.801 + * @since 1.4
4.802 + */
4.803 + public static void rotate(List<?> list, int distance) {
4.804 + if (list instanceof RandomAccess || list.size() < ROTATE_THRESHOLD)
4.805 + rotate1(list, distance);
4.806 + else
4.807 + rotate2(list, distance);
4.808 + }
4.809 +
4.810 + private static <T> void rotate1(List<T> list, int distance) {
4.811 + int size = list.size();
4.812 + if (size == 0)
4.813 + return;
4.814 + distance = distance % size;
4.815 + if (distance < 0)
4.816 + distance += size;
4.817 + if (distance == 0)
4.818 + return;
4.819 +
4.820 + for (int cycleStart = 0, nMoved = 0; nMoved != size; cycleStart++) {
4.821 + T displaced = list.get(cycleStart);
4.822 + int i = cycleStart;
4.823 + do {
4.824 + i += distance;
4.825 + if (i >= size)
4.826 + i -= size;
4.827 + displaced = list.set(i, displaced);
4.828 + nMoved ++;
4.829 + } while (i != cycleStart);
4.830 + }
4.831 + }
4.832 +
4.833 + private static void rotate2(List<?> list, int distance) {
4.834 + int size = list.size();
4.835 + if (size == 0)
4.836 + return;
4.837 + int mid = -distance % size;
4.838 + if (mid < 0)
4.839 + mid += size;
4.840 + if (mid == 0)
4.841 + return;
4.842 +
4.843 + reverse(list.subList(0, mid));
4.844 + reverse(list.subList(mid, size));
4.845 + reverse(list);
4.846 + }
4.847 +
4.848 + /**
4.849 + * Replaces all occurrences of one specified value in a list with another.
4.850 + * More formally, replaces with <tt>newVal</tt> each element <tt>e</tt>
4.851 + * in <tt>list</tt> such that
4.852 + * <tt>(oldVal==null ? e==null : oldVal.equals(e))</tt>.
4.853 + * (This method has no effect on the size of the list.)
4.854 + *
4.855 + * @param list the list in which replacement is to occur.
4.856 + * @param oldVal the old value to be replaced.
4.857 + * @param newVal the new value with which <tt>oldVal</tt> is to be
4.858 + * replaced.
4.859 + * @return <tt>true</tt> if <tt>list</tt> contained one or more elements
4.860 + * <tt>e</tt> such that
4.861 + * <tt>(oldVal==null ? e==null : oldVal.equals(e))</tt>.
4.862 + * @throws UnsupportedOperationException if the specified list or
4.863 + * its list-iterator does not support the <tt>set</tt> operation.
4.864 + * @since 1.4
4.865 + */
4.866 + public static <T> boolean replaceAll(List<T> list, T oldVal, T newVal) {
4.867 + boolean result = false;
4.868 + int size = list.size();
4.869 + if (size < REPLACEALL_THRESHOLD || list instanceof RandomAccess) {
4.870 + if (oldVal==null) {
4.871 + for (int i=0; i<size; i++) {
4.872 + if (list.get(i)==null) {
4.873 + list.set(i, newVal);
4.874 + result = true;
4.875 + }
4.876 + }
4.877 + } else {
4.878 + for (int i=0; i<size; i++) {
4.879 + if (oldVal.equals(list.get(i))) {
4.880 + list.set(i, newVal);
4.881 + result = true;
4.882 + }
4.883 + }
4.884 + }
4.885 + } else {
4.886 + ListIterator<T> itr=list.listIterator();
4.887 + if (oldVal==null) {
4.888 + for (int i=0; i<size; i++) {
4.889 + if (itr.next()==null) {
4.890 + itr.set(newVal);
4.891 + result = true;
4.892 + }
4.893 + }
4.894 + } else {
4.895 + for (int i=0; i<size; i++) {
4.896 + if (oldVal.equals(itr.next())) {
4.897 + itr.set(newVal);
4.898 + result = true;
4.899 + }
4.900 + }
4.901 + }
4.902 + }
4.903 + return result;
4.904 + }
4.905 +
4.906 + /**
4.907 + * Returns the starting position of the first occurrence of the specified
4.908 + * target list within the specified source list, or -1 if there is no
4.909 + * such occurrence. More formally, returns the lowest index <tt>i</tt>
4.910 + * such that <tt>source.subList(i, i+target.size()).equals(target)</tt>,
4.911 + * or -1 if there is no such index. (Returns -1 if
4.912 + * <tt>target.size() > source.size()</tt>.)
4.913 + *
4.914 + * <p>This implementation uses the "brute force" technique of scanning
4.915 + * over the source list, looking for a match with the target at each
4.916 + * location in turn.
4.917 + *
4.918 + * @param source the list in which to search for the first occurrence
4.919 + * of <tt>target</tt>.
4.920 + * @param target the list to search for as a subList of <tt>source</tt>.
4.921 + * @return the starting position of the first occurrence of the specified
4.922 + * target list within the specified source list, or -1 if there
4.923 + * is no such occurrence.
4.924 + * @since 1.4
4.925 + */
4.926 + public static int indexOfSubList(List<?> source, List<?> target) {
4.927 + int sourceSize = source.size();
4.928 + int targetSize = target.size();
4.929 + int maxCandidate = sourceSize - targetSize;
4.930 +
4.931 + if (sourceSize < INDEXOFSUBLIST_THRESHOLD ||
4.932 + (source instanceof RandomAccess&&target instanceof RandomAccess)) {
4.933 + nextCand:
4.934 + for (int candidate = 0; candidate <= maxCandidate; candidate++) {
4.935 + for (int i=0, j=candidate; i<targetSize; i++, j++)
4.936 + if (!eq(target.get(i), source.get(j)))
4.937 + continue nextCand; // Element mismatch, try next cand
4.938 + return candidate; // All elements of candidate matched target
4.939 + }
4.940 + } else { // Iterator version of above algorithm
4.941 + ListIterator<?> si = source.listIterator();
4.942 + nextCand:
4.943 + for (int candidate = 0; candidate <= maxCandidate; candidate++) {
4.944 + ListIterator<?> ti = target.listIterator();
4.945 + for (int i=0; i<targetSize; i++) {
4.946 + if (!eq(ti.next(), si.next())) {
4.947 + // Back up source iterator to next candidate
4.948 + for (int j=0; j<i; j++)
4.949 + si.previous();
4.950 + continue nextCand;
4.951 + }
4.952 + }
4.953 + return candidate;
4.954 + }
4.955 + }
4.956 + return -1; // No candidate matched the target
4.957 + }
4.958 +
4.959 + /**
4.960 + * Returns the starting position of the last occurrence of the specified
4.961 + * target list within the specified source list, or -1 if there is no such
4.962 + * occurrence. More formally, returns the highest index <tt>i</tt>
4.963 + * such that <tt>source.subList(i, i+target.size()).equals(target)</tt>,
4.964 + * or -1 if there is no such index. (Returns -1 if
4.965 + * <tt>target.size() > source.size()</tt>.)
4.966 + *
4.967 + * <p>This implementation uses the "brute force" technique of iterating
4.968 + * over the source list, looking for a match with the target at each
4.969 + * location in turn.
4.970 + *
4.971 + * @param source the list in which to search for the last occurrence
4.972 + * of <tt>target</tt>.
4.973 + * @param target the list to search for as a subList of <tt>source</tt>.
4.974 + * @return the starting position of the last occurrence of the specified
4.975 + * target list within the specified source list, or -1 if there
4.976 + * is no such occurrence.
4.977 + * @since 1.4
4.978 + */
4.979 + public static int lastIndexOfSubList(List<?> source, List<?> target) {
4.980 + int sourceSize = source.size();
4.981 + int targetSize = target.size();
4.982 + int maxCandidate = sourceSize - targetSize;
4.983 +
4.984 + if (sourceSize < INDEXOFSUBLIST_THRESHOLD ||
4.985 + source instanceof RandomAccess) { // Index access version
4.986 + nextCand:
4.987 + for (int candidate = maxCandidate; candidate >= 0; candidate--) {
4.988 + for (int i=0, j=candidate; i<targetSize; i++, j++)
4.989 + if (!eq(target.get(i), source.get(j)))
4.990 + continue nextCand; // Element mismatch, try next cand
4.991 + return candidate; // All elements of candidate matched target
4.992 + }
4.993 + } else { // Iterator version of above algorithm
4.994 + if (maxCandidate < 0)
4.995 + return -1;
4.996 + ListIterator<?> si = source.listIterator(maxCandidate);
4.997 + nextCand:
4.998 + for (int candidate = maxCandidate; candidate >= 0; candidate--) {
4.999 + ListIterator<?> ti = target.listIterator();
4.1000 + for (int i=0; i<targetSize; i++) {
4.1001 + if (!eq(ti.next(), si.next())) {
4.1002 + if (candidate != 0) {
4.1003 + // Back up source iterator to next candidate
4.1004 + for (int j=0; j<=i+1; j++)
4.1005 + si.previous();
4.1006 + }
4.1007 + continue nextCand;
4.1008 + }
4.1009 + }
4.1010 + return candidate;
4.1011 + }
4.1012 + }
4.1013 + return -1; // No candidate matched the target
4.1014 + }
4.1015 +
4.1016 +
4.1017 + // Unmodifiable Wrappers
4.1018 +
4.1019 + /**
4.1020 + * Returns an unmodifiable view of the specified collection. This method
4.1021 + * allows modules to provide users with "read-only" access to internal
4.1022 + * collections. Query operations on the returned collection "read through"
4.1023 + * to the specified collection, and attempts to modify the returned
4.1024 + * collection, whether direct or via its iterator, result in an
4.1025 + * <tt>UnsupportedOperationException</tt>.<p>
4.1026 + *
4.1027 + * The returned collection does <i>not</i> pass the hashCode and equals
4.1028 + * operations through to the backing collection, but relies on
4.1029 + * <tt>Object</tt>'s <tt>equals</tt> and <tt>hashCode</tt> methods. This
4.1030 + * is necessary to preserve the contracts of these operations in the case
4.1031 + * that the backing collection is a set or a list.<p>
4.1032 + *
4.1033 + * The returned collection will be serializable if the specified collection
4.1034 + * is serializable.
4.1035 + *
4.1036 + * @param c the collection for which an unmodifiable view is to be
4.1037 + * returned.
4.1038 + * @return an unmodifiable view of the specified collection.
4.1039 + */
4.1040 + public static <T> Collection<T> unmodifiableCollection(Collection<? extends T> c) {
4.1041 + return new UnmodifiableCollection<>(c);
4.1042 + }
4.1043 +
4.1044 + /**
4.1045 + * @serial include
4.1046 + */
4.1047 + static class UnmodifiableCollection<E> implements Collection<E>, Serializable {
4.1048 + private static final long serialVersionUID = 1820017752578914078L;
4.1049 +
4.1050 + final Collection<? extends E> c;
4.1051 +
4.1052 + UnmodifiableCollection(Collection<? extends E> c) {
4.1053 + if (c==null)
4.1054 + throw new NullPointerException();
4.1055 + this.c = c;
4.1056 + }
4.1057 +
4.1058 + public int size() {return c.size();}
4.1059 + public boolean isEmpty() {return c.isEmpty();}
4.1060 + public boolean contains(Object o) {return c.contains(o);}
4.1061 + public Object[] toArray() {return c.toArray();}
4.1062 + public <T> T[] toArray(T[] a) {return c.toArray(a);}
4.1063 + public String toString() {return c.toString();}
4.1064 +
4.1065 + public Iterator<E> iterator() {
4.1066 + return new Iterator<E>() {
4.1067 + private final Iterator<? extends E> i = c.iterator();
4.1068 +
4.1069 + public boolean hasNext() {return i.hasNext();}
4.1070 + public E next() {return i.next();}
4.1071 + public void remove() {
4.1072 + throw new UnsupportedOperationException();
4.1073 + }
4.1074 + };
4.1075 + }
4.1076 +
4.1077 + public boolean add(E e) {
4.1078 + throw new UnsupportedOperationException();
4.1079 + }
4.1080 + public boolean remove(Object o) {
4.1081 + throw new UnsupportedOperationException();
4.1082 + }
4.1083 +
4.1084 + public boolean containsAll(Collection<?> coll) {
4.1085 + return c.containsAll(coll);
4.1086 + }
4.1087 + public boolean addAll(Collection<? extends E> coll) {
4.1088 + throw new UnsupportedOperationException();
4.1089 + }
4.1090 + public boolean removeAll(Collection<?> coll) {
4.1091 + throw new UnsupportedOperationException();
4.1092 + }
4.1093 + public boolean retainAll(Collection<?> coll) {
4.1094 + throw new UnsupportedOperationException();
4.1095 + }
4.1096 + public void clear() {
4.1097 + throw new UnsupportedOperationException();
4.1098 + }
4.1099 + }
4.1100 +
4.1101 + /**
4.1102 + * Returns an unmodifiable view of the specified set. This method allows
4.1103 + * modules to provide users with "read-only" access to internal sets.
4.1104 + * Query operations on the returned set "read through" to the specified
4.1105 + * set, and attempts to modify the returned set, whether direct or via its
4.1106 + * iterator, result in an <tt>UnsupportedOperationException</tt>.<p>
4.1107 + *
4.1108 + * The returned set will be serializable if the specified set
4.1109 + * is serializable.
4.1110 + *
4.1111 + * @param s the set for which an unmodifiable view is to be returned.
4.1112 + * @return an unmodifiable view of the specified set.
4.1113 + */
4.1114 + public static <T> Set<T> unmodifiableSet(Set<? extends T> s) {
4.1115 + return new UnmodifiableSet<>(s);
4.1116 + }
4.1117 +
4.1118 + /**
4.1119 + * @serial include
4.1120 + */
4.1121 + static class UnmodifiableSet<E> extends UnmodifiableCollection<E>
4.1122 + implements Set<E>, Serializable {
4.1123 + private static final long serialVersionUID = -9215047833775013803L;
4.1124 +
4.1125 + UnmodifiableSet(Set<? extends E> s) {super(s);}
4.1126 + public boolean equals(Object o) {return o == this || c.equals(o);}
4.1127 + public int hashCode() {return c.hashCode();}
4.1128 + }
4.1129 +
4.1130 + /**
4.1131 + * Returns an unmodifiable view of the specified sorted set. This method
4.1132 + * allows modules to provide users with "read-only" access to internal
4.1133 + * sorted sets. Query operations on the returned sorted set "read
4.1134 + * through" to the specified sorted set. Attempts to modify the returned
4.1135 + * sorted set, whether direct, via its iterator, or via its
4.1136 + * <tt>subSet</tt>, <tt>headSet</tt>, or <tt>tailSet</tt> views, result in
4.1137 + * an <tt>UnsupportedOperationException</tt>.<p>
4.1138 + *
4.1139 + * The returned sorted set will be serializable if the specified sorted set
4.1140 + * is serializable.
4.1141 + *
4.1142 + * @param s the sorted set for which an unmodifiable view is to be
4.1143 + * returned.
4.1144 + * @return an unmodifiable view of the specified sorted set.
4.1145 + */
4.1146 + public static <T> SortedSet<T> unmodifiableSortedSet(SortedSet<T> s) {
4.1147 + return new UnmodifiableSortedSet<>(s);
4.1148 + }
4.1149 +
4.1150 + /**
4.1151 + * @serial include
4.1152 + */
4.1153 + static class UnmodifiableSortedSet<E>
4.1154 + extends UnmodifiableSet<E>
4.1155 + implements SortedSet<E>, Serializable {
4.1156 + private static final long serialVersionUID = -4929149591599911165L;
4.1157 + private final SortedSet<E> ss;
4.1158 +
4.1159 + UnmodifiableSortedSet(SortedSet<E> s) {super(s); ss = s;}
4.1160 +
4.1161 + public Comparator<? super E> comparator() {return ss.comparator();}
4.1162 +
4.1163 + public SortedSet<E> subSet(E fromElement, E toElement) {
4.1164 + return new UnmodifiableSortedSet<>(ss.subSet(fromElement,toElement));
4.1165 + }
4.1166 + public SortedSet<E> headSet(E toElement) {
4.1167 + return new UnmodifiableSortedSet<>(ss.headSet(toElement));
4.1168 + }
4.1169 + public SortedSet<E> tailSet(E fromElement) {
4.1170 + return new UnmodifiableSortedSet<>(ss.tailSet(fromElement));
4.1171 + }
4.1172 +
4.1173 + public E first() {return ss.first();}
4.1174 + public E last() {return ss.last();}
4.1175 + }
4.1176 +
4.1177 + /**
4.1178 + * Returns an unmodifiable view of the specified list. This method allows
4.1179 + * modules to provide users with "read-only" access to internal
4.1180 + * lists. Query operations on the returned list "read through" to the
4.1181 + * specified list, and attempts to modify the returned list, whether
4.1182 + * direct or via its iterator, result in an
4.1183 + * <tt>UnsupportedOperationException</tt>.<p>
4.1184 + *
4.1185 + * The returned list will be serializable if the specified list
4.1186 + * is serializable. Similarly, the returned list will implement
4.1187 + * {@link RandomAccess} if the specified list does.
4.1188 + *
4.1189 + * @param list the list for which an unmodifiable view is to be returned.
4.1190 + * @return an unmodifiable view of the specified list.
4.1191 + */
4.1192 + public static <T> List<T> unmodifiableList(List<? extends T> list) {
4.1193 + return (list instanceof RandomAccess ?
4.1194 + new UnmodifiableRandomAccessList<>(list) :
4.1195 + new UnmodifiableList<>(list));
4.1196 + }
4.1197 +
4.1198 + /**
4.1199 + * @serial include
4.1200 + */
4.1201 + static class UnmodifiableList<E> extends UnmodifiableCollection<E>
4.1202 + implements List<E> {
4.1203 + private static final long serialVersionUID = -283967356065247728L;
4.1204 + final List<? extends E> list;
4.1205 +
4.1206 + UnmodifiableList(List<? extends E> list) {
4.1207 + super(list);
4.1208 + this.list = list;
4.1209 + }
4.1210 +
4.1211 + public boolean equals(Object o) {return o == this || list.equals(o);}
4.1212 + public int hashCode() {return list.hashCode();}
4.1213 +
4.1214 + public E get(int index) {return list.get(index);}
4.1215 + public E set(int index, E element) {
4.1216 + throw new UnsupportedOperationException();
4.1217 + }
4.1218 + public void add(int index, E element) {
4.1219 + throw new UnsupportedOperationException();
4.1220 + }
4.1221 + public E remove(int index) {
4.1222 + throw new UnsupportedOperationException();
4.1223 + }
4.1224 + public int indexOf(Object o) {return list.indexOf(o);}
4.1225 + public int lastIndexOf(Object o) {return list.lastIndexOf(o);}
4.1226 + public boolean addAll(int index, Collection<? extends E> c) {
4.1227 + throw new UnsupportedOperationException();
4.1228 + }
4.1229 + public ListIterator<E> listIterator() {return listIterator(0);}
4.1230 +
4.1231 + public ListIterator<E> listIterator(final int index) {
4.1232 + return new ListIterator<E>() {
4.1233 + private final ListIterator<? extends E> i
4.1234 + = list.listIterator(index);
4.1235 +
4.1236 + public boolean hasNext() {return i.hasNext();}
4.1237 + public E next() {return i.next();}
4.1238 + public boolean hasPrevious() {return i.hasPrevious();}
4.1239 + public E previous() {return i.previous();}
4.1240 + public int nextIndex() {return i.nextIndex();}
4.1241 + public int previousIndex() {return i.previousIndex();}
4.1242 +
4.1243 + public void remove() {
4.1244 + throw new UnsupportedOperationException();
4.1245 + }
4.1246 + public void set(E e) {
4.1247 + throw new UnsupportedOperationException();
4.1248 + }
4.1249 + public void add(E e) {
4.1250 + throw new UnsupportedOperationException();
4.1251 + }
4.1252 + };
4.1253 + }
4.1254 +
4.1255 + public List<E> subList(int fromIndex, int toIndex) {
4.1256 + return new UnmodifiableList<>(list.subList(fromIndex, toIndex));
4.1257 + }
4.1258 +
4.1259 + /**
4.1260 + * UnmodifiableRandomAccessList instances are serialized as
4.1261 + * UnmodifiableList instances to allow them to be deserialized
4.1262 + * in pre-1.4 JREs (which do not have UnmodifiableRandomAccessList).
4.1263 + * This method inverts the transformation. As a beneficial
4.1264 + * side-effect, it also grafts the RandomAccess marker onto
4.1265 + * UnmodifiableList instances that were serialized in pre-1.4 JREs.
4.1266 + *
4.1267 + * Note: Unfortunately, UnmodifiableRandomAccessList instances
4.1268 + * serialized in 1.4.1 and deserialized in 1.4 will become
4.1269 + * UnmodifiableList instances, as this method was missing in 1.4.
4.1270 + */
4.1271 + private Object readResolve() {
4.1272 + return (list instanceof RandomAccess
4.1273 + ? new UnmodifiableRandomAccessList<>(list)
4.1274 + : this);
4.1275 + }
4.1276 + }
4.1277 +
4.1278 + /**
4.1279 + * @serial include
4.1280 + */
4.1281 + static class UnmodifiableRandomAccessList<E> extends UnmodifiableList<E>
4.1282 + implements RandomAccess
4.1283 + {
4.1284 + UnmodifiableRandomAccessList(List<? extends E> list) {
4.1285 + super(list);
4.1286 + }
4.1287 +
4.1288 + public List<E> subList(int fromIndex, int toIndex) {
4.1289 + return new UnmodifiableRandomAccessList<>(
4.1290 + list.subList(fromIndex, toIndex));
4.1291 + }
4.1292 +
4.1293 + private static final long serialVersionUID = -2542308836966382001L;
4.1294 +
4.1295 + /**
4.1296 + * Allows instances to be deserialized in pre-1.4 JREs (which do
4.1297 + * not have UnmodifiableRandomAccessList). UnmodifiableList has
4.1298 + * a readResolve method that inverts this transformation upon
4.1299 + * deserialization.
4.1300 + */
4.1301 + private Object writeReplace() {
4.1302 + return new UnmodifiableList<>(list);
4.1303 + }
4.1304 + }
4.1305 +
4.1306 + /**
4.1307 + * Returns an unmodifiable view of the specified map. This method
4.1308 + * allows modules to provide users with "read-only" access to internal
4.1309 + * maps. Query operations on the returned map "read through"
4.1310 + * to the specified map, and attempts to modify the returned
4.1311 + * map, whether direct or via its collection views, result in an
4.1312 + * <tt>UnsupportedOperationException</tt>.<p>
4.1313 + *
4.1314 + * The returned map will be serializable if the specified map
4.1315 + * is serializable.
4.1316 + *
4.1317 + * @param m the map for which an unmodifiable view is to be returned.
4.1318 + * @return an unmodifiable view of the specified map.
4.1319 + */
4.1320 + public static <K,V> Map<K,V> unmodifiableMap(Map<? extends K, ? extends V> m) {
4.1321 + return new UnmodifiableMap<>(m);
4.1322 + }
4.1323 +
4.1324 + /**
4.1325 + * @serial include
4.1326 + */
4.1327 + private static class UnmodifiableMap<K,V> implements Map<K,V>, Serializable {
4.1328 + private static final long serialVersionUID = -1034234728574286014L;
4.1329 +
4.1330 + private final Map<? extends K, ? extends V> m;
4.1331 +
4.1332 + UnmodifiableMap(Map<? extends K, ? extends V> m) {
4.1333 + if (m==null)
4.1334 + throw new NullPointerException();
4.1335 + this.m = m;
4.1336 + }
4.1337 +
4.1338 + public int size() {return m.size();}
4.1339 + public boolean isEmpty() {return m.isEmpty();}
4.1340 + public boolean containsKey(Object key) {return m.containsKey(key);}
4.1341 + public boolean containsValue(Object val) {return m.containsValue(val);}
4.1342 + public V get(Object key) {return m.get(key);}
4.1343 +
4.1344 + public V put(K key, V value) {
4.1345 + throw new UnsupportedOperationException();
4.1346 + }
4.1347 + public V remove(Object key) {
4.1348 + throw new UnsupportedOperationException();
4.1349 + }
4.1350 + public void putAll(Map<? extends K, ? extends V> m) {
4.1351 + throw new UnsupportedOperationException();
4.1352 + }
4.1353 + public void clear() {
4.1354 + throw new UnsupportedOperationException();
4.1355 + }
4.1356 +
4.1357 + private transient Set<K> keySet = null;
4.1358 + private transient Set<Map.Entry<K,V>> entrySet = null;
4.1359 + private transient Collection<V> values = null;
4.1360 +
4.1361 + public Set<K> keySet() {
4.1362 + if (keySet==null)
4.1363 + keySet = unmodifiableSet(m.keySet());
4.1364 + return keySet;
4.1365 + }
4.1366 +
4.1367 + public Set<Map.Entry<K,V>> entrySet() {
4.1368 + if (entrySet==null)
4.1369 + entrySet = new UnmodifiableEntrySet<>(m.entrySet());
4.1370 + return entrySet;
4.1371 + }
4.1372 +
4.1373 + public Collection<V> values() {
4.1374 + if (values==null)
4.1375 + values = unmodifiableCollection(m.values());
4.1376 + return values;
4.1377 + }
4.1378 +
4.1379 + public boolean equals(Object o) {return o == this || m.equals(o);}
4.1380 + public int hashCode() {return m.hashCode();}
4.1381 + public String toString() {return m.toString();}
4.1382 +
4.1383 + /**
4.1384 + * We need this class in addition to UnmodifiableSet as
4.1385 + * Map.Entries themselves permit modification of the backing Map
4.1386 + * via their setValue operation. This class is subtle: there are
4.1387 + * many possible attacks that must be thwarted.
4.1388 + *
4.1389 + * @serial include
4.1390 + */
4.1391 + static class UnmodifiableEntrySet<K,V>
4.1392 + extends UnmodifiableSet<Map.Entry<K,V>> {
4.1393 + private static final long serialVersionUID = 7854390611657943733L;
4.1394 +
4.1395 + UnmodifiableEntrySet(Set<? extends Map.Entry<? extends K, ? extends V>> s) {
4.1396 + super((Set)s);
4.1397 + }
4.1398 + public Iterator<Map.Entry<K,V>> iterator() {
4.1399 + return new Iterator<Map.Entry<K,V>>() {
4.1400 + private final Iterator<? extends Map.Entry<? extends K, ? extends V>> i = c.iterator();
4.1401 +
4.1402 + public boolean hasNext() {
4.1403 + return i.hasNext();
4.1404 + }
4.1405 + public Map.Entry<K,V> next() {
4.1406 + return new UnmodifiableEntry<>(i.next());
4.1407 + }
4.1408 + public void remove() {
4.1409 + throw new UnsupportedOperationException();
4.1410 + }
4.1411 + };
4.1412 + }
4.1413 +
4.1414 + public Object[] toArray() {
4.1415 + Object[] a = c.toArray();
4.1416 + for (int i=0; i<a.length; i++)
4.1417 + a[i] = new UnmodifiableEntry<>((Map.Entry<K,V>)a[i]);
4.1418 + return a;
4.1419 + }
4.1420 +
4.1421 + public <T> T[] toArray(T[] a) {
4.1422 + // We don't pass a to c.toArray, to avoid window of
4.1423 + // vulnerability wherein an unscrupulous multithreaded client
4.1424 + // could get his hands on raw (unwrapped) Entries from c.
4.1425 + Object[] arr = c.toArray(a.length==0 ? a : Arrays.copyOf(a, 0));
4.1426 +
4.1427 + for (int i=0; i<arr.length; i++)
4.1428 + arr[i] = new UnmodifiableEntry<>((Map.Entry<K,V>)arr[i]);
4.1429 +
4.1430 + if (arr.length > a.length)
4.1431 + return (T[])arr;
4.1432 +
4.1433 + System.arraycopy(arr, 0, a, 0, arr.length);
4.1434 + if (a.length > arr.length)
4.1435 + a[arr.length] = null;
4.1436 + return a;
4.1437 + }
4.1438 +
4.1439 + /**
4.1440 + * This method is overridden to protect the backing set against
4.1441 + * an object with a nefarious equals function that senses
4.1442 + * that the equality-candidate is Map.Entry and calls its
4.1443 + * setValue method.
4.1444 + */
4.1445 + public boolean contains(Object o) {
4.1446 + if (!(o instanceof Map.Entry))
4.1447 + return false;
4.1448 + return c.contains(
4.1449 + new UnmodifiableEntry<>((Map.Entry<?,?>) o));
4.1450 + }
4.1451 +
4.1452 + /**
4.1453 + * The next two methods are overridden to protect against
4.1454 + * an unscrupulous List whose contains(Object o) method senses
4.1455 + * when o is a Map.Entry, and calls o.setValue.
4.1456 + */
4.1457 + public boolean containsAll(Collection<?> coll) {
4.1458 + for (Object e : coll) {
4.1459 + if (!contains(e)) // Invokes safe contains() above
4.1460 + return false;
4.1461 + }
4.1462 + return true;
4.1463 + }
4.1464 + public boolean equals(Object o) {
4.1465 + if (o == this)
4.1466 + return true;
4.1467 +
4.1468 + if (!(o instanceof Set))
4.1469 + return false;
4.1470 + Set s = (Set) o;
4.1471 + if (s.size() != c.size())
4.1472 + return false;
4.1473 + return containsAll(s); // Invokes safe containsAll() above
4.1474 + }
4.1475 +
4.1476 + /**
4.1477 + * This "wrapper class" serves two purposes: it prevents
4.1478 + * the client from modifying the backing Map, by short-circuiting
4.1479 + * the setValue method, and it protects the backing Map against
4.1480 + * an ill-behaved Map.Entry that attempts to modify another
4.1481 + * Map Entry when asked to perform an equality check.
4.1482 + */
4.1483 + private static class UnmodifiableEntry<K,V> implements Map.Entry<K,V> {
4.1484 + private Map.Entry<? extends K, ? extends V> e;
4.1485 +
4.1486 + UnmodifiableEntry(Map.Entry<? extends K, ? extends V> e) {this.e = e;}
4.1487 +
4.1488 + public K getKey() {return e.getKey();}
4.1489 + public V getValue() {return e.getValue();}
4.1490 + public V setValue(V value) {
4.1491 + throw new UnsupportedOperationException();
4.1492 + }
4.1493 + public int hashCode() {return e.hashCode();}
4.1494 + public boolean equals(Object o) {
4.1495 + if (!(o instanceof Map.Entry))
4.1496 + return false;
4.1497 + Map.Entry t = (Map.Entry)o;
4.1498 + return eq(e.getKey(), t.getKey()) &&
4.1499 + eq(e.getValue(), t.getValue());
4.1500 + }
4.1501 + public String toString() {return e.toString();}
4.1502 + }
4.1503 + }
4.1504 + }
4.1505 +
4.1506 + /**
4.1507 + * Returns an unmodifiable view of the specified sorted map. This method
4.1508 + * allows modules to provide users with "read-only" access to internal
4.1509 + * sorted maps. Query operations on the returned sorted map "read through"
4.1510 + * to the specified sorted map. Attempts to modify the returned
4.1511 + * sorted map, whether direct, via its collection views, or via its
4.1512 + * <tt>subMap</tt>, <tt>headMap</tt>, or <tt>tailMap</tt> views, result in
4.1513 + * an <tt>UnsupportedOperationException</tt>.<p>
4.1514 + *
4.1515 + * The returned sorted map will be serializable if the specified sorted map
4.1516 + * is serializable.
4.1517 + *
4.1518 + * @param m the sorted map for which an unmodifiable view is to be
4.1519 + * returned.
4.1520 + * @return an unmodifiable view of the specified sorted map.
4.1521 + */
4.1522 + public static <K,V> SortedMap<K,V> unmodifiableSortedMap(SortedMap<K, ? extends V> m) {
4.1523 + return new UnmodifiableSortedMap<>(m);
4.1524 + }
4.1525 +
4.1526 + /**
4.1527 + * @serial include
4.1528 + */
4.1529 + static class UnmodifiableSortedMap<K,V>
4.1530 + extends UnmodifiableMap<K,V>
4.1531 + implements SortedMap<K,V>, Serializable {
4.1532 + private static final long serialVersionUID = -8806743815996713206L;
4.1533 +
4.1534 + private final SortedMap<K, ? extends V> sm;
4.1535 +
4.1536 + UnmodifiableSortedMap(SortedMap<K, ? extends V> m) {super(m); sm = m;}
4.1537 +
4.1538 + public Comparator<? super K> comparator() {return sm.comparator();}
4.1539 +
4.1540 + public SortedMap<K,V> subMap(K fromKey, K toKey) {
4.1541 + return new UnmodifiableSortedMap<>(sm.subMap(fromKey, toKey));
4.1542 + }
4.1543 + public SortedMap<K,V> headMap(K toKey) {
4.1544 + return new UnmodifiableSortedMap<>(sm.headMap(toKey));
4.1545 + }
4.1546 + public SortedMap<K,V> tailMap(K fromKey) {
4.1547 + return new UnmodifiableSortedMap<>(sm.tailMap(fromKey));
4.1548 + }
4.1549 +
4.1550 + public K firstKey() {return sm.firstKey();}
4.1551 + public K lastKey() {return sm.lastKey();}
4.1552 + }
4.1553 +
4.1554 +
4.1555 + // Synch Wrappers
4.1556 +
4.1557 + /**
4.1558 + * Returns a synchronized (thread-safe) collection backed by the specified
4.1559 + * collection. In order to guarantee serial access, it is critical that
4.1560 + * <strong>all</strong> access to the backing collection is accomplished
4.1561 + * through the returned collection.<p>
4.1562 + *
4.1563 + * It is imperative that the user manually synchronize on the returned
4.1564 + * collection when iterating over it:
4.1565 + * <pre>
4.1566 + * Collection c = Collections.synchronizedCollection(myCollection);
4.1567 + * ...
4.1568 + * synchronized (c) {
4.1569 + * Iterator i = c.iterator(); // Must be in the synchronized block
4.1570 + * while (i.hasNext())
4.1571 + * foo(i.next());
4.1572 + * }
4.1573 + * </pre>
4.1574 + * Failure to follow this advice may result in non-deterministic behavior.
4.1575 + *
4.1576 + * <p>The returned collection does <i>not</i> pass the <tt>hashCode</tt>
4.1577 + * and <tt>equals</tt> operations through to the backing collection, but
4.1578 + * relies on <tt>Object</tt>'s equals and hashCode methods. This is
4.1579 + * necessary to preserve the contracts of these operations in the case
4.1580 + * that the backing collection is a set or a list.<p>
4.1581 + *
4.1582 + * The returned collection will be serializable if the specified collection
4.1583 + * is serializable.
4.1584 + *
4.1585 + * @param c the collection to be "wrapped" in a synchronized collection.
4.1586 + * @return a synchronized view of the specified collection.
4.1587 + */
4.1588 + public static <T> Collection<T> synchronizedCollection(Collection<T> c) {
4.1589 + return new SynchronizedCollection<>(c);
4.1590 + }
4.1591 +
4.1592 + static <T> Collection<T> synchronizedCollection(Collection<T> c, Object mutex) {
4.1593 + return new SynchronizedCollection<>(c, mutex);
4.1594 + }
4.1595 +
4.1596 + /**
4.1597 + * @serial include
4.1598 + */
4.1599 + static class SynchronizedCollection<E> implements Collection<E>, Serializable {
4.1600 + private static final long serialVersionUID = 3053995032091335093L;
4.1601 +
4.1602 + final Collection<E> c; // Backing Collection
4.1603 + final Object mutex; // Object on which to synchronize
4.1604 +
4.1605 + SynchronizedCollection(Collection<E> c) {
4.1606 + if (c==null)
4.1607 + throw new NullPointerException();
4.1608 + this.c = c;
4.1609 + mutex = this;
4.1610 + }
4.1611 + SynchronizedCollection(Collection<E> c, Object mutex) {
4.1612 + this.c = c;
4.1613 + this.mutex = mutex;
4.1614 + }
4.1615 +
4.1616 + public int size() {
4.1617 + synchronized (mutex) {return c.size();}
4.1618 + }
4.1619 + public boolean isEmpty() {
4.1620 + synchronized (mutex) {return c.isEmpty();}
4.1621 + }
4.1622 + public boolean contains(Object o) {
4.1623 + synchronized (mutex) {return c.contains(o);}
4.1624 + }
4.1625 + public Object[] toArray() {
4.1626 + synchronized (mutex) {return c.toArray();}
4.1627 + }
4.1628 + public <T> T[] toArray(T[] a) {
4.1629 + synchronized (mutex) {return c.toArray(a);}
4.1630 + }
4.1631 +
4.1632 + public Iterator<E> iterator() {
4.1633 + return c.iterator(); // Must be manually synched by user!
4.1634 + }
4.1635 +
4.1636 + public boolean add(E e) {
4.1637 + synchronized (mutex) {return c.add(e);}
4.1638 + }
4.1639 + public boolean remove(Object o) {
4.1640 + synchronized (mutex) {return c.remove(o);}
4.1641 + }
4.1642 +
4.1643 + public boolean containsAll(Collection<?> coll) {
4.1644 + synchronized (mutex) {return c.containsAll(coll);}
4.1645 + }
4.1646 + public boolean addAll(Collection<? extends E> coll) {
4.1647 + synchronized (mutex) {return c.addAll(coll);}
4.1648 + }
4.1649 + public boolean removeAll(Collection<?> coll) {
4.1650 + synchronized (mutex) {return c.removeAll(coll);}
4.1651 + }
4.1652 + public boolean retainAll(Collection<?> coll) {
4.1653 + synchronized (mutex) {return c.retainAll(coll);}
4.1654 + }
4.1655 + public void clear() {
4.1656 + synchronized (mutex) {c.clear();}
4.1657 + }
4.1658 + public String toString() {
4.1659 + synchronized (mutex) {return c.toString();}
4.1660 + }
4.1661 + private void writeObject(ObjectOutputStream s) throws IOException {
4.1662 + synchronized (mutex) {s.defaultWriteObject();}
4.1663 + }
4.1664 + }
4.1665 +
4.1666 + /**
4.1667 + * Returns a synchronized (thread-safe) set backed by the specified
4.1668 + * set. In order to guarantee serial access, it is critical that
4.1669 + * <strong>all</strong> access to the backing set is accomplished
4.1670 + * through the returned set.<p>
4.1671 + *
4.1672 + * It is imperative that the user manually synchronize on the returned
4.1673 + * set when iterating over it:
4.1674 + * <pre>
4.1675 + * Set s = Collections.synchronizedSet(new HashSet());
4.1676 + * ...
4.1677 + * synchronized (s) {
4.1678 + * Iterator i = s.iterator(); // Must be in the synchronized block
4.1679 + * while (i.hasNext())
4.1680 + * foo(i.next());
4.1681 + * }
4.1682 + * </pre>
4.1683 + * Failure to follow this advice may result in non-deterministic behavior.
4.1684 + *
4.1685 + * <p>The returned set will be serializable if the specified set is
4.1686 + * serializable.
4.1687 + *
4.1688 + * @param s the set to be "wrapped" in a synchronized set.
4.1689 + * @return a synchronized view of the specified set.
4.1690 + */
4.1691 + public static <T> Set<T> synchronizedSet(Set<T> s) {
4.1692 + return new SynchronizedSet<>(s);
4.1693 + }
4.1694 +
4.1695 + static <T> Set<T> synchronizedSet(Set<T> s, Object mutex) {
4.1696 + return new SynchronizedSet<>(s, mutex);
4.1697 + }
4.1698 +
4.1699 + /**
4.1700 + * @serial include
4.1701 + */
4.1702 + static class SynchronizedSet<E>
4.1703 + extends SynchronizedCollection<E>
4.1704 + implements Set<E> {
4.1705 + private static final long serialVersionUID = 487447009682186044L;
4.1706 +
4.1707 + SynchronizedSet(Set<E> s) {
4.1708 + super(s);
4.1709 + }
4.1710 + SynchronizedSet(Set<E> s, Object mutex) {
4.1711 + super(s, mutex);
4.1712 + }
4.1713 +
4.1714 + public boolean equals(Object o) {
4.1715 + synchronized (mutex) {return c.equals(o);}
4.1716 + }
4.1717 + public int hashCode() {
4.1718 + synchronized (mutex) {return c.hashCode();}
4.1719 + }
4.1720 + }
4.1721 +
4.1722 + /**
4.1723 + * Returns a synchronized (thread-safe) sorted set backed by the specified
4.1724 + * sorted set. In order to guarantee serial access, it is critical that
4.1725 + * <strong>all</strong> access to the backing sorted set is accomplished
4.1726 + * through the returned sorted set (or its views).<p>
4.1727 + *
4.1728 + * It is imperative that the user manually synchronize on the returned
4.1729 + * sorted set when iterating over it or any of its <tt>subSet</tt>,
4.1730 + * <tt>headSet</tt>, or <tt>tailSet</tt> views.
4.1731 + * <pre>
4.1732 + * SortedSet s = Collections.synchronizedSortedSet(new TreeSet());
4.1733 + * ...
4.1734 + * synchronized (s) {
4.1735 + * Iterator i = s.iterator(); // Must be in the synchronized block
4.1736 + * while (i.hasNext())
4.1737 + * foo(i.next());
4.1738 + * }
4.1739 + * </pre>
4.1740 + * or:
4.1741 + * <pre>
4.1742 + * SortedSet s = Collections.synchronizedSortedSet(new TreeSet());
4.1743 + * SortedSet s2 = s.headSet(foo);
4.1744 + * ...
4.1745 + * synchronized (s) { // Note: s, not s2!!!
4.1746 + * Iterator i = s2.iterator(); // Must be in the synchronized block
4.1747 + * while (i.hasNext())
4.1748 + * foo(i.next());
4.1749 + * }
4.1750 + * </pre>
4.1751 + * Failure to follow this advice may result in non-deterministic behavior.
4.1752 + *
4.1753 + * <p>The returned sorted set will be serializable if the specified
4.1754 + * sorted set is serializable.
4.1755 + *
4.1756 + * @param s the sorted set to be "wrapped" in a synchronized sorted set.
4.1757 + * @return a synchronized view of the specified sorted set.
4.1758 + */
4.1759 + public static <T> SortedSet<T> synchronizedSortedSet(SortedSet<T> s) {
4.1760 + return new SynchronizedSortedSet<>(s);
4.1761 + }
4.1762 +
4.1763 + /**
4.1764 + * @serial include
4.1765 + */
4.1766 + static class SynchronizedSortedSet<E>
4.1767 + extends SynchronizedSet<E>
4.1768 + implements SortedSet<E>
4.1769 + {
4.1770 + private static final long serialVersionUID = 8695801310862127406L;
4.1771 +
4.1772 + private final SortedSet<E> ss;
4.1773 +
4.1774 + SynchronizedSortedSet(SortedSet<E> s) {
4.1775 + super(s);
4.1776 + ss = s;
4.1777 + }
4.1778 + SynchronizedSortedSet(SortedSet<E> s, Object mutex) {
4.1779 + super(s, mutex);
4.1780 + ss = s;
4.1781 + }
4.1782 +
4.1783 + public Comparator<? super E> comparator() {
4.1784 + synchronized (mutex) {return ss.comparator();}
4.1785 + }
4.1786 +
4.1787 + public SortedSet<E> subSet(E fromElement, E toElement) {
4.1788 + synchronized (mutex) {
4.1789 + return new SynchronizedSortedSet<>(
4.1790 + ss.subSet(fromElement, toElement), mutex);
4.1791 + }
4.1792 + }
4.1793 + public SortedSet<E> headSet(E toElement) {
4.1794 + synchronized (mutex) {
4.1795 + return new SynchronizedSortedSet<>(ss.headSet(toElement), mutex);
4.1796 + }
4.1797 + }
4.1798 + public SortedSet<E> tailSet(E fromElement) {
4.1799 + synchronized (mutex) {
4.1800 + return new SynchronizedSortedSet<>(ss.tailSet(fromElement),mutex);
4.1801 + }
4.1802 + }
4.1803 +
4.1804 + public E first() {
4.1805 + synchronized (mutex) {return ss.first();}
4.1806 + }
4.1807 + public E last() {
4.1808 + synchronized (mutex) {return ss.last();}
4.1809 + }
4.1810 + }
4.1811 +
4.1812 + /**
4.1813 + * Returns a synchronized (thread-safe) list backed by the specified
4.1814 + * list. In order to guarantee serial access, it is critical that
4.1815 + * <strong>all</strong> access to the backing list is accomplished
4.1816 + * through the returned list.<p>
4.1817 + *
4.1818 + * It is imperative that the user manually synchronize on the returned
4.1819 + * list when iterating over it:
4.1820 + * <pre>
4.1821 + * List list = Collections.synchronizedList(new ArrayList());
4.1822 + * ...
4.1823 + * synchronized (list) {
4.1824 + * Iterator i = list.iterator(); // Must be in synchronized block
4.1825 + * while (i.hasNext())
4.1826 + * foo(i.next());
4.1827 + * }
4.1828 + * </pre>
4.1829 + * Failure to follow this advice may result in non-deterministic behavior.
4.1830 + *
4.1831 + * <p>The returned list will be serializable if the specified list is
4.1832 + * serializable.
4.1833 + *
4.1834 + * @param list the list to be "wrapped" in a synchronized list.
4.1835 + * @return a synchronized view of the specified list.
4.1836 + */
4.1837 + public static <T> List<T> synchronizedList(List<T> list) {
4.1838 + return (list instanceof RandomAccess ?
4.1839 + new SynchronizedRandomAccessList<>(list) :
4.1840 + new SynchronizedList<>(list));
4.1841 + }
4.1842 +
4.1843 + static <T> List<T> synchronizedList(List<T> list, Object mutex) {
4.1844 + return (list instanceof RandomAccess ?
4.1845 + new SynchronizedRandomAccessList<>(list, mutex) :
4.1846 + new SynchronizedList<>(list, mutex));
4.1847 + }
4.1848 +
4.1849 + /**
4.1850 + * @serial include
4.1851 + */
4.1852 + static class SynchronizedList<E>
4.1853 + extends SynchronizedCollection<E>
4.1854 + implements List<E> {
4.1855 + private static final long serialVersionUID = -7754090372962971524L;
4.1856 +
4.1857 + final List<E> list;
4.1858 +
4.1859 + SynchronizedList(List<E> list) {
4.1860 + super(list);
4.1861 + this.list = list;
4.1862 + }
4.1863 + SynchronizedList(List<E> list, Object mutex) {
4.1864 + super(list, mutex);
4.1865 + this.list = list;
4.1866 + }
4.1867 +
4.1868 + public boolean equals(Object o) {
4.1869 + synchronized (mutex) {return list.equals(o);}
4.1870 + }
4.1871 + public int hashCode() {
4.1872 + synchronized (mutex) {return list.hashCode();}
4.1873 + }
4.1874 +
4.1875 + public E get(int index) {
4.1876 + synchronized (mutex) {return list.get(index);}
4.1877 + }
4.1878 + public E set(int index, E element) {
4.1879 + synchronized (mutex) {return list.set(index, element);}
4.1880 + }
4.1881 + public void add(int index, E element) {
4.1882 + synchronized (mutex) {list.add(index, element);}
4.1883 + }
4.1884 + public E remove(int index) {
4.1885 + synchronized (mutex) {return list.remove(index);}
4.1886 + }
4.1887 +
4.1888 + public int indexOf(Object o) {
4.1889 + synchronized (mutex) {return list.indexOf(o);}
4.1890 + }
4.1891 + public int lastIndexOf(Object o) {
4.1892 + synchronized (mutex) {return list.lastIndexOf(o);}
4.1893 + }
4.1894 +
4.1895 + public boolean addAll(int index, Collection<? extends E> c) {
4.1896 + synchronized (mutex) {return list.addAll(index, c);}
4.1897 + }
4.1898 +
4.1899 + public ListIterator<E> listIterator() {
4.1900 + return list.listIterator(); // Must be manually synched by user
4.1901 + }
4.1902 +
4.1903 + public ListIterator<E> listIterator(int index) {
4.1904 + return list.listIterator(index); // Must be manually synched by user
4.1905 + }
4.1906 +
4.1907 + public List<E> subList(int fromIndex, int toIndex) {
4.1908 + synchronized (mutex) {
4.1909 + return new SynchronizedList<>(list.subList(fromIndex, toIndex),
4.1910 + mutex);
4.1911 + }
4.1912 + }
4.1913 +
4.1914 + /**
4.1915 + * SynchronizedRandomAccessList instances are serialized as
4.1916 + * SynchronizedList instances to allow them to be deserialized
4.1917 + * in pre-1.4 JREs (which do not have SynchronizedRandomAccessList).
4.1918 + * This method inverts the transformation. As a beneficial
4.1919 + * side-effect, it also grafts the RandomAccess marker onto
4.1920 + * SynchronizedList instances that were serialized in pre-1.4 JREs.
4.1921 + *
4.1922 + * Note: Unfortunately, SynchronizedRandomAccessList instances
4.1923 + * serialized in 1.4.1 and deserialized in 1.4 will become
4.1924 + * SynchronizedList instances, as this method was missing in 1.4.
4.1925 + */
4.1926 + private Object readResolve() {
4.1927 + return (list instanceof RandomAccess
4.1928 + ? new SynchronizedRandomAccessList<>(list)
4.1929 + : this);
4.1930 + }
4.1931 + }
4.1932 +
4.1933 + /**
4.1934 + * @serial include
4.1935 + */
4.1936 + static class SynchronizedRandomAccessList<E>
4.1937 + extends SynchronizedList<E>
4.1938 + implements RandomAccess {
4.1939 +
4.1940 + SynchronizedRandomAccessList(List<E> list) {
4.1941 + super(list);
4.1942 + }
4.1943 +
4.1944 + SynchronizedRandomAccessList(List<E> list, Object mutex) {
4.1945 + super(list, mutex);
4.1946 + }
4.1947 +
4.1948 + public List<E> subList(int fromIndex, int toIndex) {
4.1949 + synchronized (mutex) {
4.1950 + return new SynchronizedRandomAccessList<>(
4.1951 + list.subList(fromIndex, toIndex), mutex);
4.1952 + }
4.1953 + }
4.1954 +
4.1955 + private static final long serialVersionUID = 1530674583602358482L;
4.1956 +
4.1957 + /**
4.1958 + * Allows instances to be deserialized in pre-1.4 JREs (which do
4.1959 + * not have SynchronizedRandomAccessList). SynchronizedList has
4.1960 + * a readResolve method that inverts this transformation upon
4.1961 + * deserialization.
4.1962 + */
4.1963 + private Object writeReplace() {
4.1964 + return new SynchronizedList<>(list);
4.1965 + }
4.1966 + }
4.1967 +
4.1968 + /**
4.1969 + * Returns a synchronized (thread-safe) map backed by the specified
4.1970 + * map. In order to guarantee serial access, it is critical that
4.1971 + * <strong>all</strong> access to the backing map is accomplished
4.1972 + * through the returned map.<p>
4.1973 + *
4.1974 + * It is imperative that the user manually synchronize on the returned
4.1975 + * map when iterating over any of its collection views:
4.1976 + * <pre>
4.1977 + * Map m = Collections.synchronizedMap(new HashMap());
4.1978 + * ...
4.1979 + * Set s = m.keySet(); // Needn't be in synchronized block
4.1980 + * ...
4.1981 + * synchronized (m) { // Synchronizing on m, not s!
4.1982 + * Iterator i = s.iterator(); // Must be in synchronized block
4.1983 + * while (i.hasNext())
4.1984 + * foo(i.next());
4.1985 + * }
4.1986 + * </pre>
4.1987 + * Failure to follow this advice may result in non-deterministic behavior.
4.1988 + *
4.1989 + * <p>The returned map will be serializable if the specified map is
4.1990 + * serializable.
4.1991 + *
4.1992 + * @param m the map to be "wrapped" in a synchronized map.
4.1993 + * @return a synchronized view of the specified map.
4.1994 + */
4.1995 + public static <K,V> Map<K,V> synchronizedMap(Map<K,V> m) {
4.1996 + return new SynchronizedMap<>(m);
4.1997 + }
4.1998 +
4.1999 + /**
4.2000 + * @serial include
4.2001 + */
4.2002 + private static class SynchronizedMap<K,V>
4.2003 + implements Map<K,V>, Serializable {
4.2004 + private static final long serialVersionUID = 1978198479659022715L;
4.2005 +
4.2006 + private final Map<K,V> m; // Backing Map
4.2007 + final Object mutex; // Object on which to synchronize
4.2008 +
4.2009 + SynchronizedMap(Map<K,V> m) {
4.2010 + if (m==null)
4.2011 + throw new NullPointerException();
4.2012 + this.m = m;
4.2013 + mutex = this;
4.2014 + }
4.2015 +
4.2016 + SynchronizedMap(Map<K,V> m, Object mutex) {
4.2017 + this.m = m;
4.2018 + this.mutex = mutex;
4.2019 + }
4.2020 +
4.2021 + public int size() {
4.2022 + synchronized (mutex) {return m.size();}
4.2023 + }
4.2024 + public boolean isEmpty() {
4.2025 + synchronized (mutex) {return m.isEmpty();}
4.2026 + }
4.2027 + public boolean containsKey(Object key) {
4.2028 + synchronized (mutex) {return m.containsKey(key);}
4.2029 + }
4.2030 + public boolean containsValue(Object value) {
4.2031 + synchronized (mutex) {return m.containsValue(value);}
4.2032 + }
4.2033 + public V get(Object key) {
4.2034 + synchronized (mutex) {return m.get(key);}
4.2035 + }
4.2036 +
4.2037 + public V put(K key, V value) {
4.2038 + synchronized (mutex) {return m.put(key, value);}
4.2039 + }
4.2040 + public V remove(Object key) {
4.2041 + synchronized (mutex) {return m.remove(key);}
4.2042 + }
4.2043 + public void putAll(Map<? extends K, ? extends V> map) {
4.2044 + synchronized (mutex) {m.putAll(map);}
4.2045 + }
4.2046 + public void clear() {
4.2047 + synchronized (mutex) {m.clear();}
4.2048 + }
4.2049 +
4.2050 + private transient Set<K> keySet = null;
4.2051 + private transient Set<Map.Entry<K,V>> entrySet = null;
4.2052 + private transient Collection<V> values = null;
4.2053 +
4.2054 + public Set<K> keySet() {
4.2055 + synchronized (mutex) {
4.2056 + if (keySet==null)
4.2057 + keySet = new SynchronizedSet<>(m.keySet(), mutex);
4.2058 + return keySet;
4.2059 + }
4.2060 + }
4.2061 +
4.2062 + public Set<Map.Entry<K,V>> entrySet() {
4.2063 + synchronized (mutex) {
4.2064 + if (entrySet==null)
4.2065 + entrySet = new SynchronizedSet<>(m.entrySet(), mutex);
4.2066 + return entrySet;
4.2067 + }
4.2068 + }
4.2069 +
4.2070 + public Collection<V> values() {
4.2071 + synchronized (mutex) {
4.2072 + if (values==null)
4.2073 + values = new SynchronizedCollection<>(m.values(), mutex);
4.2074 + return values;
4.2075 + }
4.2076 + }
4.2077 +
4.2078 + public boolean equals(Object o) {
4.2079 + synchronized (mutex) {return m.equals(o);}
4.2080 + }
4.2081 + public int hashCode() {
4.2082 + synchronized (mutex) {return m.hashCode();}
4.2083 + }
4.2084 + public String toString() {
4.2085 + synchronized (mutex) {return m.toString();}
4.2086 + }
4.2087 + private void writeObject(ObjectOutputStream s) throws IOException {
4.2088 + synchronized (mutex) {s.defaultWriteObject();}
4.2089 + }
4.2090 + }
4.2091 +
4.2092 + /**
4.2093 + * Returns a synchronized (thread-safe) sorted map backed by the specified
4.2094 + * sorted map. In order to guarantee serial access, it is critical that
4.2095 + * <strong>all</strong> access to the backing sorted map is accomplished
4.2096 + * through the returned sorted map (or its views).<p>
4.2097 + *
4.2098 + * It is imperative that the user manually synchronize on the returned
4.2099 + * sorted map when iterating over any of its collection views, or the
4.2100 + * collections views of any of its <tt>subMap</tt>, <tt>headMap</tt> or
4.2101 + * <tt>tailMap</tt> views.
4.2102 + * <pre>
4.2103 + * SortedMap m = Collections.synchronizedSortedMap(new TreeMap());
4.2104 + * ...
4.2105 + * Set s = m.keySet(); // Needn't be in synchronized block
4.2106 + * ...
4.2107 + * synchronized (m) { // Synchronizing on m, not s!
4.2108 + * Iterator i = s.iterator(); // Must be in synchronized block
4.2109 + * while (i.hasNext())
4.2110 + * foo(i.next());
4.2111 + * }
4.2112 + * </pre>
4.2113 + * or:
4.2114 + * <pre>
4.2115 + * SortedMap m = Collections.synchronizedSortedMap(new TreeMap());
4.2116 + * SortedMap m2 = m.subMap(foo, bar);
4.2117 + * ...
4.2118 + * Set s2 = m2.keySet(); // Needn't be in synchronized block
4.2119 + * ...
4.2120 + * synchronized (m) { // Synchronizing on m, not m2 or s2!
4.2121 + * Iterator i = s.iterator(); // Must be in synchronized block
4.2122 + * while (i.hasNext())
4.2123 + * foo(i.next());
4.2124 + * }
4.2125 + * </pre>
4.2126 + * Failure to follow this advice may result in non-deterministic behavior.
4.2127 + *
4.2128 + * <p>The returned sorted map will be serializable if the specified
4.2129 + * sorted map is serializable.
4.2130 + *
4.2131 + * @param m the sorted map to be "wrapped" in a synchronized sorted map.
4.2132 + * @return a synchronized view of the specified sorted map.
4.2133 + */
4.2134 + public static <K,V> SortedMap<K,V> synchronizedSortedMap(SortedMap<K,V> m) {
4.2135 + return new SynchronizedSortedMap<>(m);
4.2136 + }
4.2137 +
4.2138 +
4.2139 + /**
4.2140 + * @serial include
4.2141 + */
4.2142 + static class SynchronizedSortedMap<K,V>
4.2143 + extends SynchronizedMap<K,V>
4.2144 + implements SortedMap<K,V>
4.2145 + {
4.2146 + private static final long serialVersionUID = -8798146769416483793L;
4.2147 +
4.2148 + private final SortedMap<K,V> sm;
4.2149 +
4.2150 + SynchronizedSortedMap(SortedMap<K,V> m) {
4.2151 + super(m);
4.2152 + sm = m;
4.2153 + }
4.2154 + SynchronizedSortedMap(SortedMap<K,V> m, Object mutex) {
4.2155 + super(m, mutex);
4.2156 + sm = m;
4.2157 + }
4.2158 +
4.2159 + public Comparator<? super K> comparator() {
4.2160 + synchronized (mutex) {return sm.comparator();}
4.2161 + }
4.2162 +
4.2163 + public SortedMap<K,V> subMap(K fromKey, K toKey) {
4.2164 + synchronized (mutex) {
4.2165 + return new SynchronizedSortedMap<>(
4.2166 + sm.subMap(fromKey, toKey), mutex);
4.2167 + }
4.2168 + }
4.2169 + public SortedMap<K,V> headMap(K toKey) {
4.2170 + synchronized (mutex) {
4.2171 + return new SynchronizedSortedMap<>(sm.headMap(toKey), mutex);
4.2172 + }
4.2173 + }
4.2174 + public SortedMap<K,V> tailMap(K fromKey) {
4.2175 + synchronized (mutex) {
4.2176 + return new SynchronizedSortedMap<>(sm.tailMap(fromKey),mutex);
4.2177 + }
4.2178 + }
4.2179 +
4.2180 + public K firstKey() {
4.2181 + synchronized (mutex) {return sm.firstKey();}
4.2182 + }
4.2183 + public K lastKey() {
4.2184 + synchronized (mutex) {return sm.lastKey();}
4.2185 + }
4.2186 + }
4.2187 +
4.2188 + // Dynamically typesafe collection wrappers
4.2189 +
4.2190 + /**
4.2191 + * Returns a dynamically typesafe view of the specified collection.
4.2192 + * Any attempt to insert an element of the wrong type will result in an
4.2193 + * immediate {@link ClassCastException}. Assuming a collection
4.2194 + * contains no incorrectly typed elements prior to the time a
4.2195 + * dynamically typesafe view is generated, and that all subsequent
4.2196 + * access to the collection takes place through the view, it is
4.2197 + * <i>guaranteed</i> that the collection cannot contain an incorrectly
4.2198 + * typed element.
4.2199 + *
4.2200 + * <p>The generics mechanism in the language provides compile-time
4.2201 + * (static) type checking, but it is possible to defeat this mechanism
4.2202 + * with unchecked casts. Usually this is not a problem, as the compiler
4.2203 + * issues warnings on all such unchecked operations. There are, however,
4.2204 + * times when static type checking alone is not sufficient. For example,
4.2205 + * suppose a collection is passed to a third-party library and it is
4.2206 + * imperative that the library code not corrupt the collection by
4.2207 + * inserting an element of the wrong type.
4.2208 + *
4.2209 + * <p>Another use of dynamically typesafe views is debugging. Suppose a
4.2210 + * program fails with a {@code ClassCastException}, indicating that an
4.2211 + * incorrectly typed element was put into a parameterized collection.
4.2212 + * Unfortunately, the exception can occur at any time after the erroneous
4.2213 + * element is inserted, so it typically provides little or no information
4.2214 + * as to the real source of the problem. If the problem is reproducible,
4.2215 + * one can quickly determine its source by temporarily modifying the
4.2216 + * program to wrap the collection with a dynamically typesafe view.
4.2217 + * For example, this declaration:
4.2218 + * <pre> {@code
4.2219 + * Collection<String> c = new HashSet<String>();
4.2220 + * }</pre>
4.2221 + * may be replaced temporarily by this one:
4.2222 + * <pre> {@code
4.2223 + * Collection<String> c = Collections.checkedCollection(
4.2224 + * new HashSet<String>(), String.class);
4.2225 + * }</pre>
4.2226 + * Running the program again will cause it to fail at the point where
4.2227 + * an incorrectly typed element is inserted into the collection, clearly
4.2228 + * identifying the source of the problem. Once the problem is fixed, the
4.2229 + * modified declaration may be reverted back to the original.
4.2230 + *
4.2231 + * <p>The returned collection does <i>not</i> pass the hashCode and equals
4.2232 + * operations through to the backing collection, but relies on
4.2233 + * {@code Object}'s {@code equals} and {@code hashCode} methods. This
4.2234 + * is necessary to preserve the contracts of these operations in the case
4.2235 + * that the backing collection is a set or a list.
4.2236 + *
4.2237 + * <p>The returned collection will be serializable if the specified
4.2238 + * collection is serializable.
4.2239 + *
4.2240 + * <p>Since {@code null} is considered to be a value of any reference
4.2241 + * type, the returned collection permits insertion of null elements
4.2242 + * whenever the backing collection does.
4.2243 + *
4.2244 + * @param c the collection for which a dynamically typesafe view is to be
4.2245 + * returned
4.2246 + * @param type the type of element that {@code c} is permitted to hold
4.2247 + * @return a dynamically typesafe view of the specified collection
4.2248 + * @since 1.5
4.2249 + */
4.2250 + public static <E> Collection<E> checkedCollection(Collection<E> c,
4.2251 + Class<E> type) {
4.2252 + return new CheckedCollection<>(c, type);
4.2253 + }
4.2254 +
4.2255 + @SuppressWarnings("unchecked")
4.2256 + static <T> T[] zeroLengthArray(Class<T> type) {
4.2257 + return (T[]) Array.newInstance(type, 0);
4.2258 + }
4.2259 +
4.2260 + /**
4.2261 + * @serial include
4.2262 + */
4.2263 + static class CheckedCollection<E> implements Collection<E>, Serializable {
4.2264 + private static final long serialVersionUID = 1578914078182001775L;
4.2265 +
4.2266 + final Collection<E> c;
4.2267 + final Class<E> type;
4.2268 +
4.2269 + void typeCheck(Object o) {
4.2270 + if (o != null && !type.isInstance(o))
4.2271 + throw new ClassCastException(badElementMsg(o));
4.2272 + }
4.2273 +
4.2274 + private String badElementMsg(Object o) {
4.2275 + return "Attempt to insert " + o.getClass() +
4.2276 + " element into collection with element type " + type;
4.2277 + }
4.2278 +
4.2279 + CheckedCollection(Collection<E> c, Class<E> type) {
4.2280 + if (c==null || type == null)
4.2281 + throw new NullPointerException();
4.2282 + this.c = c;
4.2283 + this.type = type;
4.2284 + }
4.2285 +
4.2286 + public int size() { return c.size(); }
4.2287 + public boolean isEmpty() { return c.isEmpty(); }
4.2288 + public boolean contains(Object o) { return c.contains(o); }
4.2289 + public Object[] toArray() { return c.toArray(); }
4.2290 + public <T> T[] toArray(T[] a) { return c.toArray(a); }
4.2291 + public String toString() { return c.toString(); }
4.2292 + public boolean remove(Object o) { return c.remove(o); }
4.2293 + public void clear() { c.clear(); }
4.2294 +
4.2295 + public boolean containsAll(Collection<?> coll) {
4.2296 + return c.containsAll(coll);
4.2297 + }
4.2298 + public boolean removeAll(Collection<?> coll) {
4.2299 + return c.removeAll(coll);
4.2300 + }
4.2301 + public boolean retainAll(Collection<?> coll) {
4.2302 + return c.retainAll(coll);
4.2303 + }
4.2304 +
4.2305 + public Iterator<E> iterator() {
4.2306 + final Iterator<E> it = c.iterator();
4.2307 + return new Iterator<E>() {
4.2308 + public boolean hasNext() { return it.hasNext(); }
4.2309 + public E next() { return it.next(); }
4.2310 + public void remove() { it.remove(); }};
4.2311 + }
4.2312 +
4.2313 + public boolean add(E e) {
4.2314 + typeCheck(e);
4.2315 + return c.add(e);
4.2316 + }
4.2317 +
4.2318 + private E[] zeroLengthElementArray = null; // Lazily initialized
4.2319 +
4.2320 + private E[] zeroLengthElementArray() {
4.2321 + return zeroLengthElementArray != null ? zeroLengthElementArray :
4.2322 + (zeroLengthElementArray = zeroLengthArray(type));
4.2323 + }
4.2324 +
4.2325 + @SuppressWarnings("unchecked")
4.2326 + Collection<E> checkedCopyOf(Collection<? extends E> coll) {
4.2327 + Object[] a = null;
4.2328 + try {
4.2329 + E[] z = zeroLengthElementArray();
4.2330 + a = coll.toArray(z);
4.2331 + // Defend against coll violating the toArray contract
4.2332 + if (a.getClass() != z.getClass())
4.2333 + a = Arrays.copyOf(a, a.length, z.getClass());
4.2334 + } catch (ArrayStoreException ignore) {
4.2335 + // To get better and consistent diagnostics,
4.2336 + // we call typeCheck explicitly on each element.
4.2337 + // We call clone() to defend against coll retaining a
4.2338 + // reference to the returned array and storing a bad
4.2339 + // element into it after it has been type checked.
4.2340 + a = coll.toArray().clone();
4.2341 + for (Object o : a)
4.2342 + typeCheck(o);
4.2343 + }
4.2344 + // A slight abuse of the type system, but safe here.
4.2345 + return (Collection<E>) Arrays.asList(a);
4.2346 + }
4.2347 +
4.2348 + public boolean addAll(Collection<? extends E> coll) {
4.2349 + // Doing things this way insulates us from concurrent changes
4.2350 + // in the contents of coll and provides all-or-nothing
4.2351 + // semantics (which we wouldn't get if we type-checked each
4.2352 + // element as we added it)
4.2353 + return c.addAll(checkedCopyOf(coll));
4.2354 + }
4.2355 + }
4.2356 +
4.2357 + /**
4.2358 + * Returns a dynamically typesafe view of the specified set.
4.2359 + * Any attempt to insert an element of the wrong type will result in
4.2360 + * an immediate {@link ClassCastException}. Assuming a set contains
4.2361 + * no incorrectly typed elements prior to the time a dynamically typesafe
4.2362 + * view is generated, and that all subsequent access to the set
4.2363 + * takes place through the view, it is <i>guaranteed</i> that the
4.2364 + * set cannot contain an incorrectly typed element.
4.2365 + *
4.2366 + * <p>A discussion of the use of dynamically typesafe views may be
4.2367 + * found in the documentation for the {@link #checkedCollection
4.2368 + * checkedCollection} method.
4.2369 + *
4.2370 + * <p>The returned set will be serializable if the specified set is
4.2371 + * serializable.
4.2372 + *
4.2373 + * <p>Since {@code null} is considered to be a value of any reference
4.2374 + * type, the returned set permits insertion of null elements whenever
4.2375 + * the backing set does.
4.2376 + *
4.2377 + * @param s the set for which a dynamically typesafe view is to be
4.2378 + * returned
4.2379 + * @param type the type of element that {@code s} is permitted to hold
4.2380 + * @return a dynamically typesafe view of the specified set
4.2381 + * @since 1.5
4.2382 + */
4.2383 + public static <E> Set<E> checkedSet(Set<E> s, Class<E> type) {
4.2384 + return new CheckedSet<>(s, type);
4.2385 + }
4.2386 +
4.2387 + /**
4.2388 + * @serial include
4.2389 + */
4.2390 + static class CheckedSet<E> extends CheckedCollection<E>
4.2391 + implements Set<E>, Serializable
4.2392 + {
4.2393 + private static final long serialVersionUID = 4694047833775013803L;
4.2394 +
4.2395 + CheckedSet(Set<E> s, Class<E> elementType) { super(s, elementType); }
4.2396 +
4.2397 + public boolean equals(Object o) { return o == this || c.equals(o); }
4.2398 + public int hashCode() { return c.hashCode(); }
4.2399 + }
4.2400 +
4.2401 + /**
4.2402 + * Returns a dynamically typesafe view of the specified sorted set.
4.2403 + * Any attempt to insert an element of the wrong type will result in an
4.2404 + * immediate {@link ClassCastException}. Assuming a sorted set
4.2405 + * contains no incorrectly typed elements prior to the time a
4.2406 + * dynamically typesafe view is generated, and that all subsequent
4.2407 + * access to the sorted set takes place through the view, it is
4.2408 + * <i>guaranteed</i> that the sorted set cannot contain an incorrectly
4.2409 + * typed element.
4.2410 + *
4.2411 + * <p>A discussion of the use of dynamically typesafe views may be
4.2412 + * found in the documentation for the {@link #checkedCollection
4.2413 + * checkedCollection} method.
4.2414 + *
4.2415 + * <p>The returned sorted set will be serializable if the specified sorted
4.2416 + * set is serializable.
4.2417 + *
4.2418 + * <p>Since {@code null} is considered to be a value of any reference
4.2419 + * type, the returned sorted set permits insertion of null elements
4.2420 + * whenever the backing sorted set does.
4.2421 + *
4.2422 + * @param s the sorted set for which a dynamically typesafe view is to be
4.2423 + * returned
4.2424 + * @param type the type of element that {@code s} is permitted to hold
4.2425 + * @return a dynamically typesafe view of the specified sorted set
4.2426 + * @since 1.5
4.2427 + */
4.2428 + public static <E> SortedSet<E> checkedSortedSet(SortedSet<E> s,
4.2429 + Class<E> type) {
4.2430 + return new CheckedSortedSet<>(s, type);
4.2431 + }
4.2432 +
4.2433 + /**
4.2434 + * @serial include
4.2435 + */
4.2436 + static class CheckedSortedSet<E> extends CheckedSet<E>
4.2437 + implements SortedSet<E>, Serializable
4.2438 + {
4.2439 + private static final long serialVersionUID = 1599911165492914959L;
4.2440 + private final SortedSet<E> ss;
4.2441 +
4.2442 + CheckedSortedSet(SortedSet<E> s, Class<E> type) {
4.2443 + super(s, type);
4.2444 + ss = s;
4.2445 + }
4.2446 +
4.2447 + public Comparator<? super E> comparator() { return ss.comparator(); }
4.2448 + public E first() { return ss.first(); }
4.2449 + public E last() { return ss.last(); }
4.2450 +
4.2451 + public SortedSet<E> subSet(E fromElement, E toElement) {
4.2452 + return checkedSortedSet(ss.subSet(fromElement,toElement), type);
4.2453 + }
4.2454 + public SortedSet<E> headSet(E toElement) {
4.2455 + return checkedSortedSet(ss.headSet(toElement), type);
4.2456 + }
4.2457 + public SortedSet<E> tailSet(E fromElement) {
4.2458 + return checkedSortedSet(ss.tailSet(fromElement), type);
4.2459 + }
4.2460 + }
4.2461 +
4.2462 + /**
4.2463 + * Returns a dynamically typesafe view of the specified list.
4.2464 + * Any attempt to insert an element of the wrong type will result in
4.2465 + * an immediate {@link ClassCastException}. Assuming a list contains
4.2466 + * no incorrectly typed elements prior to the time a dynamically typesafe
4.2467 + * view is generated, and that all subsequent access to the list
4.2468 + * takes place through the view, it is <i>guaranteed</i> that the
4.2469 + * list cannot contain an incorrectly typed element.
4.2470 + *
4.2471 + * <p>A discussion of the use of dynamically typesafe views may be
4.2472 + * found in the documentation for the {@link #checkedCollection
4.2473 + * checkedCollection} method.
4.2474 + *
4.2475 + * <p>The returned list will be serializable if the specified list
4.2476 + * is serializable.
4.2477 + *
4.2478 + * <p>Since {@code null} is considered to be a value of any reference
4.2479 + * type, the returned list permits insertion of null elements whenever
4.2480 + * the backing list does.
4.2481 + *
4.2482 + * @param list the list for which a dynamically typesafe view is to be
4.2483 + * returned
4.2484 + * @param type the type of element that {@code list} is permitted to hold
4.2485 + * @return a dynamically typesafe view of the specified list
4.2486 + * @since 1.5
4.2487 + */
4.2488 + public static <E> List<E> checkedList(List<E> list, Class<E> type) {
4.2489 + return (list instanceof RandomAccess ?
4.2490 + new CheckedRandomAccessList<>(list, type) :
4.2491 + new CheckedList<>(list, type));
4.2492 + }
4.2493 +
4.2494 + /**
4.2495 + * @serial include
4.2496 + */
4.2497 + static class CheckedList<E>
4.2498 + extends CheckedCollection<E>
4.2499 + implements List<E>
4.2500 + {
4.2501 + private static final long serialVersionUID = 65247728283967356L;
4.2502 + final List<E> list;
4.2503 +
4.2504 + CheckedList(List<E> list, Class<E> type) {
4.2505 + super(list, type);
4.2506 + this.list = list;
4.2507 + }
4.2508 +
4.2509 + public boolean equals(Object o) { return o == this || list.equals(o); }
4.2510 + public int hashCode() { return list.hashCode(); }
4.2511 + public E get(int index) { return list.get(index); }
4.2512 + public E remove(int index) { return list.remove(index); }
4.2513 + public int indexOf(Object o) { return list.indexOf(o); }
4.2514 + public int lastIndexOf(Object o) { return list.lastIndexOf(o); }
4.2515 +
4.2516 + public E set(int index, E element) {
4.2517 + typeCheck(element);
4.2518 + return list.set(index, element);
4.2519 + }
4.2520 +
4.2521 + public void add(int index, E element) {
4.2522 + typeCheck(element);
4.2523 + list.add(index, element);
4.2524 + }
4.2525 +
4.2526 + public boolean addAll(int index, Collection<? extends E> c) {
4.2527 + return list.addAll(index, checkedCopyOf(c));
4.2528 + }
4.2529 + public ListIterator<E> listIterator() { return listIterator(0); }
4.2530 +
4.2531 + public ListIterator<E> listIterator(final int index) {
4.2532 + final ListIterator<E> i = list.listIterator(index);
4.2533 +
4.2534 + return new ListIterator<E>() {
4.2535 + public boolean hasNext() { return i.hasNext(); }
4.2536 + public E next() { return i.next(); }
4.2537 + public boolean hasPrevious() { return i.hasPrevious(); }
4.2538 + public E previous() { return i.previous(); }
4.2539 + public int nextIndex() { return i.nextIndex(); }
4.2540 + public int previousIndex() { return i.previousIndex(); }
4.2541 + public void remove() { i.remove(); }
4.2542 +
4.2543 + public void set(E e) {
4.2544 + typeCheck(e);
4.2545 + i.set(e);
4.2546 + }
4.2547 +
4.2548 + public void add(E e) {
4.2549 + typeCheck(e);
4.2550 + i.add(e);
4.2551 + }
4.2552 + };
4.2553 + }
4.2554 +
4.2555 + public List<E> subList(int fromIndex, int toIndex) {
4.2556 + return new CheckedList<>(list.subList(fromIndex, toIndex), type);
4.2557 + }
4.2558 + }
4.2559 +
4.2560 + /**
4.2561 + * @serial include
4.2562 + */
4.2563 + static class CheckedRandomAccessList<E> extends CheckedList<E>
4.2564 + implements RandomAccess
4.2565 + {
4.2566 + private static final long serialVersionUID = 1638200125423088369L;
4.2567 +
4.2568 + CheckedRandomAccessList(List<E> list, Class<E> type) {
4.2569 + super(list, type);
4.2570 + }
4.2571 +
4.2572 + public List<E> subList(int fromIndex, int toIndex) {
4.2573 + return new CheckedRandomAccessList<>(
4.2574 + list.subList(fromIndex, toIndex), type);
4.2575 + }
4.2576 + }
4.2577 +
4.2578 + /**
4.2579 + * Returns a dynamically typesafe view of the specified map.
4.2580 + * Any attempt to insert a mapping whose key or value have the wrong
4.2581 + * type will result in an immediate {@link ClassCastException}.
4.2582 + * Similarly, any attempt to modify the value currently associated with
4.2583 + * a key will result in an immediate {@link ClassCastException},
4.2584 + * whether the modification is attempted directly through the map
4.2585 + * itself, or through a {@link Map.Entry} instance obtained from the
4.2586 + * map's {@link Map#entrySet() entry set} view.
4.2587 + *
4.2588 + * <p>Assuming a map contains no incorrectly typed keys or values
4.2589 + * prior to the time a dynamically typesafe view is generated, and
4.2590 + * that all subsequent access to the map takes place through the view
4.2591 + * (or one of its collection views), it is <i>guaranteed</i> that the
4.2592 + * map cannot contain an incorrectly typed key or value.
4.2593 + *
4.2594 + * <p>A discussion of the use of dynamically typesafe views may be
4.2595 + * found in the documentation for the {@link #checkedCollection
4.2596 + * checkedCollection} method.
4.2597 + *
4.2598 + * <p>The returned map will be serializable if the specified map is
4.2599 + * serializable.
4.2600 + *
4.2601 + * <p>Since {@code null} is considered to be a value of any reference
4.2602 + * type, the returned map permits insertion of null keys or values
4.2603 + * whenever the backing map does.
4.2604 + *
4.2605 + * @param m the map for which a dynamically typesafe view is to be
4.2606 + * returned
4.2607 + * @param keyType the type of key that {@code m} is permitted to hold
4.2608 + * @param valueType the type of value that {@code m} is permitted to hold
4.2609 + * @return a dynamically typesafe view of the specified map
4.2610 + * @since 1.5
4.2611 + */
4.2612 + public static <K, V> Map<K, V> checkedMap(Map<K, V> m,
4.2613 + Class<K> keyType,
4.2614 + Class<V> valueType) {
4.2615 + return new CheckedMap<>(m, keyType, valueType);
4.2616 + }
4.2617 +
4.2618 +
4.2619 + /**
4.2620 + * @serial include
4.2621 + */
4.2622 + private static class CheckedMap<K,V>
4.2623 + implements Map<K,V>, Serializable
4.2624 + {
4.2625 + private static final long serialVersionUID = 5742860141034234728L;
4.2626 +
4.2627 + private final Map<K, V> m;
4.2628 + final Class<K> keyType;
4.2629 + final Class<V> valueType;
4.2630 +
4.2631 + private void typeCheck(Object key, Object value) {
4.2632 + if (key != null && !keyType.isInstance(key))
4.2633 + throw new ClassCastException(badKeyMsg(key));
4.2634 +
4.2635 + if (value != null && !valueType.isInstance(value))
4.2636 + throw new ClassCastException(badValueMsg(value));
4.2637 + }
4.2638 +
4.2639 + private String badKeyMsg(Object key) {
4.2640 + return "Attempt to insert " + key.getClass() +
4.2641 + " key into map with key type " + keyType;
4.2642 + }
4.2643 +
4.2644 + private String badValueMsg(Object value) {
4.2645 + return "Attempt to insert " + value.getClass() +
4.2646 + " value into map with value type " + valueType;
4.2647 + }
4.2648 +
4.2649 + CheckedMap(Map<K, V> m, Class<K> keyType, Class<V> valueType) {
4.2650 + if (m == null || keyType == null || valueType == null)
4.2651 + throw new NullPointerException();
4.2652 + this.m = m;
4.2653 + this.keyType = keyType;
4.2654 + this.valueType = valueType;
4.2655 + }
4.2656 +
4.2657 + public int size() { return m.size(); }
4.2658 + public boolean isEmpty() { return m.isEmpty(); }
4.2659 + public boolean containsKey(Object key) { return m.containsKey(key); }
4.2660 + public boolean containsValue(Object v) { return m.containsValue(v); }
4.2661 + public V get(Object key) { return m.get(key); }
4.2662 + public V remove(Object key) { return m.remove(key); }
4.2663 + public void clear() { m.clear(); }
4.2664 + public Set<K> keySet() { return m.keySet(); }
4.2665 + public Collection<V> values() { return m.values(); }
4.2666 + public boolean equals(Object o) { return o == this || m.equals(o); }
4.2667 + public int hashCode() { return m.hashCode(); }
4.2668 + public String toString() { return m.toString(); }
4.2669 +
4.2670 + public V put(K key, V value) {
4.2671 + typeCheck(key, value);
4.2672 + return m.put(key, value);
4.2673 + }
4.2674 +
4.2675 + @SuppressWarnings("unchecked")
4.2676 + public void putAll(Map<? extends K, ? extends V> t) {
4.2677 + // Satisfy the following goals:
4.2678 + // - good diagnostics in case of type mismatch
4.2679 + // - all-or-nothing semantics
4.2680 + // - protection from malicious t
4.2681 + // - correct behavior if t is a concurrent map
4.2682 + Object[] entries = t.entrySet().toArray();
4.2683 + List<Map.Entry<K,V>> checked = new ArrayList<>(entries.length);
4.2684 + for (Object o : entries) {
4.2685 + Map.Entry<?,?> e = (Map.Entry<?,?>) o;
4.2686 + Object k = e.getKey();
4.2687 + Object v = e.getValue();
4.2688 + typeCheck(k, v);
4.2689 + checked.add(
4.2690 + new AbstractMap.SimpleImmutableEntry<>((K) k, (V) v));
4.2691 + }
4.2692 + for (Map.Entry<K,V> e : checked)
4.2693 + m.put(e.getKey(), e.getValue());
4.2694 + }
4.2695 +
4.2696 + private transient Set<Map.Entry<K,V>> entrySet = null;
4.2697 +
4.2698 + public Set<Map.Entry<K,V>> entrySet() {
4.2699 + if (entrySet==null)
4.2700 + entrySet = new CheckedEntrySet<>(m.entrySet(), valueType);
4.2701 + return entrySet;
4.2702 + }
4.2703 +
4.2704 + /**
4.2705 + * We need this class in addition to CheckedSet as Map.Entry permits
4.2706 + * modification of the backing Map via the setValue operation. This
4.2707 + * class is subtle: there are many possible attacks that must be
4.2708 + * thwarted.
4.2709 + *
4.2710 + * @serial exclude
4.2711 + */
4.2712 + static class CheckedEntrySet<K,V> implements Set<Map.Entry<K,V>> {
4.2713 + private final Set<Map.Entry<K,V>> s;
4.2714 + private final Class<V> valueType;
4.2715 +
4.2716 + CheckedEntrySet(Set<Map.Entry<K, V>> s, Class<V> valueType) {
4.2717 + this.s = s;
4.2718 + this.valueType = valueType;
4.2719 + }
4.2720 +
4.2721 + public int size() { return s.size(); }
4.2722 + public boolean isEmpty() { return s.isEmpty(); }
4.2723 + public String toString() { return s.toString(); }
4.2724 + public int hashCode() { return s.hashCode(); }
4.2725 + public void clear() { s.clear(); }
4.2726 +
4.2727 + public boolean add(Map.Entry<K, V> e) {
4.2728 + throw new UnsupportedOperationException();
4.2729 + }
4.2730 + public boolean addAll(Collection<? extends Map.Entry<K, V>> coll) {
4.2731 + throw new UnsupportedOperationException();
4.2732 + }
4.2733 +
4.2734 + public Iterator<Map.Entry<K,V>> iterator() {
4.2735 + final Iterator<Map.Entry<K, V>> i = s.iterator();
4.2736 + final Class<V> valueType = this.valueType;
4.2737 +
4.2738 + return new Iterator<Map.Entry<K,V>>() {
4.2739 + public boolean hasNext() { return i.hasNext(); }
4.2740 + public void remove() { i.remove(); }
4.2741 +
4.2742 + public Map.Entry<K,V> next() {
4.2743 + return checkedEntry(i.next(), valueType);
4.2744 + }
4.2745 + };
4.2746 + }
4.2747 +
4.2748 + @SuppressWarnings("unchecked")
4.2749 + public Object[] toArray() {
4.2750 + Object[] source = s.toArray();
4.2751 +
4.2752 + /*
4.2753 + * Ensure that we don't get an ArrayStoreException even if
4.2754 + * s.toArray returns an array of something other than Object
4.2755 + */
4.2756 + Object[] dest = (CheckedEntry.class.isInstance(
4.2757 + source.getClass().getComponentType()) ? source :
4.2758 + new Object[source.length]);
4.2759 +
4.2760 + for (int i = 0; i < source.length; i++)
4.2761 + dest[i] = checkedEntry((Map.Entry<K,V>)source[i],
4.2762 + valueType);
4.2763 + return dest;
4.2764 + }
4.2765 +
4.2766 + @SuppressWarnings("unchecked")
4.2767 + public <T> T[] toArray(T[] a) {
4.2768 + // We don't pass a to s.toArray, to avoid window of
4.2769 + // vulnerability wherein an unscrupulous multithreaded client
4.2770 + // could get his hands on raw (unwrapped) Entries from s.
4.2771 + T[] arr = s.toArray(a.length==0 ? a : Arrays.copyOf(a, 0));
4.2772 +
4.2773 + for (int i=0; i<arr.length; i++)
4.2774 + arr[i] = (T) checkedEntry((Map.Entry<K,V>)arr[i],
4.2775 + valueType);
4.2776 + if (arr.length > a.length)
4.2777 + return arr;
4.2778 +
4.2779 + System.arraycopy(arr, 0, a, 0, arr.length);
4.2780 + if (a.length > arr.length)
4.2781 + a[arr.length] = null;
4.2782 + return a;
4.2783 + }
4.2784 +
4.2785 + /**
4.2786 + * This method is overridden to protect the backing set against
4.2787 + * an object with a nefarious equals function that senses
4.2788 + * that the equality-candidate is Map.Entry and calls its
4.2789 + * setValue method.
4.2790 + */
4.2791 + public boolean contains(Object o) {
4.2792 + if (!(o instanceof Map.Entry))
4.2793 + return false;
4.2794 + Map.Entry<?,?> e = (Map.Entry<?,?>) o;
4.2795 + return s.contains(
4.2796 + (e instanceof CheckedEntry) ? e : checkedEntry(e, valueType));
4.2797 + }
4.2798 +
4.2799 + /**
4.2800 + * The bulk collection methods are overridden to protect
4.2801 + * against an unscrupulous collection whose contains(Object o)
4.2802 + * method senses when o is a Map.Entry, and calls o.setValue.
4.2803 + */
4.2804 + public boolean containsAll(Collection<?> c) {
4.2805 + for (Object o : c)
4.2806 + if (!contains(o)) // Invokes safe contains() above
4.2807 + return false;
4.2808 + return true;
4.2809 + }
4.2810 +
4.2811 + public boolean remove(Object o) {
4.2812 + if (!(o instanceof Map.Entry))
4.2813 + return false;
4.2814 + return s.remove(new AbstractMap.SimpleImmutableEntry
4.2815 + <>((Map.Entry<?,?>)o));
4.2816 + }
4.2817 +
4.2818 + public boolean removeAll(Collection<?> c) {
4.2819 + return batchRemove(c, false);
4.2820 + }
4.2821 + public boolean retainAll(Collection<?> c) {
4.2822 + return batchRemove(c, true);
4.2823 + }
4.2824 + private boolean batchRemove(Collection<?> c, boolean complement) {
4.2825 + boolean modified = false;
4.2826 + Iterator<Map.Entry<K,V>> it = iterator();
4.2827 + while (it.hasNext()) {
4.2828 + if (c.contains(it.next()) != complement) {
4.2829 + it.remove();
4.2830 + modified = true;
4.2831 + }
4.2832 + }
4.2833 + return modified;
4.2834 + }
4.2835 +
4.2836 + public boolean equals(Object o) {
4.2837 + if (o == this)
4.2838 + return true;
4.2839 + if (!(o instanceof Set))
4.2840 + return false;
4.2841 + Set<?> that = (Set<?>) o;
4.2842 + return that.size() == s.size()
4.2843 + && containsAll(that); // Invokes safe containsAll() above
4.2844 + }
4.2845 +
4.2846 + static <K,V,T> CheckedEntry<K,V,T> checkedEntry(Map.Entry<K,V> e,
4.2847 + Class<T> valueType) {
4.2848 + return new CheckedEntry<>(e, valueType);
4.2849 + }
4.2850 +
4.2851 + /**
4.2852 + * This "wrapper class" serves two purposes: it prevents
4.2853 + * the client from modifying the backing Map, by short-circuiting
4.2854 + * the setValue method, and it protects the backing Map against
4.2855 + * an ill-behaved Map.Entry that attempts to modify another
4.2856 + * Map.Entry when asked to perform an equality check.
4.2857 + */
4.2858 + private static class CheckedEntry<K,V,T> implements Map.Entry<K,V> {
4.2859 + private final Map.Entry<K, V> e;
4.2860 + private final Class<T> valueType;
4.2861 +
4.2862 + CheckedEntry(Map.Entry<K, V> e, Class<T> valueType) {
4.2863 + this.e = e;
4.2864 + this.valueType = valueType;
4.2865 + }
4.2866 +
4.2867 + public K getKey() { return e.getKey(); }
4.2868 + public V getValue() { return e.getValue(); }
4.2869 + public int hashCode() { return e.hashCode(); }
4.2870 + public String toString() { return e.toString(); }
4.2871 +
4.2872 + public V setValue(V value) {
4.2873 + if (value != null && !valueType.isInstance(value))
4.2874 + throw new ClassCastException(badValueMsg(value));
4.2875 + return e.setValue(value);
4.2876 + }
4.2877 +
4.2878 + private String badValueMsg(Object value) {
4.2879 + return "Attempt to insert " + value.getClass() +
4.2880 + " value into map with value type " + valueType;
4.2881 + }
4.2882 +
4.2883 + public boolean equals(Object o) {
4.2884 + if (o == this)
4.2885 + return true;
4.2886 + if (!(o instanceof Map.Entry))
4.2887 + return false;
4.2888 + return e.equals(new AbstractMap.SimpleImmutableEntry
4.2889 + <>((Map.Entry<?,?>)o));
4.2890 + }
4.2891 + }
4.2892 + }
4.2893 + }
4.2894 +
4.2895 + /**
4.2896 + * Returns a dynamically typesafe view of the specified sorted map.
4.2897 + * Any attempt to insert a mapping whose key or value have the wrong
4.2898 + * type will result in an immediate {@link ClassCastException}.
4.2899 + * Similarly, any attempt to modify the value currently associated with
4.2900 + * a key will result in an immediate {@link ClassCastException},
4.2901 + * whether the modification is attempted directly through the map
4.2902 + * itself, or through a {@link Map.Entry} instance obtained from the
4.2903 + * map's {@link Map#entrySet() entry set} view.
4.2904 + *
4.2905 + * <p>Assuming a map contains no incorrectly typed keys or values
4.2906 + * prior to the time a dynamically typesafe view is generated, and
4.2907 + * that all subsequent access to the map takes place through the view
4.2908 + * (or one of its collection views), it is <i>guaranteed</i> that the
4.2909 + * map cannot contain an incorrectly typed key or value.
4.2910 + *
4.2911 + * <p>A discussion of the use of dynamically typesafe views may be
4.2912 + * found in the documentation for the {@link #checkedCollection
4.2913 + * checkedCollection} method.
4.2914 + *
4.2915 + * <p>The returned map will be serializable if the specified map is
4.2916 + * serializable.
4.2917 + *
4.2918 + * <p>Since {@code null} is considered to be a value of any reference
4.2919 + * type, the returned map permits insertion of null keys or values
4.2920 + * whenever the backing map does.
4.2921 + *
4.2922 + * @param m the map for which a dynamically typesafe view is to be
4.2923 + * returned
4.2924 + * @param keyType the type of key that {@code m} is permitted to hold
4.2925 + * @param valueType the type of value that {@code m} is permitted to hold
4.2926 + * @return a dynamically typesafe view of the specified map
4.2927 + * @since 1.5
4.2928 + */
4.2929 + public static <K,V> SortedMap<K,V> checkedSortedMap(SortedMap<K, V> m,
4.2930 + Class<K> keyType,
4.2931 + Class<V> valueType) {
4.2932 + return new CheckedSortedMap<>(m, keyType, valueType);
4.2933 + }
4.2934 +
4.2935 + /**
4.2936 + * @serial include
4.2937 + */
4.2938 + static class CheckedSortedMap<K,V> extends CheckedMap<K,V>
4.2939 + implements SortedMap<K,V>, Serializable
4.2940 + {
4.2941 + private static final long serialVersionUID = 1599671320688067438L;
4.2942 +
4.2943 + private final SortedMap<K, V> sm;
4.2944 +
4.2945 + CheckedSortedMap(SortedMap<K, V> m,
4.2946 + Class<K> keyType, Class<V> valueType) {
4.2947 + super(m, keyType, valueType);
4.2948 + sm = m;
4.2949 + }
4.2950 +
4.2951 + public Comparator<? super K> comparator() { return sm.comparator(); }
4.2952 + public K firstKey() { return sm.firstKey(); }
4.2953 + public K lastKey() { return sm.lastKey(); }
4.2954 +
4.2955 + public SortedMap<K,V> subMap(K fromKey, K toKey) {
4.2956 + return checkedSortedMap(sm.subMap(fromKey, toKey),
4.2957 + keyType, valueType);
4.2958 + }
4.2959 + public SortedMap<K,V> headMap(K toKey) {
4.2960 + return checkedSortedMap(sm.headMap(toKey), keyType, valueType);
4.2961 + }
4.2962 + public SortedMap<K,V> tailMap(K fromKey) {
4.2963 + return checkedSortedMap(sm.tailMap(fromKey), keyType, valueType);
4.2964 + }
4.2965 + }
4.2966 +
4.2967 + // Empty collections
4.2968 +
4.2969 + /**
4.2970 + * Returns an iterator that has no elements. More precisely,
4.2971 + *
4.2972 + * <ul compact>
4.2973 + *
4.2974 + * <li>{@link Iterator#hasNext hasNext} always returns {@code
4.2975 + * false}.
4.2976 + *
4.2977 + * <li>{@link Iterator#next next} always throws {@link
4.2978 + * NoSuchElementException}.
4.2979 + *
4.2980 + * <li>{@link Iterator#remove remove} always throws {@link
4.2981 + * IllegalStateException}.
4.2982 + *
4.2983 + * </ul>
4.2984 + *
4.2985 + * <p>Implementations of this method are permitted, but not
4.2986 + * required, to return the same object from multiple invocations.
4.2987 + *
4.2988 + * @return an empty iterator
4.2989 + * @since 1.7
4.2990 + */
4.2991 + @SuppressWarnings("unchecked")
4.2992 + public static <T> Iterator<T> emptyIterator() {
4.2993 + return (Iterator<T>) EmptyIterator.EMPTY_ITERATOR;
4.2994 + }
4.2995 +
4.2996 + private static class EmptyIterator<E> implements Iterator<E> {
4.2997 + static final EmptyIterator<Object> EMPTY_ITERATOR
4.2998 + = new EmptyIterator<>();
4.2999 +
4.3000 + public boolean hasNext() { return false; }
4.3001 + public E next() { throw new NoSuchElementException(); }
4.3002 + public void remove() { throw new IllegalStateException(); }
4.3003 + }
4.3004 +
4.3005 + /**
4.3006 + * Returns a list iterator that has no elements. More precisely,
4.3007 + *
4.3008 + * <ul compact>
4.3009 + *
4.3010 + * <li>{@link Iterator#hasNext hasNext} and {@link
4.3011 + * ListIterator#hasPrevious hasPrevious} always return {@code
4.3012 + * false}.
4.3013 + *
4.3014 + * <li>{@link Iterator#next next} and {@link ListIterator#previous
4.3015 + * previous} always throw {@link NoSuchElementException}.
4.3016 + *
4.3017 + * <li>{@link Iterator#remove remove} and {@link ListIterator#set
4.3018 + * set} always throw {@link IllegalStateException}.
4.3019 + *
4.3020 + * <li>{@link ListIterator#add add} always throws {@link
4.3021 + * UnsupportedOperationException}.
4.3022 + *
4.3023 + * <li>{@link ListIterator#nextIndex nextIndex} always returns
4.3024 + * {@code 0} .
4.3025 + *
4.3026 + * <li>{@link ListIterator#previousIndex previousIndex} always
4.3027 + * returns {@code -1}.
4.3028 + *
4.3029 + * </ul>
4.3030 + *
4.3031 + * <p>Implementations of this method are permitted, but not
4.3032 + * required, to return the same object from multiple invocations.
4.3033 + *
4.3034 + * @return an empty list iterator
4.3035 + * @since 1.7
4.3036 + */
4.3037 + @SuppressWarnings("unchecked")
4.3038 + public static <T> ListIterator<T> emptyListIterator() {
4.3039 + return (ListIterator<T>) EmptyListIterator.EMPTY_ITERATOR;
4.3040 + }
4.3041 +
4.3042 + private static class EmptyListIterator<E>
4.3043 + extends EmptyIterator<E>
4.3044 + implements ListIterator<E>
4.3045 + {
4.3046 + static final EmptyListIterator<Object> EMPTY_ITERATOR
4.3047 + = new EmptyListIterator<>();
4.3048 +
4.3049 + public boolean hasPrevious() { return false; }
4.3050 + public E previous() { throw new NoSuchElementException(); }
4.3051 + public int nextIndex() { return 0; }
4.3052 + public int previousIndex() { return -1; }
4.3053 + public void set(E e) { throw new IllegalStateException(); }
4.3054 + public void add(E e) { throw new UnsupportedOperationException(); }
4.3055 + }
4.3056 +
4.3057 + /**
4.3058 + * Returns an enumeration that has no elements. More precisely,
4.3059 + *
4.3060 + * <ul compact>
4.3061 + *
4.3062 + * <li>{@link Enumeration#hasMoreElements hasMoreElements} always
4.3063 + * returns {@code false}.
4.3064 + *
4.3065 + * <li> {@link Enumeration#nextElement nextElement} always throws
4.3066 + * {@link NoSuchElementException}.
4.3067 + *
4.3068 + * </ul>
4.3069 + *
4.3070 + * <p>Implementations of this method are permitted, but not
4.3071 + * required, to return the same object from multiple invocations.
4.3072 + *
4.3073 + * @return an empty enumeration
4.3074 + * @since 1.7
4.3075 + */
4.3076 + @SuppressWarnings("unchecked")
4.3077 + public static <T> Enumeration<T> emptyEnumeration() {
4.3078 + return (Enumeration<T>) EmptyEnumeration.EMPTY_ENUMERATION;
4.3079 + }
4.3080 +
4.3081 + private static class EmptyEnumeration<E> implements Enumeration<E> {
4.3082 + static final EmptyEnumeration<Object> EMPTY_ENUMERATION
4.3083 + = new EmptyEnumeration<>();
4.3084 +
4.3085 + public boolean hasMoreElements() { return false; }
4.3086 + public E nextElement() { throw new NoSuchElementException(); }
4.3087 + }
4.3088 +
4.3089 + /**
4.3090 + * The empty set (immutable). This set is serializable.
4.3091 + *
4.3092 + * @see #emptySet()
4.3093 + */
4.3094 + @SuppressWarnings("unchecked")
4.3095 + public static final Set EMPTY_SET = new EmptySet<>();
4.3096 +
4.3097 + /**
4.3098 + * Returns the empty set (immutable). This set is serializable.
4.3099 + * Unlike the like-named field, this method is parameterized.
4.3100 + *
4.3101 + * <p>This example illustrates the type-safe way to obtain an empty set:
4.3102 + * <pre>
4.3103 + * Set<String> s = Collections.emptySet();
4.3104 + * </pre>
4.3105 + * Implementation note: Implementations of this method need not
4.3106 + * create a separate <tt>Set</tt> object for each call. Using this
4.3107 + * method is likely to have comparable cost to using the like-named
4.3108 + * field. (Unlike this method, the field does not provide type safety.)
4.3109 + *
4.3110 + * @see #EMPTY_SET
4.3111 + * @since 1.5
4.3112 + */
4.3113 + @SuppressWarnings("unchecked")
4.3114 + public static final <T> Set<T> emptySet() {
4.3115 + return (Set<T>) EMPTY_SET;
4.3116 + }
4.3117 +
4.3118 + /**
4.3119 + * @serial include
4.3120 + */
4.3121 + private static class EmptySet<E>
4.3122 + extends AbstractSet<E>
4.3123 + implements Serializable
4.3124 + {
4.3125 + private static final long serialVersionUID = 1582296315990362920L;
4.3126 +
4.3127 + public Iterator<E> iterator() { return emptyIterator(); }
4.3128 +
4.3129 + public int size() {return 0;}
4.3130 + public boolean isEmpty() {return true;}
4.3131 +
4.3132 + public boolean contains(Object obj) {return false;}
4.3133 + public boolean containsAll(Collection<?> c) { return c.isEmpty(); }
4.3134 +
4.3135 + public Object[] toArray() { return new Object[0]; }
4.3136 +
4.3137 + public <T> T[] toArray(T[] a) {
4.3138 + if (a.length > 0)
4.3139 + a[0] = null;
4.3140 + return a;
4.3141 + }
4.3142 +
4.3143 + // Preserves singleton property
4.3144 + private Object readResolve() {
4.3145 + return EMPTY_SET;
4.3146 + }
4.3147 + }
4.3148 +
4.3149 + /**
4.3150 + * The empty list (immutable). This list is serializable.
4.3151 + *
4.3152 + * @see #emptyList()
4.3153 + */
4.3154 + @SuppressWarnings("unchecked")
4.3155 + public static final List EMPTY_LIST = new EmptyList<>();
4.3156 +
4.3157 + /**
4.3158 + * Returns the empty list (immutable). This list is serializable.
4.3159 + *
4.3160 + * <p>This example illustrates the type-safe way to obtain an empty list:
4.3161 + * <pre>
4.3162 + * List<String> s = Collections.emptyList();
4.3163 + * </pre>
4.3164 + * Implementation note: Implementations of this method need not
4.3165 + * create a separate <tt>List</tt> object for each call. Using this
4.3166 + * method is likely to have comparable cost to using the like-named
4.3167 + * field. (Unlike this method, the field does not provide type safety.)
4.3168 + *
4.3169 + * @see #EMPTY_LIST
4.3170 + * @since 1.5
4.3171 + */
4.3172 + @SuppressWarnings("unchecked")
4.3173 + public static final <T> List<T> emptyList() {
4.3174 + return (List<T>) EMPTY_LIST;
4.3175 + }
4.3176 +
4.3177 + /**
4.3178 + * @serial include
4.3179 + */
4.3180 + private static class EmptyList<E>
4.3181 + extends AbstractList<E>
4.3182 + implements RandomAccess, Serializable {
4.3183 + private static final long serialVersionUID = 8842843931221139166L;
4.3184 +
4.3185 + public Iterator<E> iterator() {
4.3186 + return emptyIterator();
4.3187 + }
4.3188 + public ListIterator<E> listIterator() {
4.3189 + return emptyListIterator();
4.3190 + }
4.3191 +
4.3192 + public int size() {return 0;}
4.3193 + public boolean isEmpty() {return true;}
4.3194 +
4.3195 + public boolean contains(Object obj) {return false;}
4.3196 + public boolean containsAll(Collection<?> c) { return c.isEmpty(); }
4.3197 +
4.3198 + public Object[] toArray() { return new Object[0]; }
4.3199 +
4.3200 + public <T> T[] toArray(T[] a) {
4.3201 + if (a.length > 0)
4.3202 + a[0] = null;
4.3203 + return a;
4.3204 + }
4.3205 +
4.3206 + public E get(int index) {
4.3207 + throw new IndexOutOfBoundsException("Index: "+index);
4.3208 + }
4.3209 +
4.3210 + public boolean equals(Object o) {
4.3211 + return (o instanceof List) && ((List<?>)o).isEmpty();
4.3212 + }
4.3213 +
4.3214 + public int hashCode() { return 1; }
4.3215 +
4.3216 + // Preserves singleton property
4.3217 + private Object readResolve() {
4.3218 + return EMPTY_LIST;
4.3219 + }
4.3220 + }
4.3221 +
4.3222 + /**
4.3223 + * The empty map (immutable). This map is serializable.
4.3224 + *
4.3225 + * @see #emptyMap()
4.3226 + * @since 1.3
4.3227 + */
4.3228 + @SuppressWarnings("unchecked")
4.3229 + public static final Map EMPTY_MAP = new EmptyMap<>();
4.3230 +
4.3231 + /**
4.3232 + * Returns the empty map (immutable). This map is serializable.
4.3233 + *
4.3234 + * <p>This example illustrates the type-safe way to obtain an empty set:
4.3235 + * <pre>
4.3236 + * Map<String, Date> s = Collections.emptyMap();
4.3237 + * </pre>
4.3238 + * Implementation note: Implementations of this method need not
4.3239 + * create a separate <tt>Map</tt> object for each call. Using this
4.3240 + * method is likely to have comparable cost to using the like-named
4.3241 + * field. (Unlike this method, the field does not provide type safety.)
4.3242 + *
4.3243 + * @see #EMPTY_MAP
4.3244 + * @since 1.5
4.3245 + */
4.3246 + @SuppressWarnings("unchecked")
4.3247 + public static final <K,V> Map<K,V> emptyMap() {
4.3248 + return (Map<K,V>) EMPTY_MAP;
4.3249 + }
4.3250 +
4.3251 + /**
4.3252 + * @serial include
4.3253 + */
4.3254 + private static class EmptyMap<K,V>
4.3255 + extends AbstractMap<K,V>
4.3256 + implements Serializable
4.3257 + {
4.3258 + private static final long serialVersionUID = 6428348081105594320L;
4.3259 +
4.3260 + public int size() {return 0;}
4.3261 + public boolean isEmpty() {return true;}
4.3262 + public boolean containsKey(Object key) {return false;}
4.3263 + public boolean containsValue(Object value) {return false;}
4.3264 + public V get(Object key) {return null;}
4.3265 + public Set<K> keySet() {return emptySet();}
4.3266 + public Collection<V> values() {return emptySet();}
4.3267 + public Set<Map.Entry<K,V>> entrySet() {return emptySet();}
4.3268 +
4.3269 + public boolean equals(Object o) {
4.3270 + return (o instanceof Map) && ((Map<?,?>)o).isEmpty();
4.3271 + }
4.3272 +
4.3273 + public int hashCode() {return 0;}
4.3274 +
4.3275 + // Preserves singleton property
4.3276 + private Object readResolve() {
4.3277 + return EMPTY_MAP;
4.3278 + }
4.3279 + }
4.3280 +
4.3281 + // Singleton collections
4.3282 +
4.3283 + /**
4.3284 + * Returns an immutable set containing only the specified object.
4.3285 + * The returned set is serializable.
4.3286 + *
4.3287 + * @param o the sole object to be stored in the returned set.
4.3288 + * @return an immutable set containing only the specified object.
4.3289 + */
4.3290 + public static <T> Set<T> singleton(T o) {
4.3291 + return new SingletonSet<>(o);
4.3292 + }
4.3293 +
4.3294 + static <E> Iterator<E> singletonIterator(final E e) {
4.3295 + return new Iterator<E>() {
4.3296 + private boolean hasNext = true;
4.3297 + public boolean hasNext() {
4.3298 + return hasNext;
4.3299 + }
4.3300 + public E next() {
4.3301 + if (hasNext) {
4.3302 + hasNext = false;
4.3303 + return e;
4.3304 + }
4.3305 + throw new NoSuchElementException();
4.3306 + }
4.3307 + public void remove() {
4.3308 + throw new UnsupportedOperationException();
4.3309 + }
4.3310 + };
4.3311 + }
4.3312 +
4.3313 + /**
4.3314 + * @serial include
4.3315 + */
4.3316 + private static class SingletonSet<E>
4.3317 + extends AbstractSet<E>
4.3318 + implements Serializable
4.3319 + {
4.3320 + private static final long serialVersionUID = 3193687207550431679L;
4.3321 +
4.3322 + private final E element;
4.3323 +
4.3324 + SingletonSet(E e) {element = e;}
4.3325 +
4.3326 + public Iterator<E> iterator() {
4.3327 + return singletonIterator(element);
4.3328 + }
4.3329 +
4.3330 + public int size() {return 1;}
4.3331 +
4.3332 + public boolean contains(Object o) {return eq(o, element);}
4.3333 + }
4.3334 +
4.3335 + /**
4.3336 + * Returns an immutable list containing only the specified object.
4.3337 + * The returned list is serializable.
4.3338 + *
4.3339 + * @param o the sole object to be stored in the returned list.
4.3340 + * @return an immutable list containing only the specified object.
4.3341 + * @since 1.3
4.3342 + */
4.3343 + public static <T> List<T> singletonList(T o) {
4.3344 + return new SingletonList<>(o);
4.3345 + }
4.3346 +
4.3347 + /**
4.3348 + * @serial include
4.3349 + */
4.3350 + private static class SingletonList<E>
4.3351 + extends AbstractList<E>
4.3352 + implements RandomAccess, Serializable {
4.3353 +
4.3354 + private static final long serialVersionUID = 3093736618740652951L;
4.3355 +
4.3356 + private final E element;
4.3357 +
4.3358 + SingletonList(E obj) {element = obj;}
4.3359 +
4.3360 + public Iterator<E> iterator() {
4.3361 + return singletonIterator(element);
4.3362 + }
4.3363 +
4.3364 + public int size() {return 1;}
4.3365 +
4.3366 + public boolean contains(Object obj) {return eq(obj, element);}
4.3367 +
4.3368 + public E get(int index) {
4.3369 + if (index != 0)
4.3370 + throw new IndexOutOfBoundsException("Index: "+index+", Size: 1");
4.3371 + return element;
4.3372 + }
4.3373 + }
4.3374 +
4.3375 + /**
4.3376 + * Returns an immutable map, mapping only the specified key to the
4.3377 + * specified value. The returned map is serializable.
4.3378 + *
4.3379 + * @param key the sole key to be stored in the returned map.
4.3380 + * @param value the value to which the returned map maps <tt>key</tt>.
4.3381 + * @return an immutable map containing only the specified key-value
4.3382 + * mapping.
4.3383 + * @since 1.3
4.3384 + */
4.3385 + public static <K,V> Map<K,V> singletonMap(K key, V value) {
4.3386 + return new SingletonMap<>(key, value);
4.3387 + }
4.3388 +
4.3389 + /**
4.3390 + * @serial include
4.3391 + */
4.3392 + private static class SingletonMap<K,V>
4.3393 + extends AbstractMap<K,V>
4.3394 + implements Serializable {
4.3395 + private static final long serialVersionUID = -6979724477215052911L;
4.3396 +
4.3397 + private final K k;
4.3398 + private final V v;
4.3399 +
4.3400 + SingletonMap(K key, V value) {
4.3401 + k = key;
4.3402 + v = value;
4.3403 + }
4.3404 +
4.3405 + public int size() {return 1;}
4.3406 +
4.3407 + public boolean isEmpty() {return false;}
4.3408 +
4.3409 + public boolean containsKey(Object key) {return eq(key, k);}
4.3410 +
4.3411 + public boolean containsValue(Object value) {return eq(value, v);}
4.3412 +
4.3413 + public V get(Object key) {return (eq(key, k) ? v : null);}
4.3414 +
4.3415 + private transient Set<K> keySet = null;
4.3416 + private transient Set<Map.Entry<K,V>> entrySet = null;
4.3417 + private transient Collection<V> values = null;
4.3418 +
4.3419 + public Set<K> keySet() {
4.3420 + if (keySet==null)
4.3421 + keySet = singleton(k);
4.3422 + return keySet;
4.3423 + }
4.3424 +
4.3425 + public Set<Map.Entry<K,V>> entrySet() {
4.3426 + if (entrySet==null)
4.3427 + entrySet = Collections.<Map.Entry<K,V>>singleton(
4.3428 + new SimpleImmutableEntry<>(k, v));
4.3429 + return entrySet;
4.3430 + }
4.3431 +
4.3432 + public Collection<V> values() {
4.3433 + if (values==null)
4.3434 + values = singleton(v);
4.3435 + return values;
4.3436 + }
4.3437 +
4.3438 + }
4.3439 +
4.3440 + // Miscellaneous
4.3441 +
4.3442 + /**
4.3443 + * Returns an immutable list consisting of <tt>n</tt> copies of the
4.3444 + * specified object. The newly allocated data object is tiny (it contains
4.3445 + * a single reference to the data object). This method is useful in
4.3446 + * combination with the <tt>List.addAll</tt> method to grow lists.
4.3447 + * The returned list is serializable.
4.3448 + *
4.3449 + * @param n the number of elements in the returned list.
4.3450 + * @param o the element to appear repeatedly in the returned list.
4.3451 + * @return an immutable list consisting of <tt>n</tt> copies of the
4.3452 + * specified object.
4.3453 + * @throws IllegalArgumentException if {@code n < 0}
4.3454 + * @see List#addAll(Collection)
4.3455 + * @see List#addAll(int, Collection)
4.3456 + */
4.3457 + public static <T> List<T> nCopies(int n, T o) {
4.3458 + if (n < 0)
4.3459 + throw new IllegalArgumentException("List length = " + n);
4.3460 + return new CopiesList<>(n, o);
4.3461 + }
4.3462 +
4.3463 + /**
4.3464 + * @serial include
4.3465 + */
4.3466 + private static class CopiesList<E>
4.3467 + extends AbstractList<E>
4.3468 + implements RandomAccess, Serializable
4.3469 + {
4.3470 + private static final long serialVersionUID = 2739099268398711800L;
4.3471 +
4.3472 + final int n;
4.3473 + final E element;
4.3474 +
4.3475 + CopiesList(int n, E e) {
4.3476 + assert n >= 0;
4.3477 + this.n = n;
4.3478 + element = e;
4.3479 + }
4.3480 +
4.3481 + public int size() {
4.3482 + return n;
4.3483 + }
4.3484 +
4.3485 + public boolean contains(Object obj) {
4.3486 + return n != 0 && eq(obj, element);
4.3487 + }
4.3488 +
4.3489 + public int indexOf(Object o) {
4.3490 + return contains(o) ? 0 : -1;
4.3491 + }
4.3492 +
4.3493 + public int lastIndexOf(Object o) {
4.3494 + return contains(o) ? n - 1 : -1;
4.3495 + }
4.3496 +
4.3497 + public E get(int index) {
4.3498 + if (index < 0 || index >= n)
4.3499 + throw new IndexOutOfBoundsException("Index: "+index+
4.3500 + ", Size: "+n);
4.3501 + return element;
4.3502 + }
4.3503 +
4.3504 + public Object[] toArray() {
4.3505 + final Object[] a = new Object[n];
4.3506 + if (element != null)
4.3507 + Arrays.fill(a, 0, n, element);
4.3508 + return a;
4.3509 + }
4.3510 +
4.3511 + public <T> T[] toArray(T[] a) {
4.3512 + final int n = this.n;
4.3513 + if (a.length < n) {
4.3514 + a = (T[])java.lang.reflect.Array
4.3515 + .newInstance(a.getClass().getComponentType(), n);
4.3516 + if (element != null)
4.3517 + Arrays.fill(a, 0, n, element);
4.3518 + } else {
4.3519 + Arrays.fill(a, 0, n, element);
4.3520 + if (a.length > n)
4.3521 + a[n] = null;
4.3522 + }
4.3523 + return a;
4.3524 + }
4.3525 +
4.3526 + public List<E> subList(int fromIndex, int toIndex) {
4.3527 + if (fromIndex < 0)
4.3528 + throw new IndexOutOfBoundsException("fromIndex = " + fromIndex);
4.3529 + if (toIndex > n)
4.3530 + throw new IndexOutOfBoundsException("toIndex = " + toIndex);
4.3531 + if (fromIndex > toIndex)
4.3532 + throw new IllegalArgumentException("fromIndex(" + fromIndex +
4.3533 + ") > toIndex(" + toIndex + ")");
4.3534 + return new CopiesList<>(toIndex - fromIndex, element);
4.3535 + }
4.3536 + }
4.3537 +
4.3538 + /**
4.3539 + * Returns a comparator that imposes the reverse of the <em>natural
4.3540 + * ordering</em> on a collection of objects that implement the
4.3541 + * {@code Comparable} interface. (The natural ordering is the ordering
4.3542 + * imposed by the objects' own {@code compareTo} method.) This enables a
4.3543 + * simple idiom for sorting (or maintaining) collections (or arrays) of
4.3544 + * objects that implement the {@code Comparable} interface in
4.3545 + * reverse-natural-order. For example, suppose {@code a} is an array of
4.3546 + * strings. Then: <pre>
4.3547 + * Arrays.sort(a, Collections.reverseOrder());
4.3548 + * </pre> sorts the array in reverse-lexicographic (alphabetical) order.<p>
4.3549 + *
4.3550 + * The returned comparator is serializable.
4.3551 + *
4.3552 + * @return A comparator that imposes the reverse of the <i>natural
4.3553 + * ordering</i> on a collection of objects that implement
4.3554 + * the <tt>Comparable</tt> interface.
4.3555 + * @see Comparable
4.3556 + */
4.3557 + public static <T> Comparator<T> reverseOrder() {
4.3558 + return (Comparator<T>) ReverseComparator.REVERSE_ORDER;
4.3559 + }
4.3560 +
4.3561 + /**
4.3562 + * @serial include
4.3563 + */
4.3564 + private static class ReverseComparator
4.3565 + implements Comparator<Comparable<Object>>, Serializable {
4.3566 +
4.3567 + private static final long serialVersionUID = 7207038068494060240L;
4.3568 +
4.3569 + static final ReverseComparator REVERSE_ORDER
4.3570 + = new ReverseComparator();
4.3571 +
4.3572 + public int compare(Comparable<Object> c1, Comparable<Object> c2) {
4.3573 + return c2.compareTo(c1);
4.3574 + }
4.3575 +
4.3576 + private Object readResolve() { return reverseOrder(); }
4.3577 + }
4.3578 +
4.3579 + /**
4.3580 + * Returns a comparator that imposes the reverse ordering of the specified
4.3581 + * comparator. If the specified comparator is {@code null}, this method is
4.3582 + * equivalent to {@link #reverseOrder()} (in other words, it returns a
4.3583 + * comparator that imposes the reverse of the <em>natural ordering</em> on
4.3584 + * a collection of objects that implement the Comparable interface).
4.3585 + *
4.3586 + * <p>The returned comparator is serializable (assuming the specified
4.3587 + * comparator is also serializable or {@code null}).
4.3588 + *
4.3589 + * @param cmp a comparator who's ordering is to be reversed by the returned
4.3590 + * comparator or {@code null}
4.3591 + * @return A comparator that imposes the reverse ordering of the
4.3592 + * specified comparator.
4.3593 + * @since 1.5
4.3594 + */
4.3595 + public static <T> Comparator<T> reverseOrder(Comparator<T> cmp) {
4.3596 + if (cmp == null)
4.3597 + return reverseOrder();
4.3598 +
4.3599 + if (cmp instanceof ReverseComparator2)
4.3600 + return ((ReverseComparator2<T>)cmp).cmp;
4.3601 +
4.3602 + return new ReverseComparator2<>(cmp);
4.3603 + }
4.3604 +
4.3605 + /**
4.3606 + * @serial include
4.3607 + */
4.3608 + private static class ReverseComparator2<T> implements Comparator<T>,
4.3609 + Serializable
4.3610 + {
4.3611 + private static final long serialVersionUID = 4374092139857L;
4.3612 +
4.3613 + /**
4.3614 + * The comparator specified in the static factory. This will never
4.3615 + * be null, as the static factory returns a ReverseComparator
4.3616 + * instance if its argument is null.
4.3617 + *
4.3618 + * @serial
4.3619 + */
4.3620 + final Comparator<T> cmp;
4.3621 +
4.3622 + ReverseComparator2(Comparator<T> cmp) {
4.3623 + assert cmp != null;
4.3624 + this.cmp = cmp;
4.3625 + }
4.3626 +
4.3627 + public int compare(T t1, T t2) {
4.3628 + return cmp.compare(t2, t1);
4.3629 + }
4.3630 +
4.3631 + public boolean equals(Object o) {
4.3632 + return (o == this) ||
4.3633 + (o instanceof ReverseComparator2 &&
4.3634 + cmp.equals(((ReverseComparator2)o).cmp));
4.3635 + }
4.3636 +
4.3637 + public int hashCode() {
4.3638 + return cmp.hashCode() ^ Integer.MIN_VALUE;
4.3639 + }
4.3640 + }
4.3641 +
4.3642 + /**
4.3643 + * Returns an enumeration over the specified collection. This provides
4.3644 + * interoperability with legacy APIs that require an enumeration
4.3645 + * as input.
4.3646 + *
4.3647 + * @param c the collection for which an enumeration is to be returned.
4.3648 + * @return an enumeration over the specified collection.
4.3649 + * @see Enumeration
4.3650 + */
4.3651 + public static <T> Enumeration<T> enumeration(final Collection<T> c) {
4.3652 + return new Enumeration<T>() {
4.3653 + private final Iterator<T> i = c.iterator();
4.3654 +
4.3655 + public boolean hasMoreElements() {
4.3656 + return i.hasNext();
4.3657 + }
4.3658 +
4.3659 + public T nextElement() {
4.3660 + return i.next();
4.3661 + }
4.3662 + };
4.3663 + }
4.3664 +
4.3665 + /**
4.3666 + * Returns an array list containing the elements returned by the
4.3667 + * specified enumeration in the order they are returned by the
4.3668 + * enumeration. This method provides interoperability between
4.3669 + * legacy APIs that return enumerations and new APIs that require
4.3670 + * collections.
4.3671 + *
4.3672 + * @param e enumeration providing elements for the returned
4.3673 + * array list
4.3674 + * @return an array list containing the elements returned
4.3675 + * by the specified enumeration.
4.3676 + * @since 1.4
4.3677 + * @see Enumeration
4.3678 + * @see ArrayList
4.3679 + */
4.3680 + public static <T> ArrayList<T> list(Enumeration<T> e) {
4.3681 + ArrayList<T> l = new ArrayList<>();
4.3682 + while (e.hasMoreElements())
4.3683 + l.add(e.nextElement());
4.3684 + return l;
4.3685 + }
4.3686 +
4.3687 + /**
4.3688 + * Returns true if the specified arguments are equal, or both null.
4.3689 + */
4.3690 + static boolean eq(Object o1, Object o2) {
4.3691 + return o1==null ? o2==null : o1.equals(o2);
4.3692 + }
4.3693 +
4.3694 + /**
4.3695 + * Returns the number of elements in the specified collection equal to the
4.3696 + * specified object. More formally, returns the number of elements
4.3697 + * <tt>e</tt> in the collection such that
4.3698 + * <tt>(o == null ? e == null : o.equals(e))</tt>.
4.3699 + *
4.3700 + * @param c the collection in which to determine the frequency
4.3701 + * of <tt>o</tt>
4.3702 + * @param o the object whose frequency is to be determined
4.3703 + * @throws NullPointerException if <tt>c</tt> is null
4.3704 + * @since 1.5
4.3705 + */
4.3706 + public static int frequency(Collection<?> c, Object o) {
4.3707 + int result = 0;
4.3708 + if (o == null) {
4.3709 + for (Object e : c)
4.3710 + if (e == null)
4.3711 + result++;
4.3712 + } else {
4.3713 + for (Object e : c)
4.3714 + if (o.equals(e))
4.3715 + result++;
4.3716 + }
4.3717 + return result;
4.3718 + }
4.3719 +
4.3720 + /**
4.3721 + * Returns {@code true} if the two specified collections have no
4.3722 + * elements in common.
4.3723 + *
4.3724 + * <p>Care must be exercised if this method is used on collections that
4.3725 + * do not comply with the general contract for {@code Collection}.
4.3726 + * Implementations may elect to iterate over either collection and test
4.3727 + * for containment in the other collection (or to perform any equivalent
4.3728 + * computation). If either collection uses a nonstandard equality test
4.3729 + * (as does a {@link SortedSet} whose ordering is not <em>compatible with
4.3730 + * equals</em>, or the key set of an {@link IdentityHashMap}), both
4.3731 + * collections must use the same nonstandard equality test, or the
4.3732 + * result of this method is undefined.
4.3733 + *
4.3734 + * <p>Care must also be exercised when using collections that have
4.3735 + * restrictions on the elements that they may contain. Collection
4.3736 + * implementations are allowed to throw exceptions for any operation
4.3737 + * involving elements they deem ineligible. For absolute safety the
4.3738 + * specified collections should contain only elements which are
4.3739 + * eligible elements for both collections.
4.3740 + *
4.3741 + * <p>Note that it is permissible to pass the same collection in both
4.3742 + * parameters, in which case the method will return {@code true} if and
4.3743 + * only if the collection is empty.
4.3744 + *
4.3745 + * @param c1 a collection
4.3746 + * @param c2 a collection
4.3747 + * @return {@code true} if the two specified collections have no
4.3748 + * elements in common.
4.3749 + * @throws NullPointerException if either collection is {@code null}.
4.3750 + * @throws NullPointerException if one collection contains a {@code null}
4.3751 + * element and {@code null} is not an eligible element for the other collection.
4.3752 + * (<a href="Collection.html#optional-restrictions">optional</a>)
4.3753 + * @throws ClassCastException if one collection contains an element that is
4.3754 + * of a type which is ineligible for the other collection.
4.3755 + * (<a href="Collection.html#optional-restrictions">optional</a>)
4.3756 + * @since 1.5
4.3757 + */
4.3758 + public static boolean disjoint(Collection<?> c1, Collection<?> c2) {
4.3759 + // The collection to be used for contains(). Preference is given to
4.3760 + // the collection who's contains() has lower O() complexity.
4.3761 + Collection<?> contains = c2;
4.3762 + // The collection to be iterated. If the collections' contains() impl
4.3763 + // are of different O() complexity, the collection with slower
4.3764 + // contains() will be used for iteration. For collections who's
4.3765 + // contains() are of the same complexity then best performance is
4.3766 + // achieved by iterating the smaller collection.
4.3767 + Collection<?> iterate = c1;
4.3768 +
4.3769 + // Performance optimization cases. The heuristics:
4.3770 + // 1. Generally iterate over c1.
4.3771 + // 2. If c1 is a Set then iterate over c2.
4.3772 + // 3. If either collection is empty then result is always true.
4.3773 + // 4. Iterate over the smaller Collection.
4.3774 + if (c1 instanceof Set) {
4.3775 + // Use c1 for contains as a Set's contains() is expected to perform
4.3776 + // better than O(N/2)
4.3777 + iterate = c2;
4.3778 + contains = c1;
4.3779 + } else if (!(c2 instanceof Set)) {
4.3780 + // Both are mere Collections. Iterate over smaller collection.
4.3781 + // Example: If c1 contains 3 elements and c2 contains 50 elements and
4.3782 + // assuming contains() requires ceiling(N/2) comparisons then
4.3783 + // checking for all c1 elements in c2 would require 75 comparisons
4.3784 + // (3 * ceiling(50/2)) vs. checking all c2 elements in c1 requiring
4.3785 + // 100 comparisons (50 * ceiling(3/2)).
4.3786 + int c1size = c1.size();
4.3787 + int c2size = c2.size();
4.3788 + if (c1size == 0 || c2size == 0) {
4.3789 + // At least one collection is empty. Nothing will match.
4.3790 + return true;
4.3791 + }
4.3792 +
4.3793 + if (c1size > c2size) {
4.3794 + iterate = c2;
4.3795 + contains = c1;
4.3796 + }
4.3797 + }
4.3798 +
4.3799 + for (Object e : iterate) {
4.3800 + if (contains.contains(e)) {
4.3801 + // Found a common element. Collections are not disjoint.
4.3802 + return false;
4.3803 + }
4.3804 + }
4.3805 +
4.3806 + // No common elements were found.
4.3807 + return true;
4.3808 + }
4.3809 +
4.3810 + /**
4.3811 + * Adds all of the specified elements to the specified collection.
4.3812 + * Elements to be added may be specified individually or as an array.
4.3813 + * The behavior of this convenience method is identical to that of
4.3814 + * <tt>c.addAll(Arrays.asList(elements))</tt>, but this method is likely
4.3815 + * to run significantly faster under most implementations.
4.3816 + *
4.3817 + * <p>When elements are specified individually, this method provides a
4.3818 + * convenient way to add a few elements to an existing collection:
4.3819 + * <pre>
4.3820 + * Collections.addAll(flavors, "Peaches 'n Plutonium", "Rocky Racoon");
4.3821 + * </pre>
4.3822 + *
4.3823 + * @param c the collection into which <tt>elements</tt> are to be inserted
4.3824 + * @param elements the elements to insert into <tt>c</tt>
4.3825 + * @return <tt>true</tt> if the collection changed as a result of the call
4.3826 + * @throws UnsupportedOperationException if <tt>c</tt> does not support
4.3827 + * the <tt>add</tt> operation
4.3828 + * @throws NullPointerException if <tt>elements</tt> contains one or more
4.3829 + * null values and <tt>c</tt> does not permit null elements, or
4.3830 + * if <tt>c</tt> or <tt>elements</tt> are <tt>null</tt>
4.3831 + * @throws IllegalArgumentException if some property of a value in
4.3832 + * <tt>elements</tt> prevents it from being added to <tt>c</tt>
4.3833 + * @see Collection#addAll(Collection)
4.3834 + * @since 1.5
4.3835 + */
4.3836 + @SafeVarargs
4.3837 + public static <T> boolean addAll(Collection<? super T> c, T... elements) {
4.3838 + boolean result = false;
4.3839 + for (T element : elements)
4.3840 + result |= c.add(element);
4.3841 + return result;
4.3842 + }
4.3843 +
4.3844 + /**
4.3845 + * Returns a set backed by the specified map. The resulting set displays
4.3846 + * the same ordering, concurrency, and performance characteristics as the
4.3847 + * backing map. In essence, this factory method provides a {@link Set}
4.3848 + * implementation corresponding to any {@link Map} implementation. There
4.3849 + * is no need to use this method on a {@link Map} implementation that
4.3850 + * already has a corresponding {@link Set} implementation (such as {@link
4.3851 + * HashMap} or {@link TreeMap}).
4.3852 + *
4.3853 + * <p>Each method invocation on the set returned by this method results in
4.3854 + * exactly one method invocation on the backing map or its <tt>keySet</tt>
4.3855 + * view, with one exception. The <tt>addAll</tt> method is implemented
4.3856 + * as a sequence of <tt>put</tt> invocations on the backing map.
4.3857 + *
4.3858 + * <p>The specified map must be empty at the time this method is invoked,
4.3859 + * and should not be accessed directly after this method returns. These
4.3860 + * conditions are ensured if the map is created empty, passed directly
4.3861 + * to this method, and no reference to the map is retained, as illustrated
4.3862 + * in the following code fragment:
4.3863 + * <pre>
4.3864 + * Set<Object> weakHashSet = Collections.newSetFromMap(
4.3865 + * new WeakHashMap<Object, Boolean>());
4.3866 + * </pre>
4.3867 + *
4.3868 + * @param map the backing map
4.3869 + * @return the set backed by the map
4.3870 + * @throws IllegalArgumentException if <tt>map</tt> is not empty
4.3871 + * @since 1.6
4.3872 + */
4.3873 + public static <E> Set<E> newSetFromMap(Map<E, Boolean> map) {
4.3874 + return new SetFromMap<>(map);
4.3875 + }
4.3876 +
4.3877 + /**
4.3878 + * @serial include
4.3879 + */
4.3880 + private static class SetFromMap<E> extends AbstractSet<E>
4.3881 + implements Set<E>, Serializable
4.3882 + {
4.3883 + private final Map<E, Boolean> m; // The backing map
4.3884 + private transient Set<E> s; // Its keySet
4.3885 +
4.3886 + SetFromMap(Map<E, Boolean> map) {
4.3887 + if (!map.isEmpty())
4.3888 + throw new IllegalArgumentException("Map is non-empty");
4.3889 + m = map;
4.3890 + s = map.keySet();
4.3891 + }
4.3892 +
4.3893 + public void clear() { m.clear(); }
4.3894 + public int size() { return m.size(); }
4.3895 + public boolean isEmpty() { return m.isEmpty(); }
4.3896 + public boolean contains(Object o) { return m.containsKey(o); }
4.3897 + public boolean remove(Object o) { return m.remove(o) != null; }
4.3898 + public boolean add(E e) { return m.put(e, Boolean.TRUE) == null; }
4.3899 + public Iterator<E> iterator() { return s.iterator(); }
4.3900 + public Object[] toArray() { return s.toArray(); }
4.3901 + public <T> T[] toArray(T[] a) { return s.toArray(a); }
4.3902 + public String toString() { return s.toString(); }
4.3903 + public int hashCode() { return s.hashCode(); }
4.3904 + public boolean equals(Object o) { return o == this || s.equals(o); }
4.3905 + public boolean containsAll(Collection<?> c) {return s.containsAll(c);}
4.3906 + public boolean removeAll(Collection<?> c) {return s.removeAll(c);}
4.3907 + public boolean retainAll(Collection<?> c) {return s.retainAll(c);}
4.3908 + // addAll is the only inherited implementation
4.3909 +
4.3910 + private static final long serialVersionUID = 2454657854757543876L;
4.3911 +
4.3912 + private void readObject(java.io.ObjectInputStream stream)
4.3913 + throws IOException, ClassNotFoundException
4.3914 + {
4.3915 + stream.defaultReadObject();
4.3916 + s = m.keySet();
4.3917 + }
4.3918 + }
4.3919 +
4.3920 + /**
4.3921 + * Returns a view of a {@link Deque} as a Last-in-first-out (Lifo)
4.3922 + * {@link Queue}. Method <tt>add</tt> is mapped to <tt>push</tt>,
4.3923 + * <tt>remove</tt> is mapped to <tt>pop</tt> and so on. This
4.3924 + * view can be useful when you would like to use a method
4.3925 + * requiring a <tt>Queue</tt> but you need Lifo ordering.
4.3926 + *
4.3927 + * <p>Each method invocation on the queue returned by this method
4.3928 + * results in exactly one method invocation on the backing deque, with
4.3929 + * one exception. The {@link Queue#addAll addAll} method is
4.3930 + * implemented as a sequence of {@link Deque#addFirst addFirst}
4.3931 + * invocations on the backing deque.
4.3932 + *
4.3933 + * @param deque the deque
4.3934 + * @return the queue
4.3935 + * @since 1.6
4.3936 + */
4.3937 + public static <T> Queue<T> asLifoQueue(Deque<T> deque) {
4.3938 + return new AsLIFOQueue<>(deque);
4.3939 + }
4.3940 +
4.3941 + /**
4.3942 + * @serial include
4.3943 + */
4.3944 + static class AsLIFOQueue<E> extends AbstractQueue<E>
4.3945 + implements Queue<E>, Serializable {
4.3946 + private static final long serialVersionUID = 1802017725587941708L;
4.3947 + private final Deque<E> q;
4.3948 + AsLIFOQueue(Deque<E> q) { this.q = q; }
4.3949 + public boolean add(E e) { q.addFirst(e); return true; }
4.3950 + public boolean offer(E e) { return q.offerFirst(e); }
4.3951 + public E poll() { return q.pollFirst(); }
4.3952 + public E remove() { return q.removeFirst(); }
4.3953 + public E peek() { return q.peekFirst(); }
4.3954 + public E element() { return q.getFirst(); }
4.3955 + public void clear() { q.clear(); }
4.3956 + public int size() { return q.size(); }
4.3957 + public boolean isEmpty() { return q.isEmpty(); }
4.3958 + public boolean contains(Object o) { return q.contains(o); }
4.3959 + public boolean remove(Object o) { return q.remove(o); }
4.3960 + public Iterator<E> iterator() { return q.iterator(); }
4.3961 + public Object[] toArray() { return q.toArray(); }
4.3962 + public <T> T[] toArray(T[] a) { return q.toArray(a); }
4.3963 + public String toString() { return q.toString(); }
4.3964 + public boolean containsAll(Collection<?> c) {return q.containsAll(c);}
4.3965 + public boolean removeAll(Collection<?> c) {return q.removeAll(c);}
4.3966 + public boolean retainAll(Collection<?> c) {return q.retainAll(c);}
4.3967 + // We use inherited addAll; forwarding addAll would be wrong
4.3968 + }
4.3969 +}
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/emul/compact/src/main/java/java/util/Deque.java Mon Jan 28 13:28:02 2013 +0100
5.3 @@ -0,0 +1,584 @@
5.4 +/*
5.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5.6 + *
5.7 + * This code is free software; you can redistribute it and/or modify it
5.8 + * under the terms of the GNU General Public License version 2 only, as
5.9 + * published by the Free Software Foundation. Oracle designates this
5.10 + * particular file as subject to the "Classpath" exception as provided
5.11 + * by Oracle in the LICENSE file that accompanied this code.
5.12 + *
5.13 + * This code is distributed in the hope that it will be useful, but WITHOUT
5.14 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
5.15 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
5.16 + * version 2 for more details (a copy is included in the LICENSE file that
5.17 + * accompanied this code).
5.18 + *
5.19 + * You should have received a copy of the GNU General Public License version
5.20 + * 2 along with this work; if not, write to the Free Software Foundation,
5.21 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
5.22 + *
5.23 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
5.24 + * or visit www.oracle.com if you need additional information or have any
5.25 + * questions.
5.26 + */
5.27 +
5.28 +/*
5.29 + * This file is available under and governed by the GNU General Public
5.30 + * License version 2 only, as published by the Free Software Foundation.
5.31 + * However, the following notice accompanied the original version of this
5.32 + * file:
5.33 + *
5.34 + * Written by Doug Lea and Josh Bloch with assistance from members of
5.35 + * JCP JSR-166 Expert Group and released to the public domain, as explained
5.36 + * at http://creativecommons.org/publicdomain/zero/1.0/
5.37 + */
5.38 +
5.39 +package java.util;
5.40 +
5.41 +/**
5.42 + * A linear collection that supports element insertion and removal at
5.43 + * both ends. The name <i>deque</i> is short for "double ended queue"
5.44 + * and is usually pronounced "deck". Most <tt>Deque</tt>
5.45 + * implementations place no fixed limits on the number of elements
5.46 + * they may contain, but this interface supports capacity-restricted
5.47 + * deques as well as those with no fixed size limit.
5.48 + *
5.49 + * <p>This interface defines methods to access the elements at both
5.50 + * ends of the deque. Methods are provided to insert, remove, and
5.51 + * examine the element. Each of these methods exists in two forms:
5.52 + * one throws an exception if the operation fails, the other returns a
5.53 + * special value (either <tt>null</tt> or <tt>false</tt>, depending on
5.54 + * the operation). The latter form of the insert operation is
5.55 + * designed specifically for use with capacity-restricted
5.56 + * <tt>Deque</tt> implementations; in most implementations, insert
5.57 + * operations cannot fail.
5.58 + *
5.59 + * <p>The twelve methods described above are summarized in the
5.60 + * following table:
5.61 + *
5.62 + * <p>
5.63 + * <table BORDER CELLPADDING=3 CELLSPACING=1>
5.64 + * <tr>
5.65 + * <td></td>
5.66 + * <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td>
5.67 + * <td ALIGN=CENTER COLSPAN = 2> <b>Last Element (Tail)</b></td>
5.68 + * </tr>
5.69 + * <tr>
5.70 + * <td></td>
5.71 + * <td ALIGN=CENTER><em>Throws exception</em></td>
5.72 + * <td ALIGN=CENTER><em>Special value</em></td>
5.73 + * <td ALIGN=CENTER><em>Throws exception</em></td>
5.74 + * <td ALIGN=CENTER><em>Special value</em></td>
5.75 + * </tr>
5.76 + * <tr>
5.77 + * <td><b>Insert</b></td>
5.78 + * <td>{@link #addFirst addFirst(e)}</td>
5.79 + * <td>{@link #offerFirst offerFirst(e)}</td>
5.80 + * <td>{@link #addLast addLast(e)}</td>
5.81 + * <td>{@link #offerLast offerLast(e)}</td>
5.82 + * </tr>
5.83 + * <tr>
5.84 + * <td><b>Remove</b></td>
5.85 + * <td>{@link #removeFirst removeFirst()}</td>
5.86 + * <td>{@link #pollFirst pollFirst()}</td>
5.87 + * <td>{@link #removeLast removeLast()}</td>
5.88 + * <td>{@link #pollLast pollLast()}</td>
5.89 + * </tr>
5.90 + * <tr>
5.91 + * <td><b>Examine</b></td>
5.92 + * <td>{@link #getFirst getFirst()}</td>
5.93 + * <td>{@link #peekFirst peekFirst()}</td>
5.94 + * <td>{@link #getLast getLast()}</td>
5.95 + * <td>{@link #peekLast peekLast()}</td>
5.96 + * </tr>
5.97 + * </table>
5.98 + *
5.99 + * <p>This interface extends the {@link Queue} interface. When a deque is
5.100 + * used as a queue, FIFO (First-In-First-Out) behavior results. Elements are
5.101 + * added at the end of the deque and removed from the beginning. The methods
5.102 + * inherited from the <tt>Queue</tt> interface are precisely equivalent to
5.103 + * <tt>Deque</tt> methods as indicated in the following table:
5.104 + *
5.105 + * <p>
5.106 + * <table BORDER CELLPADDING=3 CELLSPACING=1>
5.107 + * <tr>
5.108 + * <td ALIGN=CENTER> <b><tt>Queue</tt> Method</b></td>
5.109 + * <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
5.110 + * </tr>
5.111 + * <tr>
5.112 + * <td>{@link java.util.Queue#add add(e)}</td>
5.113 + * <td>{@link #addLast addLast(e)}</td>
5.114 + * </tr>
5.115 + * <tr>
5.116 + * <td>{@link java.util.Queue#offer offer(e)}</td>
5.117 + * <td>{@link #offerLast offerLast(e)}</td>
5.118 + * </tr>
5.119 + * <tr>
5.120 + * <td>{@link java.util.Queue#remove remove()}</td>
5.121 + * <td>{@link #removeFirst removeFirst()}</td>
5.122 + * </tr>
5.123 + * <tr>
5.124 + * <td>{@link java.util.Queue#poll poll()}</td>
5.125 + * <td>{@link #pollFirst pollFirst()}</td>
5.126 + * </tr>
5.127 + * <tr>
5.128 + * <td>{@link java.util.Queue#element element()}</td>
5.129 + * <td>{@link #getFirst getFirst()}</td>
5.130 + * </tr>
5.131 + * <tr>
5.132 + * <td>{@link java.util.Queue#peek peek()}</td>
5.133 + * <td>{@link #peek peekFirst()}</td>
5.134 + * </tr>
5.135 + * </table>
5.136 + *
5.137 + * <p>Deques can also be used as LIFO (Last-In-First-Out) stacks. This
5.138 + * interface should be used in preference to the legacy {@link Stack} class.
5.139 + * When a deque is used as a stack, elements are pushed and popped from the
5.140 + * beginning of the deque. Stack methods are precisely equivalent to
5.141 + * <tt>Deque</tt> methods as indicated in the table below:
5.142 + *
5.143 + * <p>
5.144 + * <table BORDER CELLPADDING=3 CELLSPACING=1>
5.145 + * <tr>
5.146 + * <td ALIGN=CENTER> <b>Stack Method</b></td>
5.147 + * <td ALIGN=CENTER> <b>Equivalent <tt>Deque</tt> Method</b></td>
5.148 + * </tr>
5.149 + * <tr>
5.150 + * <td>{@link #push push(e)}</td>
5.151 + * <td>{@link #addFirst addFirst(e)}</td>
5.152 + * </tr>
5.153 + * <tr>
5.154 + * <td>{@link #pop pop()}</td>
5.155 + * <td>{@link #removeFirst removeFirst()}</td>
5.156 + * </tr>
5.157 + * <tr>
5.158 + * <td>{@link #peek peek()}</td>
5.159 + * <td>{@link #peekFirst peekFirst()}</td>
5.160 + * </tr>
5.161 + * </table>
5.162 + *
5.163 + * <p>Note that the {@link #peek peek} method works equally well when
5.164 + * a deque is used as a queue or a stack; in either case, elements are
5.165 + * drawn from the beginning of the deque.
5.166 + *
5.167 + * <p>This interface provides two methods to remove interior
5.168 + * elements, {@link #removeFirstOccurrence removeFirstOccurrence} and
5.169 + * {@link #removeLastOccurrence removeLastOccurrence}.
5.170 + *
5.171 + * <p>Unlike the {@link List} interface, this interface does not
5.172 + * provide support for indexed access to elements.
5.173 + *
5.174 + * <p>While <tt>Deque</tt> implementations are not strictly required
5.175 + * to prohibit the insertion of null elements, they are strongly
5.176 + * encouraged to do so. Users of any <tt>Deque</tt> implementations
5.177 + * that do allow null elements are strongly encouraged <i>not</i> to
5.178 + * take advantage of the ability to insert nulls. This is so because
5.179 + * <tt>null</tt> is used as a special return value by various methods
5.180 + * to indicated that the deque is empty.
5.181 + *
5.182 + * <p><tt>Deque</tt> implementations generally do not define
5.183 + * element-based versions of the <tt>equals</tt> and <tt>hashCode</tt>
5.184 + * methods, but instead inherit the identity-based versions from class
5.185 + * <tt>Object</tt>.
5.186 + *
5.187 + * <p>This interface is a member of the <a
5.188 + * href="{@docRoot}/../technotes/guides/collections/index.html"> Java Collections
5.189 + * Framework</a>.
5.190 + *
5.191 + * @author Doug Lea
5.192 + * @author Josh Bloch
5.193 + * @since 1.6
5.194 + * @param <E> the type of elements held in this collection
5.195 + */
5.196 +
5.197 +public interface Deque<E> extends Queue<E> {
5.198 + /**
5.199 + * Inserts the specified element at the front of this deque if it is
5.200 + * possible to do so immediately without violating capacity restrictions.
5.201 + * When using a capacity-restricted deque, it is generally preferable to
5.202 + * use method {@link #offerFirst}.
5.203 + *
5.204 + * @param e the element to add
5.205 + * @throws IllegalStateException if the element cannot be added at this
5.206 + * time due to capacity restrictions
5.207 + * @throws ClassCastException if the class of the specified element
5.208 + * prevents it from being added to this deque
5.209 + * @throws NullPointerException if the specified element is null and this
5.210 + * deque does not permit null elements
5.211 + * @throws IllegalArgumentException if some property of the specified
5.212 + * element prevents it from being added to this deque
5.213 + */
5.214 + void addFirst(E e);
5.215 +
5.216 + /**
5.217 + * Inserts the specified element at the end of this deque if it is
5.218 + * possible to do so immediately without violating capacity restrictions.
5.219 + * When using a capacity-restricted deque, it is generally preferable to
5.220 + * use method {@link #offerLast}.
5.221 + *
5.222 + * <p>This method is equivalent to {@link #add}.
5.223 + *
5.224 + * @param e the element to add
5.225 + * @throws IllegalStateException if the element cannot be added at this
5.226 + * time due to capacity restrictions
5.227 + * @throws ClassCastException if the class of the specified element
5.228 + * prevents it from being added to this deque
5.229 + * @throws NullPointerException if the specified element is null and this
5.230 + * deque does not permit null elements
5.231 + * @throws IllegalArgumentException if some property of the specified
5.232 + * element prevents it from being added to this deque
5.233 + */
5.234 + void addLast(E e);
5.235 +
5.236 + /**
5.237 + * Inserts the specified element at the front of this deque unless it would
5.238 + * violate capacity restrictions. When using a capacity-restricted deque,
5.239 + * this method is generally preferable to the {@link #addFirst} method,
5.240 + * which can fail to insert an element only by throwing an exception.
5.241 + *
5.242 + * @param e the element to add
5.243 + * @return <tt>true</tt> if the element was added to this deque, else
5.244 + * <tt>false</tt>
5.245 + * @throws ClassCastException if the class of the specified element
5.246 + * prevents it from being added to this deque
5.247 + * @throws NullPointerException if the specified element is null and this
5.248 + * deque does not permit null elements
5.249 + * @throws IllegalArgumentException if some property of the specified
5.250 + * element prevents it from being added to this deque
5.251 + */
5.252 + boolean offerFirst(E e);
5.253 +
5.254 + /**
5.255 + * Inserts the specified element at the end of this deque unless it would
5.256 + * violate capacity restrictions. When using a capacity-restricted deque,
5.257 + * this method is generally preferable to the {@link #addLast} method,
5.258 + * which can fail to insert an element only by throwing an exception.
5.259 + *
5.260 + * @param e the element to add
5.261 + * @return <tt>true</tt> if the element was added to this deque, else
5.262 + * <tt>false</tt>
5.263 + * @throws ClassCastException if the class of the specified element
5.264 + * prevents it from being added to this deque
5.265 + * @throws NullPointerException if the specified element is null and this
5.266 + * deque does not permit null elements
5.267 + * @throws IllegalArgumentException if some property of the specified
5.268 + * element prevents it from being added to this deque
5.269 + */
5.270 + boolean offerLast(E e);
5.271 +
5.272 + /**
5.273 + * Retrieves and removes the first element of this deque. This method
5.274 + * differs from {@link #pollFirst pollFirst} only in that it throws an
5.275 + * exception if this deque is empty.
5.276 + *
5.277 + * @return the head of this deque
5.278 + * @throws NoSuchElementException if this deque is empty
5.279 + */
5.280 + E removeFirst();
5.281 +
5.282 + /**
5.283 + * Retrieves and removes the last element of this deque. This method
5.284 + * differs from {@link #pollLast pollLast} only in that it throws an
5.285 + * exception if this deque is empty.
5.286 + *
5.287 + * @return the tail of this deque
5.288 + * @throws NoSuchElementException if this deque is empty
5.289 + */
5.290 + E removeLast();
5.291 +
5.292 + /**
5.293 + * Retrieves and removes the first element of this deque,
5.294 + * or returns <tt>null</tt> if this deque is empty.
5.295 + *
5.296 + * @return the head of this deque, or <tt>null</tt> if this deque is empty
5.297 + */
5.298 + E pollFirst();
5.299 +
5.300 + /**
5.301 + * Retrieves and removes the last element of this deque,
5.302 + * or returns <tt>null</tt> if this deque is empty.
5.303 + *
5.304 + * @return the tail of this deque, or <tt>null</tt> if this deque is empty
5.305 + */
5.306 + E pollLast();
5.307 +
5.308 + /**
5.309 + * Retrieves, but does not remove, the first element of this deque.
5.310 + *
5.311 + * This method differs from {@link #peekFirst peekFirst} only in that it
5.312 + * throws an exception if this deque is empty.
5.313 + *
5.314 + * @return the head of this deque
5.315 + * @throws NoSuchElementException if this deque is empty
5.316 + */
5.317 + E getFirst();
5.318 +
5.319 + /**
5.320 + * Retrieves, but does not remove, the last element of this deque.
5.321 + * This method differs from {@link #peekLast peekLast} only in that it
5.322 + * throws an exception if this deque is empty.
5.323 + *
5.324 + * @return the tail of this deque
5.325 + * @throws NoSuchElementException if this deque is empty
5.326 + */
5.327 + E getLast();
5.328 +
5.329 + /**
5.330 + * Retrieves, but does not remove, the first element of this deque,
5.331 + * or returns <tt>null</tt> if this deque is empty.
5.332 + *
5.333 + * @return the head of this deque, or <tt>null</tt> if this deque is empty
5.334 + */
5.335 + E peekFirst();
5.336 +
5.337 + /**
5.338 + * Retrieves, but does not remove, the last element of this deque,
5.339 + * or returns <tt>null</tt> if this deque is empty.
5.340 + *
5.341 + * @return the tail of this deque, or <tt>null</tt> if this deque is empty
5.342 + */
5.343 + E peekLast();
5.344 +
5.345 + /**
5.346 + * Removes the first occurrence of the specified element from this deque.
5.347 + * If the deque does not contain the element, it is unchanged.
5.348 + * More formally, removes the first element <tt>e</tt> such that
5.349 + * <tt>(o==null ? e==null : o.equals(e))</tt>
5.350 + * (if such an element exists).
5.351 + * Returns <tt>true</tt> if this deque contained the specified element
5.352 + * (or equivalently, if this deque changed as a result of the call).
5.353 + *
5.354 + * @param o element to be removed from this deque, if present
5.355 + * @return <tt>true</tt> if an element was removed as a result of this call
5.356 + * @throws ClassCastException if the class of the specified element
5.357 + * is incompatible with this deque
5.358 + * (<a href="Collection.html#optional-restrictions">optional</a>)
5.359 + * @throws NullPointerException if the specified element is null and this
5.360 + * deque does not permit null elements
5.361 + * (<a href="Collection.html#optional-restrictions">optional</a>)
5.362 + */
5.363 + boolean removeFirstOccurrence(Object o);
5.364 +
5.365 + /**
5.366 + * Removes the last occurrence of the specified element from this deque.
5.367 + * If the deque does not contain the element, it is unchanged.
5.368 + * More formally, removes the last element <tt>e</tt> such that
5.369 + * <tt>(o==null ? e==null : o.equals(e))</tt>
5.370 + * (if such an element exists).
5.371 + * Returns <tt>true</tt> if this deque contained the specified element
5.372 + * (or equivalently, if this deque changed as a result of the call).
5.373 + *
5.374 + * @param o element to be removed from this deque, if present
5.375 + * @return <tt>true</tt> if an element was removed as a result of this call
5.376 + * @throws ClassCastException if the class of the specified element
5.377 + * is incompatible with this deque
5.378 + * (<a href="Collection.html#optional-restrictions">optional</a>)
5.379 + * @throws NullPointerException if the specified element is null and this
5.380 + * deque does not permit null elements
5.381 + * (<a href="Collection.html#optional-restrictions">optional</a>)
5.382 + */
5.383 + boolean removeLastOccurrence(Object o);
5.384 +
5.385 + // *** Queue methods ***
5.386 +
5.387 + /**
5.388 + * Inserts the specified element into the queue represented by this deque
5.389 + * (in other words, at the tail of this deque) if it is possible to do so
5.390 + * immediately without violating capacity restrictions, returning
5.391 + * <tt>true</tt> upon success and throwing an
5.392 + * <tt>IllegalStateException</tt> if no space is currently available.
5.393 + * When using a capacity-restricted deque, it is generally preferable to
5.394 + * use {@link #offer(Object) offer}.
5.395 + *
5.396 + * <p>This method is equivalent to {@link #addLast}.
5.397 + *
5.398 + * @param e the element to add
5.399 + * @return <tt>true</tt> (as specified by {@link Collection#add})
5.400 + * @throws IllegalStateException if the element cannot be added at this
5.401 + * time due to capacity restrictions
5.402 + * @throws ClassCastException if the class of the specified element
5.403 + * prevents it from being added to this deque
5.404 + * @throws NullPointerException if the specified element is null and this
5.405 + * deque does not permit null elements
5.406 + * @throws IllegalArgumentException if some property of the specified
5.407 + * element prevents it from being added to this deque
5.408 + */
5.409 + boolean add(E e);
5.410 +
5.411 + /**
5.412 + * Inserts the specified element into the queue represented by this deque
5.413 + * (in other words, at the tail of this deque) if it is possible to do so
5.414 + * immediately without violating capacity restrictions, returning
5.415 + * <tt>true</tt> upon success and <tt>false</tt> if no space is currently
5.416 + * available. When using a capacity-restricted deque, this method is
5.417 + * generally preferable to the {@link #add} method, which can fail to
5.418 + * insert an element only by throwing an exception.
5.419 + *
5.420 + * <p>This method is equivalent to {@link #offerLast}.
5.421 + *
5.422 + * @param e the element to add
5.423 + * @return <tt>true</tt> if the element was added to this deque, else
5.424 + * <tt>false</tt>
5.425 + * @throws ClassCastException if the class of the specified element
5.426 + * prevents it from being added to this deque
5.427 + * @throws NullPointerException if the specified element is null and this
5.428 + * deque does not permit null elements
5.429 + * @throws IllegalArgumentException if some property of the specified
5.430 + * element prevents it from being added to this deque
5.431 + */
5.432 + boolean offer(E e);
5.433 +
5.434 + /**
5.435 + * Retrieves and removes the head of the queue represented by this deque
5.436 + * (in other words, the first element of this deque).
5.437 + * This method differs from {@link #poll poll} only in that it throws an
5.438 + * exception if this deque is empty.
5.439 + *
5.440 + * <p>This method is equivalent to {@link #removeFirst()}.
5.441 + *
5.442 + * @return the head of the queue represented by this deque
5.443 + * @throws NoSuchElementException if this deque is empty
5.444 + */
5.445 + E remove();
5.446 +
5.447 + /**
5.448 + * Retrieves and removes the head of the queue represented by this deque
5.449 + * (in other words, the first element of this deque), or returns
5.450 + * <tt>null</tt> if this deque is empty.
5.451 + *
5.452 + * <p>This method is equivalent to {@link #pollFirst()}.
5.453 + *
5.454 + * @return the first element of this deque, or <tt>null</tt> if
5.455 + * this deque is empty
5.456 + */
5.457 + E poll();
5.458 +
5.459 + /**
5.460 + * Retrieves, but does not remove, the head of the queue represented by
5.461 + * this deque (in other words, the first element of this deque).
5.462 + * This method differs from {@link #peek peek} only in that it throws an
5.463 + * exception if this deque is empty.
5.464 + *
5.465 + * <p>This method is equivalent to {@link #getFirst()}.
5.466 + *
5.467 + * @return the head of the queue represented by this deque
5.468 + * @throws NoSuchElementException if this deque is empty
5.469 + */
5.470 + E element();
5.471 +
5.472 + /**
5.473 + * Retrieves, but does not remove, the head of the queue represented by
5.474 + * this deque (in other words, the first element of this deque), or
5.475 + * returns <tt>null</tt> if this deque is empty.
5.476 + *
5.477 + * <p>This method is equivalent to {@link #peekFirst()}.
5.478 + *
5.479 + * @return the head of the queue represented by this deque, or
5.480 + * <tt>null</tt> if this deque is empty
5.481 + */
5.482 + E peek();
5.483 +
5.484 +
5.485 + // *** Stack methods ***
5.486 +
5.487 + /**
5.488 + * Pushes an element onto the stack represented by this deque (in other
5.489 + * words, at the head of this deque) if it is possible to do so
5.490 + * immediately without violating capacity restrictions, returning
5.491 + * <tt>true</tt> upon success and throwing an
5.492 + * <tt>IllegalStateException</tt> if no space is currently available.
5.493 + *
5.494 + * <p>This method is equivalent to {@link #addFirst}.
5.495 + *
5.496 + * @param e the element to push
5.497 + * @throws IllegalStateException if the element cannot be added at this
5.498 + * time due to capacity restrictions
5.499 + * @throws ClassCastException if the class of the specified element
5.500 + * prevents it from being added to this deque
5.501 + * @throws NullPointerException if the specified element is null and this
5.502 + * deque does not permit null elements
5.503 + * @throws IllegalArgumentException if some property of the specified
5.504 + * element prevents it from being added to this deque
5.505 + */
5.506 + void push(E e);
5.507 +
5.508 + /**
5.509 + * Pops an element from the stack represented by this deque. In other
5.510 + * words, removes and returns the first element of this deque.
5.511 + *
5.512 + * <p>This method is equivalent to {@link #removeFirst()}.
5.513 + *
5.514 + * @return the element at the front of this deque (which is the top
5.515 + * of the stack represented by this deque)
5.516 + * @throws NoSuchElementException if this deque is empty
5.517 + */
5.518 + E pop();
5.519 +
5.520 +
5.521 + // *** Collection methods ***
5.522 +
5.523 + /**
5.524 + * Removes the first occurrence of the specified element from this deque.
5.525 + * If the deque does not contain the element, it is unchanged.
5.526 + * More formally, removes the first element <tt>e</tt> such that
5.527 + * <tt>(o==null ? e==null : o.equals(e))</tt>
5.528 + * (if such an element exists).
5.529 + * Returns <tt>true</tt> if this deque contained the specified element
5.530 + * (or equivalently, if this deque changed as a result of the call).
5.531 + *
5.532 + * <p>This method is equivalent to {@link #removeFirstOccurrence}.
5.533 + *
5.534 + * @param o element to be removed from this deque, if present
5.535 + * @return <tt>true</tt> if an element was removed as a result of this call
5.536 + * @throws ClassCastException if the class of the specified element
5.537 + * is incompatible with this deque
5.538 + * (<a href="Collection.html#optional-restrictions">optional</a>)
5.539 + * @throws NullPointerException if the specified element is null and this
5.540 + * deque does not permit null elements
5.541 + * (<a href="Collection.html#optional-restrictions">optional</a>)
5.542 + */
5.543 + boolean remove(Object o);
5.544 +
5.545 + /**
5.546 + * Returns <tt>true</tt> if this deque contains the specified element.
5.547 + * More formally, returns <tt>true</tt> if and only if this deque contains
5.548 + * at least one element <tt>e</tt> such that
5.549 + * <tt>(o==null ? e==null : o.equals(e))</tt>.
5.550 + *
5.551 + * @param o element whose presence in this deque is to be tested
5.552 + * @return <tt>true</tt> if this deque contains the specified element
5.553 + * @throws ClassCastException if the type of the specified element
5.554 + * is incompatible with this deque
5.555 + * (<a href="Collection.html#optional-restrictions">optional</a>)
5.556 + * @throws NullPointerException if the specified element is null and this
5.557 + * deque does not permit null elements
5.558 + * (<a href="Collection.html#optional-restrictions">optional</a>)
5.559 + */
5.560 + boolean contains(Object o);
5.561 +
5.562 + /**
5.563 + * Returns the number of elements in this deque.
5.564 + *
5.565 + * @return the number of elements in this deque
5.566 + */
5.567 + public int size();
5.568 +
5.569 + /**
5.570 + * Returns an iterator over the elements in this deque in proper sequence.
5.571 + * The elements will be returned in order from first (head) to last (tail).
5.572 + *
5.573 + * @return an iterator over the elements in this deque in proper sequence
5.574 + */
5.575 + Iterator<E> iterator();
5.576 +
5.577 + /**
5.578 + * Returns an iterator over the elements in this deque in reverse
5.579 + * sequential order. The elements will be returned in order from
5.580 + * last (tail) to first (head).
5.581 + *
5.582 + * @return an iterator over the elements in this deque in reverse
5.583 + * sequence
5.584 + */
5.585 + Iterator<E> descendingIterator();
5.586 +
5.587 +}
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2 +++ b/emul/compact/src/main/java/java/util/Dictionary.java Mon Jan 28 13:28:02 2013 +0100
6.3 @@ -0,0 +1,155 @@
6.4 +/*
6.5 + * Copyright (c) 1995, 2004, Oracle and/or its affiliates. All rights reserved.
6.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
6.7 + *
6.8 + * This code is free software; you can redistribute it and/or modify it
6.9 + * under the terms of the GNU General Public License version 2 only, as
6.10 + * published by the Free Software Foundation. Oracle designates this
6.11 + * particular file as subject to the "Classpath" exception as provided
6.12 + * by Oracle in the LICENSE file that accompanied this code.
6.13 + *
6.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
6.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
6.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
6.17 + * version 2 for more details (a copy is included in the LICENSE file that
6.18 + * accompanied this code).
6.19 + *
6.20 + * You should have received a copy of the GNU General Public License version
6.21 + * 2 along with this work; if not, write to the Free Software Foundation,
6.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
6.23 + *
6.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
6.25 + * or visit www.oracle.com if you need additional information or have any
6.26 + * questions.
6.27 + */
6.28 +
6.29 +package java.util;
6.30 +
6.31 +/**
6.32 + * The <code>Dictionary</code> class is the abstract parent of any
6.33 + * class, such as <code>Hashtable</code>, which maps keys to values.
6.34 + * Every key and every value is an object. In any one <tt>Dictionary</tt>
6.35 + * object, every key is associated with at most one value. Given a
6.36 + * <tt>Dictionary</tt> and a key, the associated element can be looked up.
6.37 + * Any non-<code>null</code> object can be used as a key and as a value.
6.38 + * <p>
6.39 + * As a rule, the <code>equals</code> method should be used by
6.40 + * implementations of this class to decide if two keys are the same.
6.41 + * <p>
6.42 + * <strong>NOTE: This class is obsolete. New implementations should
6.43 + * implement the Map interface, rather than extending this class.</strong>
6.44 + *
6.45 + * @author unascribed
6.46 + * @see java.util.Map
6.47 + * @see java.lang.Object#equals(java.lang.Object)
6.48 + * @see java.lang.Object#hashCode()
6.49 + * @see java.util.Hashtable
6.50 + * @since JDK1.0
6.51 + */
6.52 +public abstract
6.53 +class Dictionary<K,V> {
6.54 + /**
6.55 + * Sole constructor. (For invocation by subclass constructors, typically
6.56 + * implicit.)
6.57 + */
6.58 + public Dictionary() {
6.59 + }
6.60 +
6.61 + /**
6.62 + * Returns the number of entries (distinct keys) in this dictionary.
6.63 + *
6.64 + * @return the number of keys in this dictionary.
6.65 + */
6.66 + abstract public int size();
6.67 +
6.68 + /**
6.69 + * Tests if this dictionary maps no keys to value. The general contract
6.70 + * for the <tt>isEmpty</tt> method is that the result is true if and only
6.71 + * if this dictionary contains no entries.
6.72 + *
6.73 + * @return <code>true</code> if this dictionary maps no keys to values;
6.74 + * <code>false</code> otherwise.
6.75 + */
6.76 + abstract public boolean isEmpty();
6.77 +
6.78 + /**
6.79 + * Returns an enumeration of the keys in this dictionary. The general
6.80 + * contract for the keys method is that an <tt>Enumeration</tt> object
6.81 + * is returned that will generate all the keys for which this dictionary
6.82 + * contains entries.
6.83 + *
6.84 + * @return an enumeration of the keys in this dictionary.
6.85 + * @see java.util.Dictionary#elements()
6.86 + * @see java.util.Enumeration
6.87 + */
6.88 + abstract public Enumeration<K> keys();
6.89 +
6.90 + /**
6.91 + * Returns an enumeration of the values in this dictionary. The general
6.92 + * contract for the <tt>elements</tt> method is that an
6.93 + * <tt>Enumeration</tt> is returned that will generate all the elements
6.94 + * contained in entries in this dictionary.
6.95 + *
6.96 + * @return an enumeration of the values in this dictionary.
6.97 + * @see java.util.Dictionary#keys()
6.98 + * @see java.util.Enumeration
6.99 + */
6.100 + abstract public Enumeration<V> elements();
6.101 +
6.102 + /**
6.103 + * Returns the value to which the key is mapped in this dictionary.
6.104 + * The general contract for the <tt>isEmpty</tt> method is that if this
6.105 + * dictionary contains an entry for the specified key, the associated
6.106 + * value is returned; otherwise, <tt>null</tt> is returned.
6.107 + *
6.108 + * @return the value to which the key is mapped in this dictionary;
6.109 + * @param key a key in this dictionary.
6.110 + * <code>null</code> if the key is not mapped to any value in
6.111 + * this dictionary.
6.112 + * @exception NullPointerException if the <tt>key</tt> is <tt>null</tt>.
6.113 + * @see java.util.Dictionary#put(java.lang.Object, java.lang.Object)
6.114 + */
6.115 + abstract public V get(Object key);
6.116 +
6.117 + /**
6.118 + * Maps the specified <code>key</code> to the specified
6.119 + * <code>value</code> in this dictionary. Neither the key nor the
6.120 + * value can be <code>null</code>.
6.121 + * <p>
6.122 + * If this dictionary already contains an entry for the specified
6.123 + * <tt>key</tt>, the value already in this dictionary for that
6.124 + * <tt>key</tt> is returned, after modifying the entry to contain the
6.125 + * new element. <p>If this dictionary does not already have an entry
6.126 + * for the specified <tt>key</tt>, an entry is created for the
6.127 + * specified <tt>key</tt> and <tt>value</tt>, and <tt>null</tt> is
6.128 + * returned.
6.129 + * <p>
6.130 + * The <code>value</code> can be retrieved by calling the
6.131 + * <code>get</code> method with a <code>key</code> that is equal to
6.132 + * the original <code>key</code>.
6.133 + *
6.134 + * @param key the hashtable key.
6.135 + * @param value the value.
6.136 + * @return the previous value to which the <code>key</code> was mapped
6.137 + * in this dictionary, or <code>null</code> if the key did not
6.138 + * have a previous mapping.
6.139 + * @exception NullPointerException if the <code>key</code> or
6.140 + * <code>value</code> is <code>null</code>.
6.141 + * @see java.lang.Object#equals(java.lang.Object)
6.142 + * @see java.util.Dictionary#get(java.lang.Object)
6.143 + */
6.144 + abstract public V put(K key, V value);
6.145 +
6.146 + /**
6.147 + * Removes the <code>key</code> (and its corresponding
6.148 + * <code>value</code>) from this dictionary. This method does nothing
6.149 + * if the <code>key</code> is not in this dictionary.
6.150 + *
6.151 + * @param key the key that needs to be removed.
6.152 + * @return the value to which the <code>key</code> had been mapped in this
6.153 + * dictionary, or <code>null</code> if the key did not have a
6.154 + * mapping.
6.155 + * @exception NullPointerException if <tt>key</tt> is <tt>null</tt>.
6.156 + */
6.157 + abstract public V remove(Object key);
6.158 +}
7.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
7.2 +++ b/emul/compact/src/main/java/java/util/EmptyStackException.java Mon Jan 28 13:28:02 2013 +0100
7.3 @@ -0,0 +1,46 @@
7.4 +/*
7.5 + * Copyright (c) 1994, 2008, Oracle and/or its affiliates. All rights reserved.
7.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
7.7 + *
7.8 + * This code is free software; you can redistribute it and/or modify it
7.9 + * under the terms of the GNU General Public License version 2 only, as
7.10 + * published by the Free Software Foundation. Oracle designates this
7.11 + * particular file as subject to the "Classpath" exception as provided
7.12 + * by Oracle in the LICENSE file that accompanied this code.
7.13 + *
7.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
7.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
7.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
7.17 + * version 2 for more details (a copy is included in the LICENSE file that
7.18 + * accompanied this code).
7.19 + *
7.20 + * You should have received a copy of the GNU General Public License version
7.21 + * 2 along with this work; if not, write to the Free Software Foundation,
7.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
7.23 + *
7.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
7.25 + * or visit www.oracle.com if you need additional information or have any
7.26 + * questions.
7.27 + */
7.28 +
7.29 +package java.util;
7.30 +
7.31 +/**
7.32 + * Thrown by methods in the <code>Stack</code> class to indicate
7.33 + * that the stack is empty.
7.34 + *
7.35 + * @author Jonathan Payne
7.36 + * @see java.util.Stack
7.37 + * @since JDK1.0
7.38 + */
7.39 +public
7.40 +class EmptyStackException extends RuntimeException {
7.41 + private static final long serialVersionUID = 5084686378493302095L;
7.42 +
7.43 + /**
7.44 + * Constructs a new <code>EmptyStackException</code> with <tt>null</tt>
7.45 + * as its error message string.
7.46 + */
7.47 + public EmptyStackException() {
7.48 + }
7.49 +}
8.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2 +++ b/emul/compact/src/main/java/java/util/EventListener.java Mon Jan 28 13:28:02 2013 +0100
8.3 @@ -0,0 +1,33 @@
8.4 +/*
8.5 + * Copyright (c) 1996, 1999, Oracle and/or its affiliates. All rights reserved.
8.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
8.7 + *
8.8 + * This code is free software; you can redistribute it and/or modify it
8.9 + * under the terms of the GNU General Public License version 2 only, as
8.10 + * published by the Free Software Foundation. Oracle designates this
8.11 + * particular file as subject to the "Classpath" exception as provided
8.12 + * by Oracle in the LICENSE file that accompanied this code.
8.13 + *
8.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
8.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
8.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
8.17 + * version 2 for more details (a copy is included in the LICENSE file that
8.18 + * accompanied this code).
8.19 + *
8.20 + * You should have received a copy of the GNU General Public License version
8.21 + * 2 along with this work; if not, write to the Free Software Foundation,
8.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
8.23 + *
8.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
8.25 + * or visit www.oracle.com if you need additional information or have any
8.26 + * questions.
8.27 + */
8.28 +
8.29 +package java.util;
8.30 +
8.31 +/**
8.32 + * A tagging interface that all event listener interfaces must extend.
8.33 + * @since JDK1.1
8.34 + */
8.35 +public interface EventListener {
8.36 +}
9.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
9.2 +++ b/emul/compact/src/main/java/java/util/EventObject.java Mon Jan 28 13:28:02 2013 +0100
9.3 @@ -0,0 +1,78 @@
9.4 +/*
9.5 + * Copyright (c) 1996, 2003, Oracle and/or its affiliates. All rights reserved.
9.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
9.7 + *
9.8 + * This code is free software; you can redistribute it and/or modify it
9.9 + * under the terms of the GNU General Public License version 2 only, as
9.10 + * published by the Free Software Foundation. Oracle designates this
9.11 + * particular file as subject to the "Classpath" exception as provided
9.12 + * by Oracle in the LICENSE file that accompanied this code.
9.13 + *
9.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
9.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
9.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
9.17 + * version 2 for more details (a copy is included in the LICENSE file that
9.18 + * accompanied this code).
9.19 + *
9.20 + * You should have received a copy of the GNU General Public License version
9.21 + * 2 along with this work; if not, write to the Free Software Foundation,
9.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
9.23 + *
9.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
9.25 + * or visit www.oracle.com if you need additional information or have any
9.26 + * questions.
9.27 + */
9.28 +
9.29 +package java.util;
9.30 +
9.31 +/**
9.32 + * <p>
9.33 + * The root class from which all event state objects shall be derived.
9.34 + * <p>
9.35 + * All Events are constructed with a reference to the object, the "source",
9.36 + * that is logically deemed to be the object upon which the Event in question
9.37 + * initially occurred upon.
9.38 + *
9.39 + * @since JDK1.1
9.40 + */
9.41 +
9.42 +public class EventObject implements java.io.Serializable {
9.43 +
9.44 + private static final long serialVersionUID = 5516075349620653480L;
9.45 +
9.46 + /**
9.47 + * The object on which the Event initially occurred.
9.48 + */
9.49 + protected transient Object source;
9.50 +
9.51 + /**
9.52 + * Constructs a prototypical Event.
9.53 + *
9.54 + * @param source The object on which the Event initially occurred.
9.55 + * @exception IllegalArgumentException if source is null.
9.56 + */
9.57 + public EventObject(Object source) {
9.58 + if (source == null)
9.59 + throw new IllegalArgumentException("null source");
9.60 +
9.61 + this.source = source;
9.62 + }
9.63 +
9.64 + /**
9.65 + * The object on which the Event initially occurred.
9.66 + *
9.67 + * @return The object on which the Event initially occurred.
9.68 + */
9.69 + public Object getSource() {
9.70 + return source;
9.71 + }
9.72 +
9.73 + /**
9.74 + * Returns a String representation of this EventObject.
9.75 + *
9.76 + * @return A a String representation of this EventObject.
9.77 + */
9.78 + public String toString() {
9.79 + return getClass().getName() + "[source=" + source + "]";
9.80 + }
9.81 +}
10.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
10.2 +++ b/emul/compact/src/main/java/java/util/Hashtable.java Mon Jan 28 13:28:02 2013 +0100
10.3 @@ -0,0 +1,1115 @@
10.4 +/*
10.5 + * Copyright (c) 1994, 2011, Oracle and/or its affiliates. All rights reserved.
10.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
10.7 + *
10.8 + * This code is free software; you can redistribute it and/or modify it
10.9 + * under the terms of the GNU General Public License version 2 only, as
10.10 + * published by the Free Software Foundation. Oracle designates this
10.11 + * particular file as subject to the "Classpath" exception as provided
10.12 + * by Oracle in the LICENSE file that accompanied this code.
10.13 + *
10.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
10.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
10.17 + * version 2 for more details (a copy is included in the LICENSE file that
10.18 + * accompanied this code).
10.19 + *
10.20 + * You should have received a copy of the GNU General Public License version
10.21 + * 2 along with this work; if not, write to the Free Software Foundation,
10.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
10.23 + *
10.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
10.25 + * or visit www.oracle.com if you need additional information or have any
10.26 + * questions.
10.27 + */
10.28 +
10.29 +package java.util;
10.30 +import java.io.*;
10.31 +
10.32 +/**
10.33 + * This class implements a hash table, which maps keys to values. Any
10.34 + * non-<code>null</code> object can be used as a key or as a value. <p>
10.35 + *
10.36 + * To successfully store and retrieve objects from a hashtable, the
10.37 + * objects used as keys must implement the <code>hashCode</code>
10.38 + * method and the <code>equals</code> method. <p>
10.39 + *
10.40 + * An instance of <code>Hashtable</code> has two parameters that affect its
10.41 + * performance: <i>initial capacity</i> and <i>load factor</i>. The
10.42 + * <i>capacity</i> is the number of <i>buckets</i> in the hash table, and the
10.43 + * <i>initial capacity</i> is simply the capacity at the time the hash table
10.44 + * is created. Note that the hash table is <i>open</i>: in the case of a "hash
10.45 + * collision", a single bucket stores multiple entries, which must be searched
10.46 + * sequentially. The <i>load factor</i> is a measure of how full the hash
10.47 + * table is allowed to get before its capacity is automatically increased.
10.48 + * The initial capacity and load factor parameters are merely hints to
10.49 + * the implementation. The exact details as to when and whether the rehash
10.50 + * method is invoked are implementation-dependent.<p>
10.51 + *
10.52 + * Generally, the default load factor (.75) offers a good tradeoff between
10.53 + * time and space costs. Higher values decrease the space overhead but
10.54 + * increase the time cost to look up an entry (which is reflected in most
10.55 + * <tt>Hashtable</tt> operations, including <tt>get</tt> and <tt>put</tt>).<p>
10.56 + *
10.57 + * The initial capacity controls a tradeoff between wasted space and the
10.58 + * need for <code>rehash</code> operations, which are time-consuming.
10.59 + * No <code>rehash</code> operations will <i>ever</i> occur if the initial
10.60 + * capacity is greater than the maximum number of entries the
10.61 + * <tt>Hashtable</tt> will contain divided by its load factor. However,
10.62 + * setting the initial capacity too high can waste space.<p>
10.63 + *
10.64 + * If many entries are to be made into a <code>Hashtable</code>,
10.65 + * creating it with a sufficiently large capacity may allow the
10.66 + * entries to be inserted more efficiently than letting it perform
10.67 + * automatic rehashing as needed to grow the table. <p>
10.68 + *
10.69 + * This example creates a hashtable of numbers. It uses the names of
10.70 + * the numbers as keys:
10.71 + * <pre> {@code
10.72 + * Hashtable<String, Integer> numbers
10.73 + * = new Hashtable<String, Integer>();
10.74 + * numbers.put("one", 1);
10.75 + * numbers.put("two", 2);
10.76 + * numbers.put("three", 3);}</pre>
10.77 + *
10.78 + * <p>To retrieve a number, use the following code:
10.79 + * <pre> {@code
10.80 + * Integer n = numbers.get("two");
10.81 + * if (n != null) {
10.82 + * System.out.println("two = " + n);
10.83 + * }}</pre>
10.84 + *
10.85 + * <p>The iterators returned by the <tt>iterator</tt> method of the collections
10.86 + * returned by all of this class's "collection view methods" are
10.87 + * <em>fail-fast</em>: if the Hashtable is structurally modified at any time
10.88 + * after the iterator is created, in any way except through the iterator's own
10.89 + * <tt>remove</tt> method, the iterator will throw a {@link
10.90 + * ConcurrentModificationException}. Thus, in the face of concurrent
10.91 + * modification, the iterator fails quickly and cleanly, rather than risking
10.92 + * arbitrary, non-deterministic behavior at an undetermined time in the future.
10.93 + * The Enumerations returned by Hashtable's keys and elements methods are
10.94 + * <em>not</em> fail-fast.
10.95 + *
10.96 + * <p>Note that the fail-fast behavior of an iterator cannot be guaranteed
10.97 + * as it is, generally speaking, impossible to make any hard guarantees in the
10.98 + * presence of unsynchronized concurrent modification. Fail-fast iterators
10.99 + * throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
10.100 + * Therefore, it would be wrong to write a program that depended on this
10.101 + * exception for its correctness: <i>the fail-fast behavior of iterators
10.102 + * should be used only to detect bugs.</i>
10.103 + *
10.104 + * <p>As of the Java 2 platform v1.2, this class was retrofitted to
10.105 + * implement the {@link Map} interface, making it a member of the
10.106 + * <a href="{@docRoot}/../technotes/guides/collections/index.html">
10.107 + *
10.108 + * Java Collections Framework</a>. Unlike the new collection
10.109 + * implementations, {@code Hashtable} is synchronized. If a
10.110 + * thread-safe implementation is not needed, it is recommended to use
10.111 + * {@link HashMap} in place of {@code Hashtable}. If a thread-safe
10.112 + * highly-concurrent implementation is desired, then it is recommended
10.113 + * to use {@link java.util.concurrent.ConcurrentHashMap} in place of
10.114 + * {@code Hashtable}.
10.115 + *
10.116 + * @author Arthur van Hoff
10.117 + * @author Josh Bloch
10.118 + * @author Neal Gafter
10.119 + * @see Object#equals(java.lang.Object)
10.120 + * @see Object#hashCode()
10.121 + * @see Hashtable#rehash()
10.122 + * @see Collection
10.123 + * @see Map
10.124 + * @see HashMap
10.125 + * @see TreeMap
10.126 + * @since JDK1.0
10.127 + */
10.128 +public class Hashtable<K,V>
10.129 + extends Dictionary<K,V>
10.130 + implements Map<K,V>, Cloneable, java.io.Serializable {
10.131 +
10.132 + /**
10.133 + * The hash table data.
10.134 + */
10.135 + private transient Entry[] table;
10.136 +
10.137 + /**
10.138 + * The total number of entries in the hash table.
10.139 + */
10.140 + private transient int count;
10.141 +
10.142 + /**
10.143 + * The table is rehashed when its size exceeds this threshold. (The
10.144 + * value of this field is (int)(capacity * loadFactor).)
10.145 + *
10.146 + * @serial
10.147 + */
10.148 + private int threshold;
10.149 +
10.150 + /**
10.151 + * The load factor for the hashtable.
10.152 + *
10.153 + * @serial
10.154 + */
10.155 + private float loadFactor;
10.156 +
10.157 + /**
10.158 + * The number of times this Hashtable has been structurally modified
10.159 + * Structural modifications are those that change the number of entries in
10.160 + * the Hashtable or otherwise modify its internal structure (e.g.,
10.161 + * rehash). This field is used to make iterators on Collection-views of
10.162 + * the Hashtable fail-fast. (See ConcurrentModificationException).
10.163 + */
10.164 + private transient int modCount = 0;
10.165 +
10.166 + /** use serialVersionUID from JDK 1.0.2 for interoperability */
10.167 + private static final long serialVersionUID = 1421746759512286392L;
10.168 +
10.169 + /**
10.170 + * Constructs a new, empty hashtable with the specified initial
10.171 + * capacity and the specified load factor.
10.172 + *
10.173 + * @param initialCapacity the initial capacity of the hashtable.
10.174 + * @param loadFactor the load factor of the hashtable.
10.175 + * @exception IllegalArgumentException if the initial capacity is less
10.176 + * than zero, or if the load factor is nonpositive.
10.177 + */
10.178 + public Hashtable(int initialCapacity, float loadFactor) {
10.179 + if (initialCapacity < 0)
10.180 + throw new IllegalArgumentException("Illegal Capacity: "+
10.181 + initialCapacity);
10.182 + if (loadFactor <= 0 || Float.isNaN(loadFactor))
10.183 + throw new IllegalArgumentException("Illegal Load: "+loadFactor);
10.184 +
10.185 + if (initialCapacity==0)
10.186 + initialCapacity = 1;
10.187 + this.loadFactor = loadFactor;
10.188 + table = new Entry[initialCapacity];
10.189 + threshold = (int)(initialCapacity * loadFactor);
10.190 + }
10.191 +
10.192 + /**
10.193 + * Constructs a new, empty hashtable with the specified initial capacity
10.194 + * and default load factor (0.75).
10.195 + *
10.196 + * @param initialCapacity the initial capacity of the hashtable.
10.197 + * @exception IllegalArgumentException if the initial capacity is less
10.198 + * than zero.
10.199 + */
10.200 + public Hashtable(int initialCapacity) {
10.201 + this(initialCapacity, 0.75f);
10.202 + }
10.203 +
10.204 + /**
10.205 + * Constructs a new, empty hashtable with a default initial capacity (11)
10.206 + * and load factor (0.75).
10.207 + */
10.208 + public Hashtable() {
10.209 + this(11, 0.75f);
10.210 + }
10.211 +
10.212 + /**
10.213 + * Constructs a new hashtable with the same mappings as the given
10.214 + * Map. The hashtable is created with an initial capacity sufficient to
10.215 + * hold the mappings in the given Map and a default load factor (0.75).
10.216 + *
10.217 + * @param t the map whose mappings are to be placed in this map.
10.218 + * @throws NullPointerException if the specified map is null.
10.219 + * @since 1.2
10.220 + */
10.221 + public Hashtable(Map<? extends K, ? extends V> t) {
10.222 + this(Math.max(2*t.size(), 11), 0.75f);
10.223 + putAll(t);
10.224 + }
10.225 +
10.226 + /**
10.227 + * Returns the number of keys in this hashtable.
10.228 + *
10.229 + * @return the number of keys in this hashtable.
10.230 + */
10.231 + public synchronized int size() {
10.232 + return count;
10.233 + }
10.234 +
10.235 + /**
10.236 + * Tests if this hashtable maps no keys to values.
10.237 + *
10.238 + * @return <code>true</code> if this hashtable maps no keys to values;
10.239 + * <code>false</code> otherwise.
10.240 + */
10.241 + public synchronized boolean isEmpty() {
10.242 + return count == 0;
10.243 + }
10.244 +
10.245 + /**
10.246 + * Returns an enumeration of the keys in this hashtable.
10.247 + *
10.248 + * @return an enumeration of the keys in this hashtable.
10.249 + * @see Enumeration
10.250 + * @see #elements()
10.251 + * @see #keySet()
10.252 + * @see Map
10.253 + */
10.254 + public synchronized Enumeration<K> keys() {
10.255 + return this.<K>getEnumeration(KEYS);
10.256 + }
10.257 +
10.258 + /**
10.259 + * Returns an enumeration of the values in this hashtable.
10.260 + * Use the Enumeration methods on the returned object to fetch the elements
10.261 + * sequentially.
10.262 + *
10.263 + * @return an enumeration of the values in this hashtable.
10.264 + * @see java.util.Enumeration
10.265 + * @see #keys()
10.266 + * @see #values()
10.267 + * @see Map
10.268 + */
10.269 + public synchronized Enumeration<V> elements() {
10.270 + return this.<V>getEnumeration(VALUES);
10.271 + }
10.272 +
10.273 + /**
10.274 + * Tests if some key maps into the specified value in this hashtable.
10.275 + * This operation is more expensive than the {@link #containsKey
10.276 + * containsKey} method.
10.277 + *
10.278 + * <p>Note that this method is identical in functionality to
10.279 + * {@link #containsValue containsValue}, (which is part of the
10.280 + * {@link Map} interface in the collections framework).
10.281 + *
10.282 + * @param value a value to search for
10.283 + * @return <code>true</code> if and only if some key maps to the
10.284 + * <code>value</code> argument in this hashtable as
10.285 + * determined by the <tt>equals</tt> method;
10.286 + * <code>false</code> otherwise.
10.287 + * @exception NullPointerException if the value is <code>null</code>
10.288 + */
10.289 + public synchronized boolean contains(Object value) {
10.290 + if (value == null) {
10.291 + throw new NullPointerException();
10.292 + }
10.293 +
10.294 + Entry tab[] = table;
10.295 + for (int i = tab.length ; i-- > 0 ;) {
10.296 + for (Entry<K,V> e = tab[i] ; e != null ; e = e.next) {
10.297 + if (e.value.equals(value)) {
10.298 + return true;
10.299 + }
10.300 + }
10.301 + }
10.302 + return false;
10.303 + }
10.304 +
10.305 + /**
10.306 + * Returns true if this hashtable maps one or more keys to this value.
10.307 + *
10.308 + * <p>Note that this method is identical in functionality to {@link
10.309 + * #contains contains} (which predates the {@link Map} interface).
10.310 + *
10.311 + * @param value value whose presence in this hashtable is to be tested
10.312 + * @return <tt>true</tt> if this map maps one or more keys to the
10.313 + * specified value
10.314 + * @throws NullPointerException if the value is <code>null</code>
10.315 + * @since 1.2
10.316 + */
10.317 + public boolean containsValue(Object value) {
10.318 + return contains(value);
10.319 + }
10.320 +
10.321 + /**
10.322 + * Tests if the specified object is a key in this hashtable.
10.323 + *
10.324 + * @param key possible key
10.325 + * @return <code>true</code> if and only if the specified object
10.326 + * is a key in this hashtable, as determined by the
10.327 + * <tt>equals</tt> method; <code>false</code> otherwise.
10.328 + * @throws NullPointerException if the key is <code>null</code>
10.329 + * @see #contains(Object)
10.330 + */
10.331 + public synchronized boolean containsKey(Object key) {
10.332 + Entry tab[] = table;
10.333 + int hash = key.hashCode();
10.334 + int index = (hash & 0x7FFFFFFF) % tab.length;
10.335 + for (Entry<K,V> e = tab[index] ; e != null ; e = e.next) {
10.336 + if ((e.hash == hash) && e.key.equals(key)) {
10.337 + return true;
10.338 + }
10.339 + }
10.340 + return false;
10.341 + }
10.342 +
10.343 + /**
10.344 + * Returns the value to which the specified key is mapped,
10.345 + * or {@code null} if this map contains no mapping for the key.
10.346 + *
10.347 + * <p>More formally, if this map contains a mapping from a key
10.348 + * {@code k} to a value {@code v} such that {@code (key.equals(k))},
10.349 + * then this method returns {@code v}; otherwise it returns
10.350 + * {@code null}. (There can be at most one such mapping.)
10.351 + *
10.352 + * @param key the key whose associated value is to be returned
10.353 + * @return the value to which the specified key is mapped, or
10.354 + * {@code null} if this map contains no mapping for the key
10.355 + * @throws NullPointerException if the specified key is null
10.356 + * @see #put(Object, Object)
10.357 + */
10.358 + public synchronized V get(Object key) {
10.359 + Entry tab[] = table;
10.360 + int hash = key.hashCode();
10.361 + int index = (hash & 0x7FFFFFFF) % tab.length;
10.362 + for (Entry<K,V> e = tab[index] ; e != null ; e = e.next) {
10.363 + if ((e.hash == hash) && e.key.equals(key)) {
10.364 + return e.value;
10.365 + }
10.366 + }
10.367 + return null;
10.368 + }
10.369 +
10.370 + /**
10.371 + * The maximum size of array to allocate.
10.372 + * Some VMs reserve some header words in an array.
10.373 + * Attempts to allocate larger arrays may result in
10.374 + * OutOfMemoryError: Requested array size exceeds VM limit
10.375 + */
10.376 + private static final int MAX_ARRAY_SIZE = Integer.MAX_VALUE - 8;
10.377 +
10.378 + /**
10.379 + * Increases the capacity of and internally reorganizes this
10.380 + * hashtable, in order to accommodate and access its entries more
10.381 + * efficiently. This method is called automatically when the
10.382 + * number of keys in the hashtable exceeds this hashtable's capacity
10.383 + * and load factor.
10.384 + */
10.385 + protected void rehash() {
10.386 + int oldCapacity = table.length;
10.387 + Entry[] oldMap = table;
10.388 +
10.389 + // overflow-conscious code
10.390 + int newCapacity = (oldCapacity << 1) + 1;
10.391 + if (newCapacity - MAX_ARRAY_SIZE > 0) {
10.392 + if (oldCapacity == MAX_ARRAY_SIZE)
10.393 + // Keep running with MAX_ARRAY_SIZE buckets
10.394 + return;
10.395 + newCapacity = MAX_ARRAY_SIZE;
10.396 + }
10.397 + Entry[] newMap = new Entry[newCapacity];
10.398 +
10.399 + modCount++;
10.400 + threshold = (int)(newCapacity * loadFactor);
10.401 + table = newMap;
10.402 +
10.403 + for (int i = oldCapacity ; i-- > 0 ;) {
10.404 + for (Entry<K,V> old = oldMap[i] ; old != null ; ) {
10.405 + Entry<K,V> e = old;
10.406 + old = old.next;
10.407 +
10.408 + int index = (e.hash & 0x7FFFFFFF) % newCapacity;
10.409 + e.next = newMap[index];
10.410 + newMap[index] = e;
10.411 + }
10.412 + }
10.413 + }
10.414 +
10.415 + /**
10.416 + * Maps the specified <code>key</code> to the specified
10.417 + * <code>value</code> in this hashtable. Neither the key nor the
10.418 + * value can be <code>null</code>. <p>
10.419 + *
10.420 + * The value can be retrieved by calling the <code>get</code> method
10.421 + * with a key that is equal to the original key.
10.422 + *
10.423 + * @param key the hashtable key
10.424 + * @param value the value
10.425 + * @return the previous value of the specified key in this hashtable,
10.426 + * or <code>null</code> if it did not have one
10.427 + * @exception NullPointerException if the key or value is
10.428 + * <code>null</code>
10.429 + * @see Object#equals(Object)
10.430 + * @see #get(Object)
10.431 + */
10.432 + public synchronized V put(K key, V value) {
10.433 + // Make sure the value is not null
10.434 + if (value == null) {
10.435 + throw new NullPointerException();
10.436 + }
10.437 +
10.438 + // Makes sure the key is not already in the hashtable.
10.439 + Entry tab[] = table;
10.440 + int hash = key.hashCode();
10.441 + int index = (hash & 0x7FFFFFFF) % tab.length;
10.442 + for (Entry<K,V> e = tab[index] ; e != null ; e = e.next) {
10.443 + if ((e.hash == hash) && e.key.equals(key)) {
10.444 + V old = e.value;
10.445 + e.value = value;
10.446 + return old;
10.447 + }
10.448 + }
10.449 +
10.450 + modCount++;
10.451 + if (count >= threshold) {
10.452 + // Rehash the table if the threshold is exceeded
10.453 + rehash();
10.454 +
10.455 + tab = table;
10.456 + index = (hash & 0x7FFFFFFF) % tab.length;
10.457 + }
10.458 +
10.459 + // Creates the new entry.
10.460 + Entry<K,V> e = tab[index];
10.461 + tab[index] = new Entry<>(hash, key, value, e);
10.462 + count++;
10.463 + return null;
10.464 + }
10.465 +
10.466 + /**
10.467 + * Removes the key (and its corresponding value) from this
10.468 + * hashtable. This method does nothing if the key is not in the hashtable.
10.469 + *
10.470 + * @param key the key that needs to be removed
10.471 + * @return the value to which the key had been mapped in this hashtable,
10.472 + * or <code>null</code> if the key did not have a mapping
10.473 + * @throws NullPointerException if the key is <code>null</code>
10.474 + */
10.475 + public synchronized V remove(Object key) {
10.476 + Entry tab[] = table;
10.477 + int hash = key.hashCode();
10.478 + int index = (hash & 0x7FFFFFFF) % tab.length;
10.479 + for (Entry<K,V> e = tab[index], prev = null ; e != null ; prev = e, e = e.next) {
10.480 + if ((e.hash == hash) && e.key.equals(key)) {
10.481 + modCount++;
10.482 + if (prev != null) {
10.483 + prev.next = e.next;
10.484 + } else {
10.485 + tab[index] = e.next;
10.486 + }
10.487 + count--;
10.488 + V oldValue = e.value;
10.489 + e.value = null;
10.490 + return oldValue;
10.491 + }
10.492 + }
10.493 + return null;
10.494 + }
10.495 +
10.496 + /**
10.497 + * Copies all of the mappings from the specified map to this hashtable.
10.498 + * These mappings will replace any mappings that this hashtable had for any
10.499 + * of the keys currently in the specified map.
10.500 + *
10.501 + * @param t mappings to be stored in this map
10.502 + * @throws NullPointerException if the specified map is null
10.503 + * @since 1.2
10.504 + */
10.505 + public synchronized void putAll(Map<? extends K, ? extends V> t) {
10.506 + for (Map.Entry<? extends K, ? extends V> e : t.entrySet())
10.507 + put(e.getKey(), e.getValue());
10.508 + }
10.509 +
10.510 + /**
10.511 + * Clears this hashtable so that it contains no keys.
10.512 + */
10.513 + public synchronized void clear() {
10.514 + Entry tab[] = table;
10.515 + modCount++;
10.516 + for (int index = tab.length; --index >= 0; )
10.517 + tab[index] = null;
10.518 + count = 0;
10.519 + }
10.520 +
10.521 + /**
10.522 + * Creates a shallow copy of this hashtable. All the structure of the
10.523 + * hashtable itself is copied, but the keys and values are not cloned.
10.524 + * This is a relatively expensive operation.
10.525 + *
10.526 + * @return a clone of the hashtable
10.527 + */
10.528 + public synchronized Object clone() {
10.529 + try {
10.530 + Hashtable<K,V> t = (Hashtable<K,V>) super.clone();
10.531 + t.table = new Entry[table.length];
10.532 + for (int i = table.length ; i-- > 0 ; ) {
10.533 + t.table[i] = (table[i] != null)
10.534 + ? (Entry<K,V>) table[i].clone() : null;
10.535 + }
10.536 + t.keySet = null;
10.537 + t.entrySet = null;
10.538 + t.values = null;
10.539 + t.modCount = 0;
10.540 + return t;
10.541 + } catch (CloneNotSupportedException e) {
10.542 + // this shouldn't happen, since we are Cloneable
10.543 + throw new InternalError();
10.544 + }
10.545 + }
10.546 +
10.547 + /**
10.548 + * Returns a string representation of this <tt>Hashtable</tt> object
10.549 + * in the form of a set of entries, enclosed in braces and separated
10.550 + * by the ASCII characters "<tt>, </tt>" (comma and space). Each
10.551 + * entry is rendered as the key, an equals sign <tt>=</tt>, and the
10.552 + * associated element, where the <tt>toString</tt> method is used to
10.553 + * convert the key and element to strings.
10.554 + *
10.555 + * @return a string representation of this hashtable
10.556 + */
10.557 + public synchronized String toString() {
10.558 + int max = size() - 1;
10.559 + if (max == -1)
10.560 + return "{}";
10.561 +
10.562 + StringBuilder sb = new StringBuilder();
10.563 + Iterator<Map.Entry<K,V>> it = entrySet().iterator();
10.564 +
10.565 + sb.append('{');
10.566 + for (int i = 0; ; i++) {
10.567 + Map.Entry<K,V> e = it.next();
10.568 + K key = e.getKey();
10.569 + V value = e.getValue();
10.570 + sb.append(key == this ? "(this Map)" : key.toString());
10.571 + sb.append('=');
10.572 + sb.append(value == this ? "(this Map)" : value.toString());
10.573 +
10.574 + if (i == max)
10.575 + return sb.append('}').toString();
10.576 + sb.append(", ");
10.577 + }
10.578 + }
10.579 +
10.580 +
10.581 + private <T> Enumeration<T> getEnumeration(int type) {
10.582 + if (count == 0) {
10.583 + return Collections.emptyEnumeration();
10.584 + } else {
10.585 + return new Enumerator<>(type, false);
10.586 + }
10.587 + }
10.588 +
10.589 + private <T> Iterator<T> getIterator(int type) {
10.590 + if (count == 0) {
10.591 + return Collections.emptyIterator();
10.592 + } else {
10.593 + return new Enumerator<>(type, true);
10.594 + }
10.595 + }
10.596 +
10.597 + // Views
10.598 +
10.599 + /**
10.600 + * Each of these fields are initialized to contain an instance of the
10.601 + * appropriate view the first time this view is requested. The views are
10.602 + * stateless, so there's no reason to create more than one of each.
10.603 + */
10.604 + private transient volatile Set<K> keySet = null;
10.605 + private transient volatile Set<Map.Entry<K,V>> entrySet = null;
10.606 + private transient volatile Collection<V> values = null;
10.607 +
10.608 + /**
10.609 + * Returns a {@link Set} view of the keys contained in this map.
10.610 + * The set is backed by the map, so changes to the map are
10.611 + * reflected in the set, and vice-versa. If the map is modified
10.612 + * while an iteration over the set is in progress (except through
10.613 + * the iterator's own <tt>remove</tt> operation), the results of
10.614 + * the iteration are undefined. The set supports element removal,
10.615 + * which removes the corresponding mapping from the map, via the
10.616 + * <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
10.617 + * <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt>
10.618 + * operations. It does not support the <tt>add</tt> or <tt>addAll</tt>
10.619 + * operations.
10.620 + *
10.621 + * @since 1.2
10.622 + */
10.623 + public Set<K> keySet() {
10.624 + if (keySet == null)
10.625 + keySet = Collections.synchronizedSet(new KeySet(), this);
10.626 + return keySet;
10.627 + }
10.628 +
10.629 + private class KeySet extends AbstractSet<K> {
10.630 + public Iterator<K> iterator() {
10.631 + return getIterator(KEYS);
10.632 + }
10.633 + public int size() {
10.634 + return count;
10.635 + }
10.636 + public boolean contains(Object o) {
10.637 + return containsKey(o);
10.638 + }
10.639 + public boolean remove(Object o) {
10.640 + return Hashtable.this.remove(o) != null;
10.641 + }
10.642 + public void clear() {
10.643 + Hashtable.this.clear();
10.644 + }
10.645 + }
10.646 +
10.647 + /**
10.648 + * Returns a {@link Set} view of the mappings contained in this map.
10.649 + * The set is backed by the map, so changes to the map are
10.650 + * reflected in the set, and vice-versa. If the map is modified
10.651 + * while an iteration over the set is in progress (except through
10.652 + * the iterator's own <tt>remove</tt> operation, or through the
10.653 + * <tt>setValue</tt> operation on a map entry returned by the
10.654 + * iterator) the results of the iteration are undefined. The set
10.655 + * supports element removal, which removes the corresponding
10.656 + * mapping from the map, via the <tt>Iterator.remove</tt>,
10.657 + * <tt>Set.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt> and
10.658 + * <tt>clear</tt> operations. It does not support the
10.659 + * <tt>add</tt> or <tt>addAll</tt> operations.
10.660 + *
10.661 + * @since 1.2
10.662 + */
10.663 + public Set<Map.Entry<K,V>> entrySet() {
10.664 + if (entrySet==null)
10.665 + entrySet = Collections.synchronizedSet(new EntrySet(), this);
10.666 + return entrySet;
10.667 + }
10.668 +
10.669 + private class EntrySet extends AbstractSet<Map.Entry<K,V>> {
10.670 + public Iterator<Map.Entry<K,V>> iterator() {
10.671 + return getIterator(ENTRIES);
10.672 + }
10.673 +
10.674 + public boolean add(Map.Entry<K,V> o) {
10.675 + return super.add(o);
10.676 + }
10.677 +
10.678 + public boolean contains(Object o) {
10.679 + if (!(o instanceof Map.Entry))
10.680 + return false;
10.681 + Map.Entry entry = (Map.Entry)o;
10.682 + Object key = entry.getKey();
10.683 + Entry[] tab = table;
10.684 + int hash = key.hashCode();
10.685 + int index = (hash & 0x7FFFFFFF) % tab.length;
10.686 +
10.687 + for (Entry e = tab[index]; e != null; e = e.next)
10.688 + if (e.hash==hash && e.equals(entry))
10.689 + return true;
10.690 + return false;
10.691 + }
10.692 +
10.693 + public boolean remove(Object o) {
10.694 + if (!(o instanceof Map.Entry))
10.695 + return false;
10.696 + Map.Entry<K,V> entry = (Map.Entry<K,V>) o;
10.697 + K key = entry.getKey();
10.698 + Entry[] tab = table;
10.699 + int hash = key.hashCode();
10.700 + int index = (hash & 0x7FFFFFFF) % tab.length;
10.701 +
10.702 + for (Entry<K,V> e = tab[index], prev = null; e != null;
10.703 + prev = e, e = e.next) {
10.704 + if (e.hash==hash && e.equals(entry)) {
10.705 + modCount++;
10.706 + if (prev != null)
10.707 + prev.next = e.next;
10.708 + else
10.709 + tab[index] = e.next;
10.710 +
10.711 + count--;
10.712 + e.value = null;
10.713 + return true;
10.714 + }
10.715 + }
10.716 + return false;
10.717 + }
10.718 +
10.719 + public int size() {
10.720 + return count;
10.721 + }
10.722 +
10.723 + public void clear() {
10.724 + Hashtable.this.clear();
10.725 + }
10.726 + }
10.727 +
10.728 + /**
10.729 + * Returns a {@link Collection} view of the values contained in this map.
10.730 + * The collection is backed by the map, so changes to the map are
10.731 + * reflected in the collection, and vice-versa. If the map is
10.732 + * modified while an iteration over the collection is in progress
10.733 + * (except through the iterator's own <tt>remove</tt> operation),
10.734 + * the results of the iteration are undefined. The collection
10.735 + * supports element removal, which removes the corresponding
10.736 + * mapping from the map, via the <tt>Iterator.remove</tt>,
10.737 + * <tt>Collection.remove</tt>, <tt>removeAll</tt>,
10.738 + * <tt>retainAll</tt> and <tt>clear</tt> operations. It does not
10.739 + * support the <tt>add</tt> or <tt>addAll</tt> operations.
10.740 + *
10.741 + * @since 1.2
10.742 + */
10.743 + public Collection<V> values() {
10.744 + if (values==null)
10.745 + values = Collections.synchronizedCollection(new ValueCollection(),
10.746 + this);
10.747 + return values;
10.748 + }
10.749 +
10.750 + private class ValueCollection extends AbstractCollection<V> {
10.751 + public Iterator<V> iterator() {
10.752 + return getIterator(VALUES);
10.753 + }
10.754 + public int size() {
10.755 + return count;
10.756 + }
10.757 + public boolean contains(Object o) {
10.758 + return containsValue(o);
10.759 + }
10.760 + public void clear() {
10.761 + Hashtable.this.clear();
10.762 + }
10.763 + }
10.764 +
10.765 + // Comparison and hashing
10.766 +
10.767 + /**
10.768 + * Compares the specified Object with this Map for equality,
10.769 + * as per the definition in the Map interface.
10.770 + *
10.771 + * @param o object to be compared for equality with this hashtable
10.772 + * @return true if the specified Object is equal to this Map
10.773 + * @see Map#equals(Object)
10.774 + * @since 1.2
10.775 + */
10.776 + public synchronized boolean equals(Object o) {
10.777 + if (o == this)
10.778 + return true;
10.779 +
10.780 + if (!(o instanceof Map))
10.781 + return false;
10.782 + Map<K,V> t = (Map<K,V>) o;
10.783 + if (t.size() != size())
10.784 + return false;
10.785 +
10.786 + try {
10.787 + Iterator<Map.Entry<K,V>> i = entrySet().iterator();
10.788 + while (i.hasNext()) {
10.789 + Map.Entry<K,V> e = i.next();
10.790 + K key = e.getKey();
10.791 + V value = e.getValue();
10.792 + if (value == null) {
10.793 + if (!(t.get(key)==null && t.containsKey(key)))
10.794 + return false;
10.795 + } else {
10.796 + if (!value.equals(t.get(key)))
10.797 + return false;
10.798 + }
10.799 + }
10.800 + } catch (ClassCastException unused) {
10.801 + return false;
10.802 + } catch (NullPointerException unused) {
10.803 + return false;
10.804 + }
10.805 +
10.806 + return true;
10.807 + }
10.808 +
10.809 + /**
10.810 + * Returns the hash code value for this Map as per the definition in the
10.811 + * Map interface.
10.812 + *
10.813 + * @see Map#hashCode()
10.814 + * @since 1.2
10.815 + */
10.816 + public synchronized int hashCode() {
10.817 + /*
10.818 + * This code detects the recursion caused by computing the hash code
10.819 + * of a self-referential hash table and prevents the stack overflow
10.820 + * that would otherwise result. This allows certain 1.1-era
10.821 + * applets with self-referential hash tables to work. This code
10.822 + * abuses the loadFactor field to do double-duty as a hashCode
10.823 + * in progress flag, so as not to worsen the space performance.
10.824 + * A negative load factor indicates that hash code computation is
10.825 + * in progress.
10.826 + */
10.827 + int h = 0;
10.828 + if (count == 0 || loadFactor < 0)
10.829 + return h; // Returns zero
10.830 +
10.831 + loadFactor = -loadFactor; // Mark hashCode computation in progress
10.832 + Entry[] tab = table;
10.833 + for (int i = 0; i < tab.length; i++)
10.834 + for (Entry e = tab[i]; e != null; e = e.next)
10.835 + h += e.key.hashCode() ^ e.value.hashCode();
10.836 + loadFactor = -loadFactor; // Mark hashCode computation complete
10.837 +
10.838 + return h;
10.839 + }
10.840 +
10.841 + /**
10.842 + * Save the state of the Hashtable to a stream (i.e., serialize it).
10.843 + *
10.844 + * @serialData The <i>capacity</i> of the Hashtable (the length of the
10.845 + * bucket array) is emitted (int), followed by the
10.846 + * <i>size</i> of the Hashtable (the number of key-value
10.847 + * mappings), followed by the key (Object) and value (Object)
10.848 + * for each key-value mapping represented by the Hashtable
10.849 + * The key-value mappings are emitted in no particular order.
10.850 + */
10.851 + private void writeObject(java.io.ObjectOutputStream s)
10.852 + throws IOException {
10.853 + Entry<Object, Object> entryStack = null;
10.854 +
10.855 + synchronized (this) {
10.856 + // Write out the length, threshold, loadfactor
10.857 + s.defaultWriteObject();
10.858 +
10.859 + // Write out length, count of elements
10.860 + s.writeInt(table.length);
10.861 + s.writeInt(count);
10.862 +
10.863 + // Stack copies of the entries in the table
10.864 + for (int index = 0; index < table.length; index++) {
10.865 + Entry entry = table[index];
10.866 +
10.867 + while (entry != null) {
10.868 + entryStack =
10.869 + new Entry<>(0, entry.key, entry.value, entryStack);
10.870 + entry = entry.next;
10.871 + }
10.872 + }
10.873 + }
10.874 +
10.875 + // Write out the key/value objects from the stacked entries
10.876 + while (entryStack != null) {
10.877 + s.writeObject(entryStack.key);
10.878 + s.writeObject(entryStack.value);
10.879 + entryStack = entryStack.next;
10.880 + }
10.881 + }
10.882 +
10.883 + /**
10.884 + * Reconstitute the Hashtable from a stream (i.e., deserialize it).
10.885 + */
10.886 + private void readObject(java.io.ObjectInputStream s)
10.887 + throws IOException, ClassNotFoundException
10.888 + {
10.889 + // Read in the length, threshold, and loadfactor
10.890 + s.defaultReadObject();
10.891 +
10.892 + // Read the original length of the array and number of elements
10.893 + int origlength = s.readInt();
10.894 + int elements = s.readInt();
10.895 +
10.896 + // Compute new size with a bit of room 5% to grow but
10.897 + // no larger than the original size. Make the length
10.898 + // odd if it's large enough, this helps distribute the entries.
10.899 + // Guard against the length ending up zero, that's not valid.
10.900 + int length = (int)(elements * loadFactor) + (elements / 20) + 3;
10.901 + if (length > elements && (length & 1) == 0)
10.902 + length--;
10.903 + if (origlength > 0 && length > origlength)
10.904 + length = origlength;
10.905 +
10.906 + Entry[] table = new Entry[length];
10.907 + count = 0;
10.908 +
10.909 + // Read the number of elements and then all the key/value objects
10.910 + for (; elements > 0; elements--) {
10.911 + K key = (K)s.readObject();
10.912 + V value = (V)s.readObject();
10.913 + // synch could be eliminated for performance
10.914 + reconstitutionPut(table, key, value);
10.915 + }
10.916 + this.table = table;
10.917 + }
10.918 +
10.919 + /**
10.920 + * The put method used by readObject. This is provided because put
10.921 + * is overridable and should not be called in readObject since the
10.922 + * subclass will not yet be initialized.
10.923 + *
10.924 + * <p>This differs from the regular put method in several ways. No
10.925 + * checking for rehashing is necessary since the number of elements
10.926 + * initially in the table is known. The modCount is not incremented
10.927 + * because we are creating a new instance. Also, no return value
10.928 + * is needed.
10.929 + */
10.930 + private void reconstitutionPut(Entry[] tab, K key, V value)
10.931 + throws StreamCorruptedException
10.932 + {
10.933 + if (value == null) {
10.934 + throw new java.io.StreamCorruptedException();
10.935 + }
10.936 + // Makes sure the key is not already in the hashtable.
10.937 + // This should not happen in deserialized version.
10.938 + int hash = key.hashCode();
10.939 + int index = (hash & 0x7FFFFFFF) % tab.length;
10.940 + for (Entry<K,V> e = tab[index] ; e != null ; e = e.next) {
10.941 + if ((e.hash == hash) && e.key.equals(key)) {
10.942 + throw new java.io.StreamCorruptedException();
10.943 + }
10.944 + }
10.945 + // Creates the new entry.
10.946 + Entry<K,V> e = tab[index];
10.947 + tab[index] = new Entry<>(hash, key, value, e);
10.948 + count++;
10.949 + }
10.950 +
10.951 + /**
10.952 + * Hashtable collision list.
10.953 + */
10.954 + private static class Entry<K,V> implements Map.Entry<K,V> {
10.955 + int hash;
10.956 + K key;
10.957 + V value;
10.958 + Entry<K,V> next;
10.959 +
10.960 + protected Entry(int hash, K key, V value, Entry<K,V> next) {
10.961 + this.hash = hash;
10.962 + this.key = key;
10.963 + this.value = value;
10.964 + this.next = next;
10.965 + }
10.966 +
10.967 + protected Object clone() {
10.968 + return new Entry<>(hash, key, value,
10.969 + (next==null ? null : (Entry<K,V>) next.clone()));
10.970 + }
10.971 +
10.972 + // Map.Entry Ops
10.973 +
10.974 + public K getKey() {
10.975 + return key;
10.976 + }
10.977 +
10.978 + public V getValue() {
10.979 + return value;
10.980 + }
10.981 +
10.982 + public V setValue(V value) {
10.983 + if (value == null)
10.984 + throw new NullPointerException();
10.985 +
10.986 + V oldValue = this.value;
10.987 + this.value = value;
10.988 + return oldValue;
10.989 + }
10.990 +
10.991 + public boolean equals(Object o) {
10.992 + if (!(o instanceof Map.Entry))
10.993 + return false;
10.994 + Map.Entry e = (Map.Entry)o;
10.995 +
10.996 + return (key==null ? e.getKey()==null : key.equals(e.getKey())) &&
10.997 + (value==null ? e.getValue()==null : value.equals(e.getValue()));
10.998 + }
10.999 +
10.1000 + public int hashCode() {
10.1001 + return hash ^ (value==null ? 0 : value.hashCode());
10.1002 + }
10.1003 +
10.1004 + public String toString() {
10.1005 + return key.toString()+"="+value.toString();
10.1006 + }
10.1007 + }
10.1008 +
10.1009 + // Types of Enumerations/Iterations
10.1010 + private static final int KEYS = 0;
10.1011 + private static final int VALUES = 1;
10.1012 + private static final int ENTRIES = 2;
10.1013 +
10.1014 + /**
10.1015 + * A hashtable enumerator class. This class implements both the
10.1016 + * Enumeration and Iterator interfaces, but individual instances
10.1017 + * can be created with the Iterator methods disabled. This is necessary
10.1018 + * to avoid unintentionally increasing the capabilities granted a user
10.1019 + * by passing an Enumeration.
10.1020 + */
10.1021 + private class Enumerator<T> implements Enumeration<T>, Iterator<T> {
10.1022 + Entry[] table = Hashtable.this.table;
10.1023 + int index = table.length;
10.1024 + Entry<K,V> entry = null;
10.1025 + Entry<K,V> lastReturned = null;
10.1026 + int type;
10.1027 +
10.1028 + /**
10.1029 + * Indicates whether this Enumerator is serving as an Iterator
10.1030 + * or an Enumeration. (true -> Iterator).
10.1031 + */
10.1032 + boolean iterator;
10.1033 +
10.1034 + /**
10.1035 + * The modCount value that the iterator believes that the backing
10.1036 + * Hashtable should have. If this expectation is violated, the iterator
10.1037 + * has detected concurrent modification.
10.1038 + */
10.1039 + protected int expectedModCount = modCount;
10.1040 +
10.1041 + Enumerator(int type, boolean iterator) {
10.1042 + this.type = type;
10.1043 + this.iterator = iterator;
10.1044 + }
10.1045 +
10.1046 + public boolean hasMoreElements() {
10.1047 + Entry<K,V> e = entry;
10.1048 + int i = index;
10.1049 + Entry[] t = table;
10.1050 + /* Use locals for faster loop iteration */
10.1051 + while (e == null && i > 0) {
10.1052 + e = t[--i];
10.1053 + }
10.1054 + entry = e;
10.1055 + index = i;
10.1056 + return e != null;
10.1057 + }
10.1058 +
10.1059 + public T nextElement() {
10.1060 + Entry<K,V> et = entry;
10.1061 + int i = index;
10.1062 + Entry[] t = table;
10.1063 + /* Use locals for faster loop iteration */
10.1064 + while (et == null && i > 0) {
10.1065 + et = t[--i];
10.1066 + }
10.1067 + entry = et;
10.1068 + index = i;
10.1069 + if (et != null) {
10.1070 + Entry<K,V> e = lastReturned = entry;
10.1071 + entry = e.next;
10.1072 + return type == KEYS ? (T)e.key : (type == VALUES ? (T)e.value : (T)e);
10.1073 + }
10.1074 + throw new NoSuchElementException("Hashtable Enumerator");
10.1075 + }
10.1076 +
10.1077 + // Iterator methods
10.1078 + public boolean hasNext() {
10.1079 + return hasMoreElements();
10.1080 + }
10.1081 +
10.1082 + public T next() {
10.1083 + if (modCount != expectedModCount)
10.1084 + throw new ConcurrentModificationException();
10.1085 + return nextElement();
10.1086 + }
10.1087 +
10.1088 + public void remove() {
10.1089 + if (!iterator)
10.1090 + throw new UnsupportedOperationException();
10.1091 + if (lastReturned == null)
10.1092 + throw new IllegalStateException("Hashtable Enumerator");
10.1093 + if (modCount != expectedModCount)
10.1094 + throw new ConcurrentModificationException();
10.1095 +
10.1096 + synchronized(Hashtable.this) {
10.1097 + Entry[] tab = Hashtable.this.table;
10.1098 + int index = (lastReturned.hash & 0x7FFFFFFF) % tab.length;
10.1099 +
10.1100 + for (Entry<K,V> e = tab[index], prev = null; e != null;
10.1101 + prev = e, e = e.next) {
10.1102 + if (e == lastReturned) {
10.1103 + modCount++;
10.1104 + expectedModCount++;
10.1105 + if (prev == null)
10.1106 + tab[index] = e.next;
10.1107 + else
10.1108 + prev.next = e.next;
10.1109 + count--;
10.1110 + lastReturned = null;
10.1111 + return;
10.1112 + }
10.1113 + }
10.1114 + throw new ConcurrentModificationException();
10.1115 + }
10.1116 + }
10.1117 + }
10.1118 +}
11.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
11.2 +++ b/emul/compact/src/main/java/java/util/LinkedList.java Mon Jan 28 13:28:02 2013 +0100
11.3 @@ -0,0 +1,1138 @@
11.4 +/*
11.5 + * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
11.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
11.7 + *
11.8 + * This code is free software; you can redistribute it and/or modify it
11.9 + * under the terms of the GNU General Public License version 2 only, as
11.10 + * published by the Free Software Foundation. Oracle designates this
11.11 + * particular file as subject to the "Classpath" exception as provided
11.12 + * by Oracle in the LICENSE file that accompanied this code.
11.13 + *
11.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
11.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
11.17 + * version 2 for more details (a copy is included in the LICENSE file that
11.18 + * accompanied this code).
11.19 + *
11.20 + * You should have received a copy of the GNU General Public License version
11.21 + * 2 along with this work; if not, write to the Free Software Foundation,
11.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
11.23 + *
11.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
11.25 + * or visit www.oracle.com if you need additional information or have any
11.26 + * questions.
11.27 + */
11.28 +
11.29 +package java.util;
11.30 +
11.31 +/**
11.32 + * Doubly-linked list implementation of the {@code List} and {@code Deque}
11.33 + * interfaces. Implements all optional list operations, and permits all
11.34 + * elements (including {@code null}).
11.35 + *
11.36 + * <p>All of the operations perform as could be expected for a doubly-linked
11.37 + * list. Operations that index into the list will traverse the list from
11.38 + * the beginning or the end, whichever is closer to the specified index.
11.39 + *
11.40 + * <p><strong>Note that this implementation is not synchronized.</strong>
11.41 + * If multiple threads access a linked list concurrently, and at least
11.42 + * one of the threads modifies the list structurally, it <i>must</i> be
11.43 + * synchronized externally. (A structural modification is any operation
11.44 + * that adds or deletes one or more elements; merely setting the value of
11.45 + * an element is not a structural modification.) This is typically
11.46 + * accomplished by synchronizing on some object that naturally
11.47 + * encapsulates the list.
11.48 + *
11.49 + * If no such object exists, the list should be "wrapped" using the
11.50 + * {@link Collections#synchronizedList Collections.synchronizedList}
11.51 + * method. This is best done at creation time, to prevent accidental
11.52 + * unsynchronized access to the list:<pre>
11.53 + * List list = Collections.synchronizedList(new LinkedList(...));</pre>
11.54 + *
11.55 + * <p>The iterators returned by this class's {@code iterator} and
11.56 + * {@code listIterator} methods are <i>fail-fast</i>: if the list is
11.57 + * structurally modified at any time after the iterator is created, in
11.58 + * any way except through the Iterator's own {@code remove} or
11.59 + * {@code add} methods, the iterator will throw a {@link
11.60 + * ConcurrentModificationException}. Thus, in the face of concurrent
11.61 + * modification, the iterator fails quickly and cleanly, rather than
11.62 + * risking arbitrary, non-deterministic behavior at an undetermined
11.63 + * time in the future.
11.64 + *
11.65 + * <p>Note that the fail-fast behavior of an iterator cannot be guaranteed
11.66 + * as it is, generally speaking, impossible to make any hard guarantees in the
11.67 + * presence of unsynchronized concurrent modification. Fail-fast iterators
11.68 + * throw {@code ConcurrentModificationException} on a best-effort basis.
11.69 + * Therefore, it would be wrong to write a program that depended on this
11.70 + * exception for its correctness: <i>the fail-fast behavior of iterators
11.71 + * should be used only to detect bugs.</i>
11.72 + *
11.73 + * <p>This class is a member of the
11.74 + * <a href="{@docRoot}/../technotes/guides/collections/index.html">
11.75 + * Java Collections Framework</a>.
11.76 + *
11.77 + * @author Josh Bloch
11.78 + * @see List
11.79 + * @see ArrayList
11.80 + * @since 1.2
11.81 + * @param <E> the type of elements held in this collection
11.82 + */
11.83 +
11.84 +public class LinkedList<E>
11.85 + extends AbstractSequentialList<E>
11.86 + implements List<E>, Deque<E>, Cloneable, java.io.Serializable
11.87 +{
11.88 + transient int size = 0;
11.89 +
11.90 + /**
11.91 + * Pointer to first node.
11.92 + * Invariant: (first == null && last == null) ||
11.93 + * (first.prev == null && first.item != null)
11.94 + */
11.95 + transient Node<E> first;
11.96 +
11.97 + /**
11.98 + * Pointer to last node.
11.99 + * Invariant: (first == null && last == null) ||
11.100 + * (last.next == null && last.item != null)
11.101 + */
11.102 + transient Node<E> last;
11.103 +
11.104 + /**
11.105 + * Constructs an empty list.
11.106 + */
11.107 + public LinkedList() {
11.108 + }
11.109 +
11.110 + /**
11.111 + * Constructs a list containing the elements of the specified
11.112 + * collection, in the order they are returned by the collection's
11.113 + * iterator.
11.114 + *
11.115 + * @param c the collection whose elements are to be placed into this list
11.116 + * @throws NullPointerException if the specified collection is null
11.117 + */
11.118 + public LinkedList(Collection<? extends E> c) {
11.119 + this();
11.120 + addAll(c);
11.121 + }
11.122 +
11.123 + /**
11.124 + * Links e as first element.
11.125 + */
11.126 + private void linkFirst(E e) {
11.127 + final Node<E> f = first;
11.128 + final Node<E> newNode = new Node<>(null, e, f);
11.129 + first = newNode;
11.130 + if (f == null)
11.131 + last = newNode;
11.132 + else
11.133 + f.prev = newNode;
11.134 + size++;
11.135 + modCount++;
11.136 + }
11.137 +
11.138 + /**
11.139 + * Links e as last element.
11.140 + */
11.141 + void linkLast(E e) {
11.142 + final Node<E> l = last;
11.143 + final Node<E> newNode = new Node<>(l, e, null);
11.144 + last = newNode;
11.145 + if (l == null)
11.146 + first = newNode;
11.147 + else
11.148 + l.next = newNode;
11.149 + size++;
11.150 + modCount++;
11.151 + }
11.152 +
11.153 + /**
11.154 + * Inserts element e before non-null Node succ.
11.155 + */
11.156 + void linkBefore(E e, Node<E> succ) {
11.157 + // assert succ != null;
11.158 + final Node<E> pred = succ.prev;
11.159 + final Node<E> newNode = new Node<>(pred, e, succ);
11.160 + succ.prev = newNode;
11.161 + if (pred == null)
11.162 + first = newNode;
11.163 + else
11.164 + pred.next = newNode;
11.165 + size++;
11.166 + modCount++;
11.167 + }
11.168 +
11.169 + /**
11.170 + * Unlinks non-null first node f.
11.171 + */
11.172 + private E unlinkFirst(Node<E> f) {
11.173 + // assert f == first && f != null;
11.174 + final E element = f.item;
11.175 + final Node<E> next = f.next;
11.176 + f.item = null;
11.177 + f.next = null; // help GC
11.178 + first = next;
11.179 + if (next == null)
11.180 + last = null;
11.181 + else
11.182 + next.prev = null;
11.183 + size--;
11.184 + modCount++;
11.185 + return element;
11.186 + }
11.187 +
11.188 + /**
11.189 + * Unlinks non-null last node l.
11.190 + */
11.191 + private E unlinkLast(Node<E> l) {
11.192 + // assert l == last && l != null;
11.193 + final E element = l.item;
11.194 + final Node<E> prev = l.prev;
11.195 + l.item = null;
11.196 + l.prev = null; // help GC
11.197 + last = prev;
11.198 + if (prev == null)
11.199 + first = null;
11.200 + else
11.201 + prev.next = null;
11.202 + size--;
11.203 + modCount++;
11.204 + return element;
11.205 + }
11.206 +
11.207 + /**
11.208 + * Unlinks non-null node x.
11.209 + */
11.210 + E unlink(Node<E> x) {
11.211 + // assert x != null;
11.212 + final E element = x.item;
11.213 + final Node<E> next = x.next;
11.214 + final Node<E> prev = x.prev;
11.215 +
11.216 + if (prev == null) {
11.217 + first = next;
11.218 + } else {
11.219 + prev.next = next;
11.220 + x.prev = null;
11.221 + }
11.222 +
11.223 + if (next == null) {
11.224 + last = prev;
11.225 + } else {
11.226 + next.prev = prev;
11.227 + x.next = null;
11.228 + }
11.229 +
11.230 + x.item = null;
11.231 + size--;
11.232 + modCount++;
11.233 + return element;
11.234 + }
11.235 +
11.236 + /**
11.237 + * Returns the first element in this list.
11.238 + *
11.239 + * @return the first element in this list
11.240 + * @throws NoSuchElementException if this list is empty
11.241 + */
11.242 + public E getFirst() {
11.243 + final Node<E> f = first;
11.244 + if (f == null)
11.245 + throw new NoSuchElementException();
11.246 + return f.item;
11.247 + }
11.248 +
11.249 + /**
11.250 + * Returns the last element in this list.
11.251 + *
11.252 + * @return the last element in this list
11.253 + * @throws NoSuchElementException if this list is empty
11.254 + */
11.255 + public E getLast() {
11.256 + final Node<E> l = last;
11.257 + if (l == null)
11.258 + throw new NoSuchElementException();
11.259 + return l.item;
11.260 + }
11.261 +
11.262 + /**
11.263 + * Removes and returns the first element from this list.
11.264 + *
11.265 + * @return the first element from this list
11.266 + * @throws NoSuchElementException if this list is empty
11.267 + */
11.268 + public E removeFirst() {
11.269 + final Node<E> f = first;
11.270 + if (f == null)
11.271 + throw new NoSuchElementException();
11.272 + return unlinkFirst(f);
11.273 + }
11.274 +
11.275 + /**
11.276 + * Removes and returns the last element from this list.
11.277 + *
11.278 + * @return the last element from this list
11.279 + * @throws NoSuchElementException if this list is empty
11.280 + */
11.281 + public E removeLast() {
11.282 + final Node<E> l = last;
11.283 + if (l == null)
11.284 + throw new NoSuchElementException();
11.285 + return unlinkLast(l);
11.286 + }
11.287 +
11.288 + /**
11.289 + * Inserts the specified element at the beginning of this list.
11.290 + *
11.291 + * @param e the element to add
11.292 + */
11.293 + public void addFirst(E e) {
11.294 + linkFirst(e);
11.295 + }
11.296 +
11.297 + /**
11.298 + * Appends the specified element to the end of this list.
11.299 + *
11.300 + * <p>This method is equivalent to {@link #add}.
11.301 + *
11.302 + * @param e the element to add
11.303 + */
11.304 + public void addLast(E e) {
11.305 + linkLast(e);
11.306 + }
11.307 +
11.308 + /**
11.309 + * Returns {@code true} if this list contains the specified element.
11.310 + * More formally, returns {@code true} if and only if this list contains
11.311 + * at least one element {@code e} such that
11.312 + * <tt>(o==null ? e==null : o.equals(e))</tt>.
11.313 + *
11.314 + * @param o element whose presence in this list is to be tested
11.315 + * @return {@code true} if this list contains the specified element
11.316 + */
11.317 + public boolean contains(Object o) {
11.318 + return indexOf(o) != -1;
11.319 + }
11.320 +
11.321 + /**
11.322 + * Returns the number of elements in this list.
11.323 + *
11.324 + * @return the number of elements in this list
11.325 + */
11.326 + public int size() {
11.327 + return size;
11.328 + }
11.329 +
11.330 + /**
11.331 + * Appends the specified element to the end of this list.
11.332 + *
11.333 + * <p>This method is equivalent to {@link #addLast}.
11.334 + *
11.335 + * @param e element to be appended to this list
11.336 + * @return {@code true} (as specified by {@link Collection#add})
11.337 + */
11.338 + public boolean add(E e) {
11.339 + linkLast(e);
11.340 + return true;
11.341 + }
11.342 +
11.343 + /**
11.344 + * Removes the first occurrence of the specified element from this list,
11.345 + * if it is present. If this list does not contain the element, it is
11.346 + * unchanged. More formally, removes the element with the lowest index
11.347 + * {@code i} such that
11.348 + * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>
11.349 + * (if such an element exists). Returns {@code true} if this list
11.350 + * contained the specified element (or equivalently, if this list
11.351 + * changed as a result of the call).
11.352 + *
11.353 + * @param o element to be removed from this list, if present
11.354 + * @return {@code true} if this list contained the specified element
11.355 + */
11.356 + public boolean remove(Object o) {
11.357 + if (o == null) {
11.358 + for (Node<E> x = first; x != null; x = x.next) {
11.359 + if (x.item == null) {
11.360 + unlink(x);
11.361 + return true;
11.362 + }
11.363 + }
11.364 + } else {
11.365 + for (Node<E> x = first; x != null; x = x.next) {
11.366 + if (o.equals(x.item)) {
11.367 + unlink(x);
11.368 + return true;
11.369 + }
11.370 + }
11.371 + }
11.372 + return false;
11.373 + }
11.374 +
11.375 + /**
11.376 + * Appends all of the elements in the specified collection to the end of
11.377 + * this list, in the order that they are returned by the specified
11.378 + * collection's iterator. The behavior of this operation is undefined if
11.379 + * the specified collection is modified while the operation is in
11.380 + * progress. (Note that this will occur if the specified collection is
11.381 + * this list, and it's nonempty.)
11.382 + *
11.383 + * @param c collection containing elements to be added to this list
11.384 + * @return {@code true} if this list changed as a result of the call
11.385 + * @throws NullPointerException if the specified collection is null
11.386 + */
11.387 + public boolean addAll(Collection<? extends E> c) {
11.388 + return addAll(size, c);
11.389 + }
11.390 +
11.391 + /**
11.392 + * Inserts all of the elements in the specified collection into this
11.393 + * list, starting at the specified position. Shifts the element
11.394 + * currently at that position (if any) and any subsequent elements to
11.395 + * the right (increases their indices). The new elements will appear
11.396 + * in the list in the order that they are returned by the
11.397 + * specified collection's iterator.
11.398 + *
11.399 + * @param index index at which to insert the first element
11.400 + * from the specified collection
11.401 + * @param c collection containing elements to be added to this list
11.402 + * @return {@code true} if this list changed as a result of the call
11.403 + * @throws IndexOutOfBoundsException {@inheritDoc}
11.404 + * @throws NullPointerException if the specified collection is null
11.405 + */
11.406 + public boolean addAll(int index, Collection<? extends E> c) {
11.407 + checkPositionIndex(index);
11.408 +
11.409 + Object[] a = c.toArray();
11.410 + int numNew = a.length;
11.411 + if (numNew == 0)
11.412 + return false;
11.413 +
11.414 + Node<E> pred, succ;
11.415 + if (index == size) {
11.416 + succ = null;
11.417 + pred = last;
11.418 + } else {
11.419 + succ = node(index);
11.420 + pred = succ.prev;
11.421 + }
11.422 +
11.423 + for (Object o : a) {
11.424 + @SuppressWarnings("unchecked") E e = (E) o;
11.425 + Node<E> newNode = new Node<>(pred, e, null);
11.426 + if (pred == null)
11.427 + first = newNode;
11.428 + else
11.429 + pred.next = newNode;
11.430 + pred = newNode;
11.431 + }
11.432 +
11.433 + if (succ == null) {
11.434 + last = pred;
11.435 + } else {
11.436 + pred.next = succ;
11.437 + succ.prev = pred;
11.438 + }
11.439 +
11.440 + size += numNew;
11.441 + modCount++;
11.442 + return true;
11.443 + }
11.444 +
11.445 + /**
11.446 + * Removes all of the elements from this list.
11.447 + * The list will be empty after this call returns.
11.448 + */
11.449 + public void clear() {
11.450 + // Clearing all of the links between nodes is "unnecessary", but:
11.451 + // - helps a generational GC if the discarded nodes inhabit
11.452 + // more than one generation
11.453 + // - is sure to free memory even if there is a reachable Iterator
11.454 + for (Node<E> x = first; x != null; ) {
11.455 + Node<E> next = x.next;
11.456 + x.item = null;
11.457 + x.next = null;
11.458 + x.prev = null;
11.459 + x = next;
11.460 + }
11.461 + first = last = null;
11.462 + size = 0;
11.463 + modCount++;
11.464 + }
11.465 +
11.466 +
11.467 + // Positional Access Operations
11.468 +
11.469 + /**
11.470 + * Returns the element at the specified position in this list.
11.471 + *
11.472 + * @param index index of the element to return
11.473 + * @return the element at the specified position in this list
11.474 + * @throws IndexOutOfBoundsException {@inheritDoc}
11.475 + */
11.476 + public E get(int index) {
11.477 + checkElementIndex(index);
11.478 + return node(index).item;
11.479 + }
11.480 +
11.481 + /**
11.482 + * Replaces the element at the specified position in this list with the
11.483 + * specified element.
11.484 + *
11.485 + * @param index index of the element to replace
11.486 + * @param element element to be stored at the specified position
11.487 + * @return the element previously at the specified position
11.488 + * @throws IndexOutOfBoundsException {@inheritDoc}
11.489 + */
11.490 + public E set(int index, E element) {
11.491 + checkElementIndex(index);
11.492 + Node<E> x = node(index);
11.493 + E oldVal = x.item;
11.494 + x.item = element;
11.495 + return oldVal;
11.496 + }
11.497 +
11.498 + /**
11.499 + * Inserts the specified element at the specified position in this list.
11.500 + * Shifts the element currently at that position (if any) and any
11.501 + * subsequent elements to the right (adds one to their indices).
11.502 + *
11.503 + * @param index index at which the specified element is to be inserted
11.504 + * @param element element to be inserted
11.505 + * @throws IndexOutOfBoundsException {@inheritDoc}
11.506 + */
11.507 + public void add(int index, E element) {
11.508 + checkPositionIndex(index);
11.509 +
11.510 + if (index == size)
11.511 + linkLast(element);
11.512 + else
11.513 + linkBefore(element, node(index));
11.514 + }
11.515 +
11.516 + /**
11.517 + * Removes the element at the specified position in this list. Shifts any
11.518 + * subsequent elements to the left (subtracts one from their indices).
11.519 + * Returns the element that was removed from the list.
11.520 + *
11.521 + * @param index the index of the element to be removed
11.522 + * @return the element previously at the specified position
11.523 + * @throws IndexOutOfBoundsException {@inheritDoc}
11.524 + */
11.525 + public E remove(int index) {
11.526 + checkElementIndex(index);
11.527 + return unlink(node(index));
11.528 + }
11.529 +
11.530 + /**
11.531 + * Tells if the argument is the index of an existing element.
11.532 + */
11.533 + private boolean isElementIndex(int index) {
11.534 + return index >= 0 && index < size;
11.535 + }
11.536 +
11.537 + /**
11.538 + * Tells if the argument is the index of a valid position for an
11.539 + * iterator or an add operation.
11.540 + */
11.541 + private boolean isPositionIndex(int index) {
11.542 + return index >= 0 && index <= size;
11.543 + }
11.544 +
11.545 + /**
11.546 + * Constructs an IndexOutOfBoundsException detail message.
11.547 + * Of the many possible refactorings of the error handling code,
11.548 + * this "outlining" performs best with both server and client VMs.
11.549 + */
11.550 + private String outOfBoundsMsg(int index) {
11.551 + return "Index: "+index+", Size: "+size;
11.552 + }
11.553 +
11.554 + private void checkElementIndex(int index) {
11.555 + if (!isElementIndex(index))
11.556 + throw new IndexOutOfBoundsException(outOfBoundsMsg(index));
11.557 + }
11.558 +
11.559 + private void checkPositionIndex(int index) {
11.560 + if (!isPositionIndex(index))
11.561 + throw new IndexOutOfBoundsException(outOfBoundsMsg(index));
11.562 + }
11.563 +
11.564 + /**
11.565 + * Returns the (non-null) Node at the specified element index.
11.566 + */
11.567 + Node<E> node(int index) {
11.568 + // assert isElementIndex(index);
11.569 +
11.570 + if (index < (size >> 1)) {
11.571 + Node<E> x = first;
11.572 + for (int i = 0; i < index; i++)
11.573 + x = x.next;
11.574 + return x;
11.575 + } else {
11.576 + Node<E> x = last;
11.577 + for (int i = size - 1; i > index; i--)
11.578 + x = x.prev;
11.579 + return x;
11.580 + }
11.581 + }
11.582 +
11.583 + // Search Operations
11.584 +
11.585 + /**
11.586 + * Returns the index of the first occurrence of the specified element
11.587 + * in this list, or -1 if this list does not contain the element.
11.588 + * More formally, returns the lowest index {@code i} such that
11.589 + * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
11.590 + * or -1 if there is no such index.
11.591 + *
11.592 + * @param o element to search for
11.593 + * @return the index of the first occurrence of the specified element in
11.594 + * this list, or -1 if this list does not contain the element
11.595 + */
11.596 + public int indexOf(Object o) {
11.597 + int index = 0;
11.598 + if (o == null) {
11.599 + for (Node<E> x = first; x != null; x = x.next) {
11.600 + if (x.item == null)
11.601 + return index;
11.602 + index++;
11.603 + }
11.604 + } else {
11.605 + for (Node<E> x = first; x != null; x = x.next) {
11.606 + if (o.equals(x.item))
11.607 + return index;
11.608 + index++;
11.609 + }
11.610 + }
11.611 + return -1;
11.612 + }
11.613 +
11.614 + /**
11.615 + * Returns the index of the last occurrence of the specified element
11.616 + * in this list, or -1 if this list does not contain the element.
11.617 + * More formally, returns the highest index {@code i} such that
11.618 + * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
11.619 + * or -1 if there is no such index.
11.620 + *
11.621 + * @param o element to search for
11.622 + * @return the index of the last occurrence of the specified element in
11.623 + * this list, or -1 if this list does not contain the element
11.624 + */
11.625 + public int lastIndexOf(Object o) {
11.626 + int index = size;
11.627 + if (o == null) {
11.628 + for (Node<E> x = last; x != null; x = x.prev) {
11.629 + index--;
11.630 + if (x.item == null)
11.631 + return index;
11.632 + }
11.633 + } else {
11.634 + for (Node<E> x = last; x != null; x = x.prev) {
11.635 + index--;
11.636 + if (o.equals(x.item))
11.637 + return index;
11.638 + }
11.639 + }
11.640 + return -1;
11.641 + }
11.642 +
11.643 + // Queue operations.
11.644 +
11.645 + /**
11.646 + * Retrieves, but does not remove, the head (first element) of this list.
11.647 + *
11.648 + * @return the head of this list, or {@code null} if this list is empty
11.649 + * @since 1.5
11.650 + */
11.651 + public E peek() {
11.652 + final Node<E> f = first;
11.653 + return (f == null) ? null : f.item;
11.654 + }
11.655 +
11.656 + /**
11.657 + * Retrieves, but does not remove, the head (first element) of this list.
11.658 + *
11.659 + * @return the head of this list
11.660 + * @throws NoSuchElementException if this list is empty
11.661 + * @since 1.5
11.662 + */
11.663 + public E element() {
11.664 + return getFirst();
11.665 + }
11.666 +
11.667 + /**
11.668 + * Retrieves and removes the head (first element) of this list.
11.669 + *
11.670 + * @return the head of this list, or {@code null} if this list is empty
11.671 + * @since 1.5
11.672 + */
11.673 + public E poll() {
11.674 + final Node<E> f = first;
11.675 + return (f == null) ? null : unlinkFirst(f);
11.676 + }
11.677 +
11.678 + /**
11.679 + * Retrieves and removes the head (first element) of this list.
11.680 + *
11.681 + * @return the head of this list
11.682 + * @throws NoSuchElementException if this list is empty
11.683 + * @since 1.5
11.684 + */
11.685 + public E remove() {
11.686 + return removeFirst();
11.687 + }
11.688 +
11.689 + /**
11.690 + * Adds the specified element as the tail (last element) of this list.
11.691 + *
11.692 + * @param e the element to add
11.693 + * @return {@code true} (as specified by {@link Queue#offer})
11.694 + * @since 1.5
11.695 + */
11.696 + public boolean offer(E e) {
11.697 + return add(e);
11.698 + }
11.699 +
11.700 + // Deque operations
11.701 + /**
11.702 + * Inserts the specified element at the front of this list.
11.703 + *
11.704 + * @param e the element to insert
11.705 + * @return {@code true} (as specified by {@link Deque#offerFirst})
11.706 + * @since 1.6
11.707 + */
11.708 + public boolean offerFirst(E e) {
11.709 + addFirst(e);
11.710 + return true;
11.711 + }
11.712 +
11.713 + /**
11.714 + * Inserts the specified element at the end of this list.
11.715 + *
11.716 + * @param e the element to insert
11.717 + * @return {@code true} (as specified by {@link Deque#offerLast})
11.718 + * @since 1.6
11.719 + */
11.720 + public boolean offerLast(E e) {
11.721 + addLast(e);
11.722 + return true;
11.723 + }
11.724 +
11.725 + /**
11.726 + * Retrieves, but does not remove, the first element of this list,
11.727 + * or returns {@code null} if this list is empty.
11.728 + *
11.729 + * @return the first element of this list, or {@code null}
11.730 + * if this list is empty
11.731 + * @since 1.6
11.732 + */
11.733 + public E peekFirst() {
11.734 + final Node<E> f = first;
11.735 + return (f == null) ? null : f.item;
11.736 + }
11.737 +
11.738 + /**
11.739 + * Retrieves, but does not remove, the last element of this list,
11.740 + * or returns {@code null} if this list is empty.
11.741 + *
11.742 + * @return the last element of this list, or {@code null}
11.743 + * if this list is empty
11.744 + * @since 1.6
11.745 + */
11.746 + public E peekLast() {
11.747 + final Node<E> l = last;
11.748 + return (l == null) ? null : l.item;
11.749 + }
11.750 +
11.751 + /**
11.752 + * Retrieves and removes the first element of this list,
11.753 + * or returns {@code null} if this list is empty.
11.754 + *
11.755 + * @return the first element of this list, or {@code null} if
11.756 + * this list is empty
11.757 + * @since 1.6
11.758 + */
11.759 + public E pollFirst() {
11.760 + final Node<E> f = first;
11.761 + return (f == null) ? null : unlinkFirst(f);
11.762 + }
11.763 +
11.764 + /**
11.765 + * Retrieves and removes the last element of this list,
11.766 + * or returns {@code null} if this list is empty.
11.767 + *
11.768 + * @return the last element of this list, or {@code null} if
11.769 + * this list is empty
11.770 + * @since 1.6
11.771 + */
11.772 + public E pollLast() {
11.773 + final Node<E> l = last;
11.774 + return (l == null) ? null : unlinkLast(l);
11.775 + }
11.776 +
11.777 + /**
11.778 + * Pushes an element onto the stack represented by this list. In other
11.779 + * words, inserts the element at the front of this list.
11.780 + *
11.781 + * <p>This method is equivalent to {@link #addFirst}.
11.782 + *
11.783 + * @param e the element to push
11.784 + * @since 1.6
11.785 + */
11.786 + public void push(E e) {
11.787 + addFirst(e);
11.788 + }
11.789 +
11.790 + /**
11.791 + * Pops an element from the stack represented by this list. In other
11.792 + * words, removes and returns the first element of this list.
11.793 + *
11.794 + * <p>This method is equivalent to {@link #removeFirst()}.
11.795 + *
11.796 + * @return the element at the front of this list (which is the top
11.797 + * of the stack represented by this list)
11.798 + * @throws NoSuchElementException if this list is empty
11.799 + * @since 1.6
11.800 + */
11.801 + public E pop() {
11.802 + return removeFirst();
11.803 + }
11.804 +
11.805 + /**
11.806 + * Removes the first occurrence of the specified element in this
11.807 + * list (when traversing the list from head to tail). If the list
11.808 + * does not contain the element, it is unchanged.
11.809 + *
11.810 + * @param o element to be removed from this list, if present
11.811 + * @return {@code true} if the list contained the specified element
11.812 + * @since 1.6
11.813 + */
11.814 + public boolean removeFirstOccurrence(Object o) {
11.815 + return remove(o);
11.816 + }
11.817 +
11.818 + /**
11.819 + * Removes the last occurrence of the specified element in this
11.820 + * list (when traversing the list from head to tail). If the list
11.821 + * does not contain the element, it is unchanged.
11.822 + *
11.823 + * @param o element to be removed from this list, if present
11.824 + * @return {@code true} if the list contained the specified element
11.825 + * @since 1.6
11.826 + */
11.827 + public boolean removeLastOccurrence(Object o) {
11.828 + if (o == null) {
11.829 + for (Node<E> x = last; x != null; x = x.prev) {
11.830 + if (x.item == null) {
11.831 + unlink(x);
11.832 + return true;
11.833 + }
11.834 + }
11.835 + } else {
11.836 + for (Node<E> x = last; x != null; x = x.prev) {
11.837 + if (o.equals(x.item)) {
11.838 + unlink(x);
11.839 + return true;
11.840 + }
11.841 + }
11.842 + }
11.843 + return false;
11.844 + }
11.845 +
11.846 + /**
11.847 + * Returns a list-iterator of the elements in this list (in proper
11.848 + * sequence), starting at the specified position in the list.
11.849 + * Obeys the general contract of {@code List.listIterator(int)}.<p>
11.850 + *
11.851 + * The list-iterator is <i>fail-fast</i>: if the list is structurally
11.852 + * modified at any time after the Iterator is created, in any way except
11.853 + * through the list-iterator's own {@code remove} or {@code add}
11.854 + * methods, the list-iterator will throw a
11.855 + * {@code ConcurrentModificationException}. Thus, in the face of
11.856 + * concurrent modification, the iterator fails quickly and cleanly, rather
11.857 + * than risking arbitrary, non-deterministic behavior at an undetermined
11.858 + * time in the future.
11.859 + *
11.860 + * @param index index of the first element to be returned from the
11.861 + * list-iterator (by a call to {@code next})
11.862 + * @return a ListIterator of the elements in this list (in proper
11.863 + * sequence), starting at the specified position in the list
11.864 + * @throws IndexOutOfBoundsException {@inheritDoc}
11.865 + * @see List#listIterator(int)
11.866 + */
11.867 + public ListIterator<E> listIterator(int index) {
11.868 + checkPositionIndex(index);
11.869 + return new ListItr(index);
11.870 + }
11.871 +
11.872 + private class ListItr implements ListIterator<E> {
11.873 + private Node<E> lastReturned = null;
11.874 + private Node<E> next;
11.875 + private int nextIndex;
11.876 + private int expectedModCount = modCount;
11.877 +
11.878 + ListItr(int index) {
11.879 + // assert isPositionIndex(index);
11.880 + next = (index == size) ? null : node(index);
11.881 + nextIndex = index;
11.882 + }
11.883 +
11.884 + public boolean hasNext() {
11.885 + return nextIndex < size;
11.886 + }
11.887 +
11.888 + public E next() {
11.889 + checkForComodification();
11.890 + if (!hasNext())
11.891 + throw new NoSuchElementException();
11.892 +
11.893 + lastReturned = next;
11.894 + next = next.next;
11.895 + nextIndex++;
11.896 + return lastReturned.item;
11.897 + }
11.898 +
11.899 + public boolean hasPrevious() {
11.900 + return nextIndex > 0;
11.901 + }
11.902 +
11.903 + public E previous() {
11.904 + checkForComodification();
11.905 + if (!hasPrevious())
11.906 + throw new NoSuchElementException();
11.907 +
11.908 + lastReturned = next = (next == null) ? last : next.prev;
11.909 + nextIndex--;
11.910 + return lastReturned.item;
11.911 + }
11.912 +
11.913 + public int nextIndex() {
11.914 + return nextIndex;
11.915 + }
11.916 +
11.917 + public int previousIndex() {
11.918 + return nextIndex - 1;
11.919 + }
11.920 +
11.921 + public void remove() {
11.922 + checkForComodification();
11.923 + if (lastReturned == null)
11.924 + throw new IllegalStateException();
11.925 +
11.926 + Node<E> lastNext = lastReturned.next;
11.927 + unlink(lastReturned);
11.928 + if (next == lastReturned)
11.929 + next = lastNext;
11.930 + else
11.931 + nextIndex--;
11.932 + lastReturned = null;
11.933 + expectedModCount++;
11.934 + }
11.935 +
11.936 + public void set(E e) {
11.937 + if (lastReturned == null)
11.938 + throw new IllegalStateException();
11.939 + checkForComodification();
11.940 + lastReturned.item = e;
11.941 + }
11.942 +
11.943 + public void add(E e) {
11.944 + checkForComodification();
11.945 + lastReturned = null;
11.946 + if (next == null)
11.947 + linkLast(e);
11.948 + else
11.949 + linkBefore(e, next);
11.950 + nextIndex++;
11.951 + expectedModCount++;
11.952 + }
11.953 +
11.954 + final void checkForComodification() {
11.955 + if (modCount != expectedModCount)
11.956 + throw new ConcurrentModificationException();
11.957 + }
11.958 + }
11.959 +
11.960 + private static class Node<E> {
11.961 + E item;
11.962 + Node<E> next;
11.963 + Node<E> prev;
11.964 +
11.965 + Node(Node<E> prev, E element, Node<E> next) {
11.966 + this.item = element;
11.967 + this.next = next;
11.968 + this.prev = prev;
11.969 + }
11.970 + }
11.971 +
11.972 + /**
11.973 + * @since 1.6
11.974 + */
11.975 + public Iterator<E> descendingIterator() {
11.976 + return new DescendingIterator();
11.977 + }
11.978 +
11.979 + /**
11.980 + * Adapter to provide descending iterators via ListItr.previous
11.981 + */
11.982 + private class DescendingIterator implements Iterator<E> {
11.983 + private final ListItr itr = new ListItr(size());
11.984 + public boolean hasNext() {
11.985 + return itr.hasPrevious();
11.986 + }
11.987 + public E next() {
11.988 + return itr.previous();
11.989 + }
11.990 + public void remove() {
11.991 + itr.remove();
11.992 + }
11.993 + }
11.994 +
11.995 + @SuppressWarnings("unchecked")
11.996 + private LinkedList<E> superClone() {
11.997 + try {
11.998 + return (LinkedList<E>) super.clone();
11.999 + } catch (CloneNotSupportedException e) {
11.1000 + throw new InternalError();
11.1001 + }
11.1002 + }
11.1003 +
11.1004 + /**
11.1005 + * Returns a shallow copy of this {@code LinkedList}. (The elements
11.1006 + * themselves are not cloned.)
11.1007 + *
11.1008 + * @return a shallow copy of this {@code LinkedList} instance
11.1009 + */
11.1010 + public Object clone() {
11.1011 + LinkedList<E> clone = superClone();
11.1012 +
11.1013 + // Put clone into "virgin" state
11.1014 + clone.first = clone.last = null;
11.1015 + clone.size = 0;
11.1016 + clone.modCount = 0;
11.1017 +
11.1018 + // Initialize clone with our elements
11.1019 + for (Node<E> x = first; x != null; x = x.next)
11.1020 + clone.add(x.item);
11.1021 +
11.1022 + return clone;
11.1023 + }
11.1024 +
11.1025 + /**
11.1026 + * Returns an array containing all of the elements in this list
11.1027 + * in proper sequence (from first to last element).
11.1028 + *
11.1029 + * <p>The returned array will be "safe" in that no references to it are
11.1030 + * maintained by this list. (In other words, this method must allocate
11.1031 + * a new array). The caller is thus free to modify the returned array.
11.1032 + *
11.1033 + * <p>This method acts as bridge between array-based and collection-based
11.1034 + * APIs.
11.1035 + *
11.1036 + * @return an array containing all of the elements in this list
11.1037 + * in proper sequence
11.1038 + */
11.1039 + public Object[] toArray() {
11.1040 + Object[] result = new Object[size];
11.1041 + int i = 0;
11.1042 + for (Node<E> x = first; x != null; x = x.next)
11.1043 + result[i++] = x.item;
11.1044 + return result;
11.1045 + }
11.1046 +
11.1047 + /**
11.1048 + * Returns an array containing all of the elements in this list in
11.1049 + * proper sequence (from first to last element); the runtime type of
11.1050 + * the returned array is that of the specified array. If the list fits
11.1051 + * in the specified array, it is returned therein. Otherwise, a new
11.1052 + * array is allocated with the runtime type of the specified array and
11.1053 + * the size of this list.
11.1054 + *
11.1055 + * <p>If the list fits in the specified array with room to spare (i.e.,
11.1056 + * the array has more elements than the list), the element in the array
11.1057 + * immediately following the end of the list is set to {@code null}.
11.1058 + * (This is useful in determining the length of the list <i>only</i> if
11.1059 + * the caller knows that the list does not contain any null elements.)
11.1060 + *
11.1061 + * <p>Like the {@link #toArray()} method, this method acts as bridge between
11.1062 + * array-based and collection-based APIs. Further, this method allows
11.1063 + * precise control over the runtime type of the output array, and may,
11.1064 + * under certain circumstances, be used to save allocation costs.
11.1065 + *
11.1066 + * <p>Suppose {@code x} is a list known to contain only strings.
11.1067 + * The following code can be used to dump the list into a newly
11.1068 + * allocated array of {@code String}:
11.1069 + *
11.1070 + * <pre>
11.1071 + * String[] y = x.toArray(new String[0]);</pre>
11.1072 + *
11.1073 + * Note that {@code toArray(new Object[0])} is identical in function to
11.1074 + * {@code toArray()}.
11.1075 + *
11.1076 + * @param a the array into which the elements of the list are to
11.1077 + * be stored, if it is big enough; otherwise, a new array of the
11.1078 + * same runtime type is allocated for this purpose.
11.1079 + * @return an array containing the elements of the list
11.1080 + * @throws ArrayStoreException if the runtime type of the specified array
11.1081 + * is not a supertype of the runtime type of every element in
11.1082 + * this list
11.1083 + * @throws NullPointerException if the specified array is null
11.1084 + */
11.1085 + @SuppressWarnings("unchecked")
11.1086 + public <T> T[] toArray(T[] a) {
11.1087 + if (a.length < size)
11.1088 + a = (T[])java.lang.reflect.Array.newInstance(
11.1089 + a.getClass().getComponentType(), size);
11.1090 + int i = 0;
11.1091 + Object[] result = a;
11.1092 + for (Node<E> x = first; x != null; x = x.next)
11.1093 + result[i++] = x.item;
11.1094 +
11.1095 + if (a.length > size)
11.1096 + a[size] = null;
11.1097 +
11.1098 + return a;
11.1099 + }
11.1100 +
11.1101 + private static final long serialVersionUID = 876323262645176354L;
11.1102 +
11.1103 + /**
11.1104 + * Saves the state of this {@code LinkedList} instance to a stream
11.1105 + * (that is, serializes it).
11.1106 + *
11.1107 + * @serialData The size of the list (the number of elements it
11.1108 + * contains) is emitted (int), followed by all of its
11.1109 + * elements (each an Object) in the proper order.
11.1110 + */
11.1111 + private void writeObject(java.io.ObjectOutputStream s)
11.1112 + throws java.io.IOException {
11.1113 + // Write out any hidden serialization magic
11.1114 + s.defaultWriteObject();
11.1115 +
11.1116 + // Write out size
11.1117 + s.writeInt(size);
11.1118 +
11.1119 + // Write out all elements in the proper order.
11.1120 + for (Node<E> x = first; x != null; x = x.next)
11.1121 + s.writeObject(x.item);
11.1122 + }
11.1123 +
11.1124 + /**
11.1125 + * Reconstitutes this {@code LinkedList} instance from a stream
11.1126 + * (that is, deserializes it).
11.1127 + */
11.1128 + @SuppressWarnings("unchecked")
11.1129 + private void readObject(java.io.ObjectInputStream s)
11.1130 + throws java.io.IOException, ClassNotFoundException {
11.1131 + // Read in any hidden serialization magic
11.1132 + s.defaultReadObject();
11.1133 +
11.1134 + // Read in size
11.1135 + int size = s.readInt();
11.1136 +
11.1137 + // Read in all elements in the proper order.
11.1138 + for (int i = 0; i < size; i++)
11.1139 + linkLast((E)s.readObject());
11.1140 + }
11.1141 +}
12.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
12.2 +++ b/emul/compact/src/main/java/java/util/Queue.java Mon Jan 28 13:28:02 2013 +0100
12.3 @@ -0,0 +1,218 @@
12.4 +/*
12.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
12.6 + *
12.7 + * This code is free software; you can redistribute it and/or modify it
12.8 + * under the terms of the GNU General Public License version 2 only, as
12.9 + * published by the Free Software Foundation. Oracle designates this
12.10 + * particular file as subject to the "Classpath" exception as provided
12.11 + * by Oracle in the LICENSE file that accompanied this code.
12.12 + *
12.13 + * This code is distributed in the hope that it will be useful, but WITHOUT
12.14 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12.15 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12.16 + * version 2 for more details (a copy is included in the LICENSE file that
12.17 + * accompanied this code).
12.18 + *
12.19 + * You should have received a copy of the GNU General Public License version
12.20 + * 2 along with this work; if not, write to the Free Software Foundation,
12.21 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
12.22 + *
12.23 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
12.24 + * or visit www.oracle.com if you need additional information or have any
12.25 + * questions.
12.26 + */
12.27 +
12.28 +/*
12.29 + * This file is available under and governed by the GNU General Public
12.30 + * License version 2 only, as published by the Free Software Foundation.
12.31 + * However, the following notice accompanied the original version of this
12.32 + * file:
12.33 + *
12.34 + * Written by Doug Lea with assistance from members of JCP JSR-166
12.35 + * Expert Group and released to the public domain, as explained at
12.36 + * http://creativecommons.org/publicdomain/zero/1.0/
12.37 + */
12.38 +
12.39 +package java.util;
12.40 +
12.41 +/**
12.42 + * A collection designed for holding elements prior to processing.
12.43 + * Besides basic {@link java.util.Collection Collection} operations,
12.44 + * queues provide additional insertion, extraction, and inspection
12.45 + * operations. Each of these methods exists in two forms: one throws
12.46 + * an exception if the operation fails, the other returns a special
12.47 + * value (either <tt>null</tt> or <tt>false</tt>, depending on the
12.48 + * operation). The latter form of the insert operation is designed
12.49 + * specifically for use with capacity-restricted <tt>Queue</tt>
12.50 + * implementations; in most implementations, insert operations cannot
12.51 + * fail.
12.52 + *
12.53 + * <p>
12.54 + * <table BORDER CELLPADDING=3 CELLSPACING=1>
12.55 + * <tr>
12.56 + * <td></td>
12.57 + * <td ALIGN=CENTER><em>Throws exception</em></td>
12.58 + * <td ALIGN=CENTER><em>Returns special value</em></td>
12.59 + * </tr>
12.60 + * <tr>
12.61 + * <td><b>Insert</b></td>
12.62 + * <td>{@link #add add(e)}</td>
12.63 + * <td>{@link #offer offer(e)}</td>
12.64 + * </tr>
12.65 + * <tr>
12.66 + * <td><b>Remove</b></td>
12.67 + * <td>{@link #remove remove()}</td>
12.68 + * <td>{@link #poll poll()}</td>
12.69 + * </tr>
12.70 + * <tr>
12.71 + * <td><b>Examine</b></td>
12.72 + * <td>{@link #element element()}</td>
12.73 + * <td>{@link #peek peek()}</td>
12.74 + * </tr>
12.75 + * </table>
12.76 + *
12.77 + * <p>Queues typically, but do not necessarily, order elements in a
12.78 + * FIFO (first-in-first-out) manner. Among the exceptions are
12.79 + * priority queues, which order elements according to a supplied
12.80 + * comparator, or the elements' natural ordering, and LIFO queues (or
12.81 + * stacks) which order the elements LIFO (last-in-first-out).
12.82 + * Whatever the ordering used, the <em>head</em> of the queue is that
12.83 + * element which would be removed by a call to {@link #remove() } or
12.84 + * {@link #poll()}. In a FIFO queue, all new elements are inserted at
12.85 + * the <em> tail</em> of the queue. Other kinds of queues may use
12.86 + * different placement rules. Every <tt>Queue</tt> implementation
12.87 + * must specify its ordering properties.
12.88 + *
12.89 + * <p>The {@link #offer offer} method inserts an element if possible,
12.90 + * otherwise returning <tt>false</tt>. This differs from the {@link
12.91 + * java.util.Collection#add Collection.add} method, which can fail to
12.92 + * add an element only by throwing an unchecked exception. The
12.93 + * <tt>offer</tt> method is designed for use when failure is a normal,
12.94 + * rather than exceptional occurrence, for example, in fixed-capacity
12.95 + * (or "bounded") queues.
12.96 + *
12.97 + * <p>The {@link #remove()} and {@link #poll()} methods remove and
12.98 + * return the head of the queue.
12.99 + * Exactly which element is removed from the queue is a
12.100 + * function of the queue's ordering policy, which differs from
12.101 + * implementation to implementation. The <tt>remove()</tt> and
12.102 + * <tt>poll()</tt> methods differ only in their behavior when the
12.103 + * queue is empty: the <tt>remove()</tt> method throws an exception,
12.104 + * while the <tt>poll()</tt> method returns <tt>null</tt>.
12.105 + *
12.106 + * <p>The {@link #element()} and {@link #peek()} methods return, but do
12.107 + * not remove, the head of the queue.
12.108 + *
12.109 + * <p>The <tt>Queue</tt> interface does not define the <i>blocking queue
12.110 + * methods</i>, which are common in concurrent programming. These methods,
12.111 + * which wait for elements to appear or for space to become available, are
12.112 + * defined in the {@link java.util.concurrent.BlockingQueue} interface, which
12.113 + * extends this interface.
12.114 + *
12.115 + * <p><tt>Queue</tt> implementations generally do not allow insertion
12.116 + * of <tt>null</tt> elements, although some implementations, such as
12.117 + * {@link LinkedList}, do not prohibit insertion of <tt>null</tt>.
12.118 + * Even in the implementations that permit it, <tt>null</tt> should
12.119 + * not be inserted into a <tt>Queue</tt>, as <tt>null</tt> is also
12.120 + * used as a special return value by the <tt>poll</tt> method to
12.121 + * indicate that the queue contains no elements.
12.122 + *
12.123 + * <p><tt>Queue</tt> implementations generally do not define
12.124 + * element-based versions of methods <tt>equals</tt> and
12.125 + * <tt>hashCode</tt> but instead inherit the identity based versions
12.126 + * from class <tt>Object</tt>, because element-based equality is not
12.127 + * always well-defined for queues with the same elements but different
12.128 + * ordering properties.
12.129 + *
12.130 + *
12.131 + * <p>This interface is a member of the
12.132 + * <a href="{@docRoot}/../technotes/guides/collections/index.html">
12.133 + * Java Collections Framework</a>.
12.134 + *
12.135 + * @see java.util.Collection
12.136 + * @see LinkedList
12.137 + * @see PriorityQueue
12.138 + * @see java.util.concurrent.LinkedBlockingQueue
12.139 + * @see java.util.concurrent.BlockingQueue
12.140 + * @see java.util.concurrent.ArrayBlockingQueue
12.141 + * @see java.util.concurrent.LinkedBlockingQueue
12.142 + * @see java.util.concurrent.PriorityBlockingQueue
12.143 + * @since 1.5
12.144 + * @author Doug Lea
12.145 + * @param <E> the type of elements held in this collection
12.146 + */
12.147 +public interface Queue<E> extends Collection<E> {
12.148 + /**
12.149 + * Inserts the specified element into this queue if it is possible to do so
12.150 + * immediately without violating capacity restrictions, returning
12.151 + * <tt>true</tt> upon success and throwing an <tt>IllegalStateException</tt>
12.152 + * if no space is currently available.
12.153 + *
12.154 + * @param e the element to add
12.155 + * @return <tt>true</tt> (as specified by {@link Collection#add})
12.156 + * @throws IllegalStateException if the element cannot be added at this
12.157 + * time due to capacity restrictions
12.158 + * @throws ClassCastException if the class of the specified element
12.159 + * prevents it from being added to this queue
12.160 + * @throws NullPointerException if the specified element is null and
12.161 + * this queue does not permit null elements
12.162 + * @throws IllegalArgumentException if some property of this element
12.163 + * prevents it from being added to this queue
12.164 + */
12.165 + boolean add(E e);
12.166 +
12.167 + /**
12.168 + * Inserts the specified element into this queue if it is possible to do
12.169 + * so immediately without violating capacity restrictions.
12.170 + * When using a capacity-restricted queue, this method is generally
12.171 + * preferable to {@link #add}, which can fail to insert an element only
12.172 + * by throwing an exception.
12.173 + *
12.174 + * @param e the element to add
12.175 + * @return <tt>true</tt> if the element was added to this queue, else
12.176 + * <tt>false</tt>
12.177 + * @throws ClassCastException if the class of the specified element
12.178 + * prevents it from being added to this queue
12.179 + * @throws NullPointerException if the specified element is null and
12.180 + * this queue does not permit null elements
12.181 + * @throws IllegalArgumentException if some property of this element
12.182 + * prevents it from being added to this queue
12.183 + */
12.184 + boolean offer(E e);
12.185 +
12.186 + /**
12.187 + * Retrieves and removes the head of this queue. This method differs
12.188 + * from {@link #poll poll} only in that it throws an exception if this
12.189 + * queue is empty.
12.190 + *
12.191 + * @return the head of this queue
12.192 + * @throws NoSuchElementException if this queue is empty
12.193 + */
12.194 + E remove();
12.195 +
12.196 + /**
12.197 + * Retrieves and removes the head of this queue,
12.198 + * or returns <tt>null</tt> if this queue is empty.
12.199 + *
12.200 + * @return the head of this queue, or <tt>null</tt> if this queue is empty
12.201 + */
12.202 + E poll();
12.203 +
12.204 + /**
12.205 + * Retrieves, but does not remove, the head of this queue. This method
12.206 + * differs from {@link #peek peek} only in that it throws an exception
12.207 + * if this queue is empty.
12.208 + *
12.209 + * @return the head of this queue
12.210 + * @throws NoSuchElementException if this queue is empty
12.211 + */
12.212 + E element();
12.213 +
12.214 + /**
12.215 + * Retrieves, but does not remove, the head of this queue,
12.216 + * or returns <tt>null</tt> if this queue is empty.
12.217 + *
12.218 + * @return the head of this queue, or <tt>null</tt> if this queue is empty
12.219 + */
12.220 + E peek();
12.221 +}
13.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
13.2 +++ b/emul/compact/src/main/java/java/util/Random.java Mon Jan 28 13:28:02 2013 +0100
13.3 @@ -0,0 +1,575 @@
13.4 +/*
13.5 + * Copyright (c) 1995, 2010, Oracle and/or its affiliates. All rights reserved.
13.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
13.7 + *
13.8 + * This code is free software; you can redistribute it and/or modify it
13.9 + * under the terms of the GNU General Public License version 2 only, as
13.10 + * published by the Free Software Foundation. Oracle designates this
13.11 + * particular file as subject to the "Classpath" exception as provided
13.12 + * by Oracle in the LICENSE file that accompanied this code.
13.13 + *
13.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
13.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13.17 + * version 2 for more details (a copy is included in the LICENSE file that
13.18 + * accompanied this code).
13.19 + *
13.20 + * You should have received a copy of the GNU General Public License version
13.21 + * 2 along with this work; if not, write to the Free Software Foundation,
13.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
13.23 + *
13.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
13.25 + * or visit www.oracle.com if you need additional information or have any
13.26 + * questions.
13.27 + */
13.28 +
13.29 +package java.util;
13.30 +import java.io.*;
13.31 +import java.util.concurrent.atomic.AtomicLong;
13.32 +import sun.misc.Unsafe;
13.33 +
13.34 +/**
13.35 + * An instance of this class is used to generate a stream of
13.36 + * pseudorandom numbers. The class uses a 48-bit seed, which is
13.37 + * modified using a linear congruential formula. (See Donald Knuth,
13.38 + * <i>The Art of Computer Programming, Volume 2</i>, Section 3.2.1.)
13.39 + * <p>
13.40 + * If two instances of {@code Random} are created with the same
13.41 + * seed, and the same sequence of method calls is made for each, they
13.42 + * will generate and return identical sequences of numbers. In order to
13.43 + * guarantee this property, particular algorithms are specified for the
13.44 + * class {@code Random}. Java implementations must use all the algorithms
13.45 + * shown here for the class {@code Random}, for the sake of absolute
13.46 + * portability of Java code. However, subclasses of class {@code Random}
13.47 + * are permitted to use other algorithms, so long as they adhere to the
13.48 + * general contracts for all the methods.
13.49 + * <p>
13.50 + * The algorithms implemented by class {@code Random} use a
13.51 + * {@code protected} utility method that on each invocation can supply
13.52 + * up to 32 pseudorandomly generated bits.
13.53 + * <p>
13.54 + * Many applications will find the method {@link Math#random} simpler to use.
13.55 + *
13.56 + * <p>Instances of {@code java.util.Random} are threadsafe.
13.57 + * However, the concurrent use of the same {@code java.util.Random}
13.58 + * instance across threads may encounter contention and consequent
13.59 + * poor performance. Consider instead using
13.60 + * {@link java.util.concurrent.ThreadLocalRandom} in multithreaded
13.61 + * designs.
13.62 + *
13.63 + * <p>Instances of {@code java.util.Random} are not cryptographically
13.64 + * secure. Consider instead using {@link java.security.SecureRandom} to
13.65 + * get a cryptographically secure pseudo-random number generator for use
13.66 + * by security-sensitive applications.
13.67 + *
13.68 + * @author Frank Yellin
13.69 + * @since 1.0
13.70 + */
13.71 +public
13.72 +class Random implements java.io.Serializable {
13.73 + /** use serialVersionUID from JDK 1.1 for interoperability */
13.74 + static final long serialVersionUID = 3905348978240129619L;
13.75 +
13.76 + /**
13.77 + * The internal state associated with this pseudorandom number generator.
13.78 + * (The specs for the methods in this class describe the ongoing
13.79 + * computation of this value.)
13.80 + */
13.81 + private final AtomicLong seed;
13.82 +
13.83 + private static final long multiplier = 0x5DEECE66DL;
13.84 + private static final long addend = 0xBL;
13.85 + private static final long mask = (1L << 48) - 1;
13.86 +
13.87 + /**
13.88 + * Creates a new random number generator. This constructor sets
13.89 + * the seed of the random number generator to a value very likely
13.90 + * to be distinct from any other invocation of this constructor.
13.91 + */
13.92 + public Random() {
13.93 + this(seedUniquifier() ^ System.nanoTime());
13.94 + }
13.95 +
13.96 + private static long seedUniquifier() {
13.97 + // L'Ecuyer, "Tables of Linear Congruential Generators of
13.98 + // Different Sizes and Good Lattice Structure", 1999
13.99 + for (;;) {
13.100 + long current = seedUniquifier.get();
13.101 + long next = current * 181783497276652981L;
13.102 + if (seedUniquifier.compareAndSet(current, next))
13.103 + return next;
13.104 + }
13.105 + }
13.106 +
13.107 + private static final AtomicLong seedUniquifier
13.108 + = new AtomicLong(8682522807148012L);
13.109 +
13.110 + /**
13.111 + * Creates a new random number generator using a single {@code long} seed.
13.112 + * The seed is the initial value of the internal state of the pseudorandom
13.113 + * number generator which is maintained by method {@link #next}.
13.114 + *
13.115 + * <p>The invocation {@code new Random(seed)} is equivalent to:
13.116 + * <pre> {@code
13.117 + * Random rnd = new Random();
13.118 + * rnd.setSeed(seed);}</pre>
13.119 + *
13.120 + * @param seed the initial seed
13.121 + * @see #setSeed(long)
13.122 + */
13.123 + public Random(long seed) {
13.124 + this.seed = new AtomicLong(initialScramble(seed));
13.125 + }
13.126 +
13.127 + private static long initialScramble(long seed) {
13.128 + return (seed ^ multiplier) & mask;
13.129 + }
13.130 +
13.131 + /**
13.132 + * Sets the seed of this random number generator using a single
13.133 + * {@code long} seed. The general contract of {@code setSeed} is
13.134 + * that it alters the state of this random number generator object
13.135 + * so as to be in exactly the same state as if it had just been
13.136 + * created with the argument {@code seed} as a seed. The method
13.137 + * {@code setSeed} is implemented by class {@code Random} by
13.138 + * atomically updating the seed to
13.139 + * <pre>{@code (seed ^ 0x5DEECE66DL) & ((1L << 48) - 1)}</pre>
13.140 + * and clearing the {@code haveNextNextGaussian} flag used by {@link
13.141 + * #nextGaussian}.
13.142 + *
13.143 + * <p>The implementation of {@code setSeed} by class {@code Random}
13.144 + * happens to use only 48 bits of the given seed. In general, however,
13.145 + * an overriding method may use all 64 bits of the {@code long}
13.146 + * argument as a seed value.
13.147 + *
13.148 + * @param seed the initial seed
13.149 + */
13.150 + synchronized public void setSeed(long seed) {
13.151 + this.seed.set(initialScramble(seed));
13.152 + haveNextNextGaussian = false;
13.153 + }
13.154 +
13.155 + /**
13.156 + * Generates the next pseudorandom number. Subclasses should
13.157 + * override this, as this is used by all other methods.
13.158 + *
13.159 + * <p>The general contract of {@code next} is that it returns an
13.160 + * {@code int} value and if the argument {@code bits} is between
13.161 + * {@code 1} and {@code 32} (inclusive), then that many low-order
13.162 + * bits of the returned value will be (approximately) independently
13.163 + * chosen bit values, each of which is (approximately) equally
13.164 + * likely to be {@code 0} or {@code 1}. The method {@code next} is
13.165 + * implemented by class {@code Random} by atomically updating the seed to
13.166 + * <pre>{@code (seed * 0x5DEECE66DL + 0xBL) & ((1L << 48) - 1)}</pre>
13.167 + * and returning
13.168 + * <pre>{@code (int)(seed >>> (48 - bits))}.</pre>
13.169 + *
13.170 + * This is a linear congruential pseudorandom number generator, as
13.171 + * defined by D. H. Lehmer and described by Donald E. Knuth in
13.172 + * <i>The Art of Computer Programming,</i> Volume 3:
13.173 + * <i>Seminumerical Algorithms</i>, section 3.2.1.
13.174 + *
13.175 + * @param bits random bits
13.176 + * @return the next pseudorandom value from this random number
13.177 + * generator's sequence
13.178 + * @since 1.1
13.179 + */
13.180 + protected int next(int bits) {
13.181 + long oldseed, nextseed;
13.182 + AtomicLong seed = this.seed;
13.183 + do {
13.184 + oldseed = seed.get();
13.185 + nextseed = (oldseed * multiplier + addend) & mask;
13.186 + } while (!seed.compareAndSet(oldseed, nextseed));
13.187 + return (int)(nextseed >>> (48 - bits));
13.188 + }
13.189 +
13.190 + /**
13.191 + * Generates random bytes and places them into a user-supplied
13.192 + * byte array. The number of random bytes produced is equal to
13.193 + * the length of the byte array.
13.194 + *
13.195 + * <p>The method {@code nextBytes} is implemented by class {@code Random}
13.196 + * as if by:
13.197 + * <pre> {@code
13.198 + * public void nextBytes(byte[] bytes) {
13.199 + * for (int i = 0; i < bytes.length; )
13.200 + * for (int rnd = nextInt(), n = Math.min(bytes.length - i, 4);
13.201 + * n-- > 0; rnd >>= 8)
13.202 + * bytes[i++] = (byte)rnd;
13.203 + * }}</pre>
13.204 + *
13.205 + * @param bytes the byte array to fill with random bytes
13.206 + * @throws NullPointerException if the byte array is null
13.207 + * @since 1.1
13.208 + */
13.209 + public void nextBytes(byte[] bytes) {
13.210 + for (int i = 0, len = bytes.length; i < len; )
13.211 + for (int rnd = nextInt(),
13.212 + n = Math.min(len - i, Integer.SIZE/Byte.SIZE);
13.213 + n-- > 0; rnd >>= Byte.SIZE)
13.214 + bytes[i++] = (byte)rnd;
13.215 + }
13.216 +
13.217 + /**
13.218 + * Returns the next pseudorandom, uniformly distributed {@code int}
13.219 + * value from this random number generator's sequence. The general
13.220 + * contract of {@code nextInt} is that one {@code int} value is
13.221 + * pseudorandomly generated and returned. All 2<font size="-1"><sup>32
13.222 + * </sup></font> possible {@code int} values are produced with
13.223 + * (approximately) equal probability.
13.224 + *
13.225 + * <p>The method {@code nextInt} is implemented by class {@code Random}
13.226 + * as if by:
13.227 + * <pre> {@code
13.228 + * public int nextInt() {
13.229 + * return next(32);
13.230 + * }}</pre>
13.231 + *
13.232 + * @return the next pseudorandom, uniformly distributed {@code int}
13.233 + * value from this random number generator's sequence
13.234 + */
13.235 + public int nextInt() {
13.236 + return next(32);
13.237 + }
13.238 +
13.239 + /**
13.240 + * Returns a pseudorandom, uniformly distributed {@code int} value
13.241 + * between 0 (inclusive) and the specified value (exclusive), drawn from
13.242 + * this random number generator's sequence. The general contract of
13.243 + * {@code nextInt} is that one {@code int} value in the specified range
13.244 + * is pseudorandomly generated and returned. All {@code n} possible
13.245 + * {@code int} values are produced with (approximately) equal
13.246 + * probability. The method {@code nextInt(int n)} is implemented by
13.247 + * class {@code Random} as if by:
13.248 + * <pre> {@code
13.249 + * public int nextInt(int n) {
13.250 + * if (n <= 0)
13.251 + * throw new IllegalArgumentException("n must be positive");
13.252 + *
13.253 + * if ((n & -n) == n) // i.e., n is a power of 2
13.254 + * return (int)((n * (long)next(31)) >> 31);
13.255 + *
13.256 + * int bits, val;
13.257 + * do {
13.258 + * bits = next(31);
13.259 + * val = bits % n;
13.260 + * } while (bits - val + (n-1) < 0);
13.261 + * return val;
13.262 + * }}</pre>
13.263 + *
13.264 + * <p>The hedge "approximately" is used in the foregoing description only
13.265 + * because the next method is only approximately an unbiased source of
13.266 + * independently chosen bits. If it were a perfect source of randomly
13.267 + * chosen bits, then the algorithm shown would choose {@code int}
13.268 + * values from the stated range with perfect uniformity.
13.269 + * <p>
13.270 + * The algorithm is slightly tricky. It rejects values that would result
13.271 + * in an uneven distribution (due to the fact that 2^31 is not divisible
13.272 + * by n). The probability of a value being rejected depends on n. The
13.273 + * worst case is n=2^30+1, for which the probability of a reject is 1/2,
13.274 + * and the expected number of iterations before the loop terminates is 2.
13.275 + * <p>
13.276 + * The algorithm treats the case where n is a power of two specially: it
13.277 + * returns the correct number of high-order bits from the underlying
13.278 + * pseudo-random number generator. In the absence of special treatment,
13.279 + * the correct number of <i>low-order</i> bits would be returned. Linear
13.280 + * congruential pseudo-random number generators such as the one
13.281 + * implemented by this class are known to have short periods in the
13.282 + * sequence of values of their low-order bits. Thus, this special case
13.283 + * greatly increases the length of the sequence of values returned by
13.284 + * successive calls to this method if n is a small power of two.
13.285 + *
13.286 + * @param n the bound on the random number to be returned. Must be
13.287 + * positive.
13.288 + * @return the next pseudorandom, uniformly distributed {@code int}
13.289 + * value between {@code 0} (inclusive) and {@code n} (exclusive)
13.290 + * from this random number generator's sequence
13.291 + * @throws IllegalArgumentException if n is not positive
13.292 + * @since 1.2
13.293 + */
13.294 +
13.295 + public int nextInt(int n) {
13.296 + if (n <= 0)
13.297 + throw new IllegalArgumentException("n must be positive");
13.298 +
13.299 + if ((n & -n) == n) // i.e., n is a power of 2
13.300 + return (int)((n * (long)next(31)) >> 31);
13.301 +
13.302 + int bits, val;
13.303 + do {
13.304 + bits = next(31);
13.305 + val = bits % n;
13.306 + } while (bits - val + (n-1) < 0);
13.307 + return val;
13.308 + }
13.309 +
13.310 + /**
13.311 + * Returns the next pseudorandom, uniformly distributed {@code long}
13.312 + * value from this random number generator's sequence. The general
13.313 + * contract of {@code nextLong} is that one {@code long} value is
13.314 + * pseudorandomly generated and returned.
13.315 + *
13.316 + * <p>The method {@code nextLong} is implemented by class {@code Random}
13.317 + * as if by:
13.318 + * <pre> {@code
13.319 + * public long nextLong() {
13.320 + * return ((long)next(32) << 32) + next(32);
13.321 + * }}</pre>
13.322 + *
13.323 + * Because class {@code Random} uses a seed with only 48 bits,
13.324 + * this algorithm will not return all possible {@code long} values.
13.325 + *
13.326 + * @return the next pseudorandom, uniformly distributed {@code long}
13.327 + * value from this random number generator's sequence
13.328 + */
13.329 + public long nextLong() {
13.330 + // it's okay that the bottom word remains signed.
13.331 + return ((long)(next(32)) << 32) + next(32);
13.332 + }
13.333 +
13.334 + /**
13.335 + * Returns the next pseudorandom, uniformly distributed
13.336 + * {@code boolean} value from this random number generator's
13.337 + * sequence. The general contract of {@code nextBoolean} is that one
13.338 + * {@code boolean} value is pseudorandomly generated and returned. The
13.339 + * values {@code true} and {@code false} are produced with
13.340 + * (approximately) equal probability.
13.341 + *
13.342 + * <p>The method {@code nextBoolean} is implemented by class {@code Random}
13.343 + * as if by:
13.344 + * <pre> {@code
13.345 + * public boolean nextBoolean() {
13.346 + * return next(1) != 0;
13.347 + * }}</pre>
13.348 + *
13.349 + * @return the next pseudorandom, uniformly distributed
13.350 + * {@code boolean} value from this random number generator's
13.351 + * sequence
13.352 + * @since 1.2
13.353 + */
13.354 + public boolean nextBoolean() {
13.355 + return next(1) != 0;
13.356 + }
13.357 +
13.358 + /**
13.359 + * Returns the next pseudorandom, uniformly distributed {@code float}
13.360 + * value between {@code 0.0} and {@code 1.0} from this random
13.361 + * number generator's sequence.
13.362 + *
13.363 + * <p>The general contract of {@code nextFloat} is that one
13.364 + * {@code float} value, chosen (approximately) uniformly from the
13.365 + * range {@code 0.0f} (inclusive) to {@code 1.0f} (exclusive), is
13.366 + * pseudorandomly generated and returned. All 2<font
13.367 + * size="-1"><sup>24</sup></font> possible {@code float} values
13.368 + * of the form <i>m x </i>2<font
13.369 + * size="-1"><sup>-24</sup></font>, where <i>m</i> is a positive
13.370 + * integer less than 2<font size="-1"><sup>24</sup> </font>, are
13.371 + * produced with (approximately) equal probability.
13.372 + *
13.373 + * <p>The method {@code nextFloat} is implemented by class {@code Random}
13.374 + * as if by:
13.375 + * <pre> {@code
13.376 + * public float nextFloat() {
13.377 + * return next(24) / ((float)(1 << 24));
13.378 + * }}</pre>
13.379 + *
13.380 + * <p>The hedge "approximately" is used in the foregoing description only
13.381 + * because the next method is only approximately an unbiased source of
13.382 + * independently chosen bits. If it were a perfect source of randomly
13.383 + * chosen bits, then the algorithm shown would choose {@code float}
13.384 + * values from the stated range with perfect uniformity.<p>
13.385 + * [In early versions of Java, the result was incorrectly calculated as:
13.386 + * <pre> {@code
13.387 + * return next(30) / ((float)(1 << 30));}</pre>
13.388 + * This might seem to be equivalent, if not better, but in fact it
13.389 + * introduced a slight nonuniformity because of the bias in the rounding
13.390 + * of floating-point numbers: it was slightly more likely that the
13.391 + * low-order bit of the significand would be 0 than that it would be 1.]
13.392 + *
13.393 + * @return the next pseudorandom, uniformly distributed {@code float}
13.394 + * value between {@code 0.0} and {@code 1.0} from this
13.395 + * random number generator's sequence
13.396 + */
13.397 + public float nextFloat() {
13.398 + return next(24) / ((float)(1 << 24));
13.399 + }
13.400 +
13.401 + /**
13.402 + * Returns the next pseudorandom, uniformly distributed
13.403 + * {@code double} value between {@code 0.0} and
13.404 + * {@code 1.0} from this random number generator's sequence.
13.405 + *
13.406 + * <p>The general contract of {@code nextDouble} is that one
13.407 + * {@code double} value, chosen (approximately) uniformly from the
13.408 + * range {@code 0.0d} (inclusive) to {@code 1.0d} (exclusive), is
13.409 + * pseudorandomly generated and returned.
13.410 + *
13.411 + * <p>The method {@code nextDouble} is implemented by class {@code Random}
13.412 + * as if by:
13.413 + * <pre> {@code
13.414 + * public double nextDouble() {
13.415 + * return (((long)next(26) << 27) + next(27))
13.416 + * / (double)(1L << 53);
13.417 + * }}</pre>
13.418 + *
13.419 + * <p>The hedge "approximately" is used in the foregoing description only
13.420 + * because the {@code next} method is only approximately an unbiased
13.421 + * source of independently chosen bits. If it were a perfect source of
13.422 + * randomly chosen bits, then the algorithm shown would choose
13.423 + * {@code double} values from the stated range with perfect uniformity.
13.424 + * <p>[In early versions of Java, the result was incorrectly calculated as:
13.425 + * <pre> {@code
13.426 + * return (((long)next(27) << 27) + next(27))
13.427 + * / (double)(1L << 54);}</pre>
13.428 + * This might seem to be equivalent, if not better, but in fact it
13.429 + * introduced a large nonuniformity because of the bias in the rounding
13.430 + * of floating-point numbers: it was three times as likely that the
13.431 + * low-order bit of the significand would be 0 than that it would be 1!
13.432 + * This nonuniformity probably doesn't matter much in practice, but we
13.433 + * strive for perfection.]
13.434 + *
13.435 + * @return the next pseudorandom, uniformly distributed {@code double}
13.436 + * value between {@code 0.0} and {@code 1.0} from this
13.437 + * random number generator's sequence
13.438 + * @see Math#random
13.439 + */
13.440 + public double nextDouble() {
13.441 + return (((long)(next(26)) << 27) + next(27))
13.442 + / (double)(1L << 53);
13.443 + }
13.444 +
13.445 + private double nextNextGaussian;
13.446 + private boolean haveNextNextGaussian = false;
13.447 +
13.448 + /**
13.449 + * Returns the next pseudorandom, Gaussian ("normally") distributed
13.450 + * {@code double} value with mean {@code 0.0} and standard
13.451 + * deviation {@code 1.0} from this random number generator's sequence.
13.452 + * <p>
13.453 + * The general contract of {@code nextGaussian} is that one
13.454 + * {@code double} value, chosen from (approximately) the usual
13.455 + * normal distribution with mean {@code 0.0} and standard deviation
13.456 + * {@code 1.0}, is pseudorandomly generated and returned.
13.457 + *
13.458 + * <p>The method {@code nextGaussian} is implemented by class
13.459 + * {@code Random} as if by a threadsafe version of the following:
13.460 + * <pre> {@code
13.461 + * private double nextNextGaussian;
13.462 + * private boolean haveNextNextGaussian = false;
13.463 + *
13.464 + * public double nextGaussian() {
13.465 + * if (haveNextNextGaussian) {
13.466 + * haveNextNextGaussian = false;
13.467 + * return nextNextGaussian;
13.468 + * } else {
13.469 + * double v1, v2, s;
13.470 + * do {
13.471 + * v1 = 2 * nextDouble() - 1; // between -1.0 and 1.0
13.472 + * v2 = 2 * nextDouble() - 1; // between -1.0 and 1.0
13.473 + * s = v1 * v1 + v2 * v2;
13.474 + * } while (s >= 1 || s == 0);
13.475 + * double multiplier = StrictMath.sqrt(-2 * StrictMath.log(s)/s);
13.476 + * nextNextGaussian = v2 * multiplier;
13.477 + * haveNextNextGaussian = true;
13.478 + * return v1 * multiplier;
13.479 + * }
13.480 + * }}</pre>
13.481 + * This uses the <i>polar method</i> of G. E. P. Box, M. E. Muller, and
13.482 + * G. Marsaglia, as described by Donald E. Knuth in <i>The Art of
13.483 + * Computer Programming</i>, Volume 3: <i>Seminumerical Algorithms</i>,
13.484 + * section 3.4.1, subsection C, algorithm P. Note that it generates two
13.485 + * independent values at the cost of only one call to {@code StrictMath.log}
13.486 + * and one call to {@code StrictMath.sqrt}.
13.487 + *
13.488 + * @return the next pseudorandom, Gaussian ("normally") distributed
13.489 + * {@code double} value with mean {@code 0.0} and
13.490 + * standard deviation {@code 1.0} from this random number
13.491 + * generator's sequence
13.492 + */
13.493 + synchronized public double nextGaussian() {
13.494 + // See Knuth, ACP, Section 3.4.1 Algorithm C.
13.495 + if (haveNextNextGaussian) {
13.496 + haveNextNextGaussian = false;
13.497 + return nextNextGaussian;
13.498 + } else {
13.499 + double v1, v2, s;
13.500 + do {
13.501 + v1 = 2 * nextDouble() - 1; // between -1 and 1
13.502 + v2 = 2 * nextDouble() - 1; // between -1 and 1
13.503 + s = v1 * v1 + v2 * v2;
13.504 + } while (s >= 1 || s == 0);
13.505 + double multiplier = StrictMath.sqrt(-2 * StrictMath.log(s)/s);
13.506 + nextNextGaussian = v2 * multiplier;
13.507 + haveNextNextGaussian = true;
13.508 + return v1 * multiplier;
13.509 + }
13.510 + }
13.511 +
13.512 + /**
13.513 + * Serializable fields for Random.
13.514 + *
13.515 + * @serialField seed long
13.516 + * seed for random computations
13.517 + * @serialField nextNextGaussian double
13.518 + * next Gaussian to be returned
13.519 + * @serialField haveNextNextGaussian boolean
13.520 + * nextNextGaussian is valid
13.521 + */
13.522 + private static final ObjectStreamField[] serialPersistentFields = {
13.523 + new ObjectStreamField("seed", Long.TYPE),
13.524 + new ObjectStreamField("nextNextGaussian", Double.TYPE),
13.525 + new ObjectStreamField("haveNextNextGaussian", Boolean.TYPE)
13.526 + };
13.527 +
13.528 + /**
13.529 + * Reconstitute the {@code Random} instance from a stream (that is,
13.530 + * deserialize it).
13.531 + */
13.532 + private void readObject(java.io.ObjectInputStream s)
13.533 + throws java.io.IOException, ClassNotFoundException {
13.534 +
13.535 + ObjectInputStream.GetField fields = s.readFields();
13.536 +
13.537 + // The seed is read in as {@code long} for
13.538 + // historical reasons, but it is converted to an AtomicLong.
13.539 + long seedVal = fields.get("seed", -1L);
13.540 + if (seedVal < 0)
13.541 + throw new java.io.StreamCorruptedException(
13.542 + "Random: invalid seed");
13.543 + resetSeed(seedVal);
13.544 + nextNextGaussian = fields.get("nextNextGaussian", 0.0);
13.545 + haveNextNextGaussian = fields.get("haveNextNextGaussian", false);
13.546 + }
13.547 +
13.548 + /**
13.549 + * Save the {@code Random} instance to a stream.
13.550 + */
13.551 + synchronized private void writeObject(ObjectOutputStream s)
13.552 + throws IOException {
13.553 +
13.554 + // set the values of the Serializable fields
13.555 + ObjectOutputStream.PutField fields = s.putFields();
13.556 +
13.557 + // The seed is serialized as a long for historical reasons.
13.558 + fields.put("seed", seed.get());
13.559 + fields.put("nextNextGaussian", nextNextGaussian);
13.560 + fields.put("haveNextNextGaussian", haveNextNextGaussian);
13.561 +
13.562 + // save them
13.563 + s.writeFields();
13.564 + }
13.565 +
13.566 + // Support for resetting seed while deserializing
13.567 + private static final Unsafe unsafe = Unsafe.getUnsafe();
13.568 + private static final long seedOffset;
13.569 + static {
13.570 + try {
13.571 + seedOffset = unsafe.objectFieldOffset
13.572 + (Random.class.getDeclaredField("seed"));
13.573 + } catch (Exception ex) { throw new Error(ex); }
13.574 + }
13.575 + private void resetSeed(long seedVal) {
13.576 + unsafe.putObjectVolatile(this, seedOffset, new AtomicLong(seedVal));
13.577 + }
13.578 +}
14.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
14.2 +++ b/emul/compact/src/main/java/java/util/SortedMap.java Mon Jan 28 13:28:02 2013 +0100
14.3 @@ -0,0 +1,284 @@
14.4 +/*
14.5 + * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved.
14.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
14.7 + *
14.8 + * This code is free software; you can redistribute it and/or modify it
14.9 + * under the terms of the GNU General Public License version 2 only, as
14.10 + * published by the Free Software Foundation. Oracle designates this
14.11 + * particular file as subject to the "Classpath" exception as provided
14.12 + * by Oracle in the LICENSE file that accompanied this code.
14.13 + *
14.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
14.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14.17 + * version 2 for more details (a copy is included in the LICENSE file that
14.18 + * accompanied this code).
14.19 + *
14.20 + * You should have received a copy of the GNU General Public License version
14.21 + * 2 along with this work; if not, write to the Free Software Foundation,
14.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
14.23 + *
14.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
14.25 + * or visit www.oracle.com if you need additional information or have any
14.26 + * questions.
14.27 + */
14.28 +
14.29 +package java.util;
14.30 +
14.31 +/**
14.32 + * A {@link Map} that further provides a <em>total ordering</em> on its keys.
14.33 + * The map is ordered according to the {@linkplain Comparable natural
14.34 + * ordering} of its keys, or by a {@link Comparator} typically
14.35 + * provided at sorted map creation time. This order is reflected when
14.36 + * iterating over the sorted map's collection views (returned by the
14.37 + * {@code entrySet}, {@code keySet} and {@code values} methods).
14.38 + * Several additional operations are provided to take advantage of the
14.39 + * ordering. (This interface is the map analogue of {@link SortedSet}.)
14.40 + *
14.41 + * <p>All keys inserted into a sorted map must implement the {@code Comparable}
14.42 + * interface (or be accepted by the specified comparator). Furthermore, all
14.43 + * such keys must be <em>mutually comparable</em>: {@code k1.compareTo(k2)} (or
14.44 + * {@code comparator.compare(k1, k2)}) must not throw a
14.45 + * {@code ClassCastException} for any keys {@code k1} and {@code k2} in
14.46 + * the sorted map. Attempts to violate this restriction will cause the
14.47 + * offending method or constructor invocation to throw a
14.48 + * {@code ClassCastException}.
14.49 + *
14.50 + * <p>Note that the ordering maintained by a sorted map (whether or not an
14.51 + * explicit comparator is provided) must be <em>consistent with equals</em> if
14.52 + * the sorted map is to correctly implement the {@code Map} interface. (See
14.53 + * the {@code Comparable} interface or {@code Comparator} interface for a
14.54 + * precise definition of <em>consistent with equals</em>.) This is so because
14.55 + * the {@code Map} interface is defined in terms of the {@code equals}
14.56 + * operation, but a sorted map performs all key comparisons using its
14.57 + * {@code compareTo} (or {@code compare}) method, so two keys that are
14.58 + * deemed equal by this method are, from the standpoint of the sorted map,
14.59 + * equal. The behavior of a tree map <em>is</em> well-defined even if its
14.60 + * ordering is inconsistent with equals; it just fails to obey the general
14.61 + * contract of the {@code Map} interface.
14.62 + *
14.63 + * <p>All general-purpose sorted map implementation classes should provide four
14.64 + * "standard" constructors. It is not possible to enforce this recommendation
14.65 + * though as required constructors cannot be specified by interfaces. The
14.66 + * expected "standard" constructors for all sorted map implementations are:
14.67 + * <ol>
14.68 + * <li>A void (no arguments) constructor, which creates an empty sorted map
14.69 + * sorted according to the natural ordering of its keys.</li>
14.70 + * <li>A constructor with a single argument of type {@code Comparator}, which
14.71 + * creates an empty sorted map sorted according to the specified comparator.</li>
14.72 + * <li>A constructor with a single argument of type {@code Map}, which creates
14.73 + * a new map with the same key-value mappings as its argument, sorted
14.74 + * according to the keys' natural ordering.</li>
14.75 + * <li>A constructor with a single argument of type {@code SortedMap}, which
14.76 + * creates a new sorted map with the same key-value mappings and the same
14.77 + * ordering as the input sorted map.</li>
14.78 + * </ol>
14.79 + *
14.80 + * <p><strong>Note</strong>: several methods return submaps with restricted key
14.81 + * ranges. Such ranges are <em>half-open</em>, that is, they include their low
14.82 + * endpoint but not their high endpoint (where applicable). If you need a
14.83 + * <em>closed range</em> (which includes both endpoints), and the key type
14.84 + * allows for calculation of the successor of a given key, merely request
14.85 + * the subrange from {@code lowEndpoint} to
14.86 + * {@code successor(highEndpoint)}. For example, suppose that {@code m}
14.87 + * is a map whose keys are strings. The following idiom obtains a view
14.88 + * containing all of the key-value mappings in {@code m} whose keys are
14.89 + * between {@code low} and {@code high}, inclusive:<pre>
14.90 + * SortedMap<String, V> sub = m.subMap(low, high+"\0");</pre>
14.91 + *
14.92 + * A similar technique can be used to generate an <em>open range</em>
14.93 + * (which contains neither endpoint). The following idiom obtains a
14.94 + * view containing all of the key-value mappings in {@code m} whose keys
14.95 + * are between {@code low} and {@code high}, exclusive:<pre>
14.96 + * SortedMap<String, V> sub = m.subMap(low+"\0", high);</pre>
14.97 + *
14.98 + * <p>This interface is a member of the
14.99 + * <a href="{@docRoot}/../technotes/guides/collections/index.html">
14.100 + * Java Collections Framework</a>.
14.101 + *
14.102 + * @param <K> the type of keys maintained by this map
14.103 + * @param <V> the type of mapped values
14.104 + *
14.105 + * @author Josh Bloch
14.106 + * @see Map
14.107 + * @see TreeMap
14.108 + * @see SortedSet
14.109 + * @see Comparator
14.110 + * @see Comparable
14.111 + * @see Collection
14.112 + * @see ClassCastException
14.113 + * @since 1.2
14.114 + */
14.115 +
14.116 +public interface SortedMap<K,V> extends Map<K,V> {
14.117 + /**
14.118 + * Returns the comparator used to order the keys in this map, or
14.119 + * {@code null} if this map uses the {@linkplain Comparable
14.120 + * natural ordering} of its keys.
14.121 + *
14.122 + * @return the comparator used to order the keys in this map,
14.123 + * or {@code null} if this map uses the natural ordering
14.124 + * of its keys
14.125 + */
14.126 + Comparator<? super K> comparator();
14.127 +
14.128 + /**
14.129 + * Returns a view of the portion of this map whose keys range from
14.130 + * {@code fromKey}, inclusive, to {@code toKey}, exclusive. (If
14.131 + * {@code fromKey} and {@code toKey} are equal, the returned map
14.132 + * is empty.) The returned map is backed by this map, so changes
14.133 + * in the returned map are reflected in this map, and vice-versa.
14.134 + * The returned map supports all optional map operations that this
14.135 + * map supports.
14.136 + *
14.137 + * <p>The returned map will throw an {@code IllegalArgumentException}
14.138 + * on an attempt to insert a key outside its range.
14.139 + *
14.140 + * @param fromKey low endpoint (inclusive) of the keys in the returned map
14.141 + * @param toKey high endpoint (exclusive) of the keys in the returned map
14.142 + * @return a view of the portion of this map whose keys range from
14.143 + * {@code fromKey}, inclusive, to {@code toKey}, exclusive
14.144 + * @throws ClassCastException if {@code fromKey} and {@code toKey}
14.145 + * cannot be compared to one another using this map's comparator
14.146 + * (or, if the map has no comparator, using natural ordering).
14.147 + * Implementations may, but are not required to, throw this
14.148 + * exception if {@code fromKey} or {@code toKey}
14.149 + * cannot be compared to keys currently in the map.
14.150 + * @throws NullPointerException if {@code fromKey} or {@code toKey}
14.151 + * is null and this map does not permit null keys
14.152 + * @throws IllegalArgumentException if {@code fromKey} is greater than
14.153 + * {@code toKey}; or if this map itself has a restricted
14.154 + * range, and {@code fromKey} or {@code toKey} lies
14.155 + * outside the bounds of the range
14.156 + */
14.157 + SortedMap<K,V> subMap(K fromKey, K toKey);
14.158 +
14.159 + /**
14.160 + * Returns a view of the portion of this map whose keys are
14.161 + * strictly less than {@code toKey}. The returned map is backed
14.162 + * by this map, so changes in the returned map are reflected in
14.163 + * this map, and vice-versa. The returned map supports all
14.164 + * optional map operations that this map supports.
14.165 + *
14.166 + * <p>The returned map will throw an {@code IllegalArgumentException}
14.167 + * on an attempt to insert a key outside its range.
14.168 + *
14.169 + * @param toKey high endpoint (exclusive) of the keys in the returned map
14.170 + * @return a view of the portion of this map whose keys are strictly
14.171 + * less than {@code toKey}
14.172 + * @throws ClassCastException if {@code toKey} is not compatible
14.173 + * with this map's comparator (or, if the map has no comparator,
14.174 + * if {@code toKey} does not implement {@link Comparable}).
14.175 + * Implementations may, but are not required to, throw this
14.176 + * exception if {@code toKey} cannot be compared to keys
14.177 + * currently in the map.
14.178 + * @throws NullPointerException if {@code toKey} is null and
14.179 + * this map does not permit null keys
14.180 + * @throws IllegalArgumentException if this map itself has a
14.181 + * restricted range, and {@code toKey} lies outside the
14.182 + * bounds of the range
14.183 + */
14.184 + SortedMap<K,V> headMap(K toKey);
14.185 +
14.186 + /**
14.187 + * Returns a view of the portion of this map whose keys are
14.188 + * greater than or equal to {@code fromKey}. The returned map is
14.189 + * backed by this map, so changes in the returned map are
14.190 + * reflected in this map, and vice-versa. The returned map
14.191 + * supports all optional map operations that this map supports.
14.192 + *
14.193 + * <p>The returned map will throw an {@code IllegalArgumentException}
14.194 + * on an attempt to insert a key outside its range.
14.195 + *
14.196 + * @param fromKey low endpoint (inclusive) of the keys in the returned map
14.197 + * @return a view of the portion of this map whose keys are greater
14.198 + * than or equal to {@code fromKey}
14.199 + * @throws ClassCastException if {@code fromKey} is not compatible
14.200 + * with this map's comparator (or, if the map has no comparator,
14.201 + * if {@code fromKey} does not implement {@link Comparable}).
14.202 + * Implementations may, but are not required to, throw this
14.203 + * exception if {@code fromKey} cannot be compared to keys
14.204 + * currently in the map.
14.205 + * @throws NullPointerException if {@code fromKey} is null and
14.206 + * this map does not permit null keys
14.207 + * @throws IllegalArgumentException if this map itself has a
14.208 + * restricted range, and {@code fromKey} lies outside the
14.209 + * bounds of the range
14.210 + */
14.211 + SortedMap<K,V> tailMap(K fromKey);
14.212 +
14.213 + /**
14.214 + * Returns the first (lowest) key currently in this map.
14.215 + *
14.216 + * @return the first (lowest) key currently in this map
14.217 + * @throws NoSuchElementException if this map is empty
14.218 + */
14.219 + K firstKey();
14.220 +
14.221 + /**
14.222 + * Returns the last (highest) key currently in this map.
14.223 + *
14.224 + * @return the last (highest) key currently in this map
14.225 + * @throws NoSuchElementException if this map is empty
14.226 + */
14.227 + K lastKey();
14.228 +
14.229 + /**
14.230 + * Returns a {@link Set} view of the keys contained in this map.
14.231 + * The set's iterator returns the keys in ascending order.
14.232 + * The set is backed by the map, so changes to the map are
14.233 + * reflected in the set, and vice-versa. If the map is modified
14.234 + * while an iteration over the set is in progress (except through
14.235 + * the iterator's own {@code remove} operation), the results of
14.236 + * the iteration are undefined. The set supports element removal,
14.237 + * which removes the corresponding mapping from the map, via the
14.238 + * {@code Iterator.remove}, {@code Set.remove},
14.239 + * {@code removeAll}, {@code retainAll}, and {@code clear}
14.240 + * operations. It does not support the {@code add} or {@code addAll}
14.241 + * operations.
14.242 + *
14.243 + * @return a set view of the keys contained in this map, sorted in
14.244 + * ascending order
14.245 + */
14.246 + Set<K> keySet();
14.247 +
14.248 + /**
14.249 + * Returns a {@link Collection} view of the values contained in this map.
14.250 + * The collection's iterator returns the values in ascending order
14.251 + * of the corresponding keys.
14.252 + * The collection is backed by the map, so changes to the map are
14.253 + * reflected in the collection, and vice-versa. If the map is
14.254 + * modified while an iteration over the collection is in progress
14.255 + * (except through the iterator's own {@code remove} operation),
14.256 + * the results of the iteration are undefined. The collection
14.257 + * supports element removal, which removes the corresponding
14.258 + * mapping from the map, via the {@code Iterator.remove},
14.259 + * {@code Collection.remove}, {@code removeAll},
14.260 + * {@code retainAll} and {@code clear} operations. It does not
14.261 + * support the {@code add} or {@code addAll} operations.
14.262 + *
14.263 + * @return a collection view of the values contained in this map,
14.264 + * sorted in ascending key order
14.265 + */
14.266 + Collection<V> values();
14.267 +
14.268 + /**
14.269 + * Returns a {@link Set} view of the mappings contained in this map.
14.270 + * The set's iterator returns the entries in ascending key order.
14.271 + * The set is backed by the map, so changes to the map are
14.272 + * reflected in the set, and vice-versa. If the map is modified
14.273 + * while an iteration over the set is in progress (except through
14.274 + * the iterator's own {@code remove} operation, or through the
14.275 + * {@code setValue} operation on a map entry returned by the
14.276 + * iterator) the results of the iteration are undefined. The set
14.277 + * supports element removal, which removes the corresponding
14.278 + * mapping from the map, via the {@code Iterator.remove},
14.279 + * {@code Set.remove}, {@code removeAll}, {@code retainAll} and
14.280 + * {@code clear} operations. It does not support the
14.281 + * {@code add} or {@code addAll} operations.
14.282 + *
14.283 + * @return a set view of the mappings contained in this map,
14.284 + * sorted in ascending key order
14.285 + */
14.286 + Set<Map.Entry<K, V>> entrySet();
14.287 +}
15.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
15.2 +++ b/emul/compact/src/main/java/java/util/SortedSet.java Mon Jan 28 13:28:02 2013 +0100
15.3 @@ -0,0 +1,222 @@
15.4 +/*
15.5 + * Copyright (c) 1998, 2006, Oracle and/or its affiliates. All rights reserved.
15.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
15.7 + *
15.8 + * This code is free software; you can redistribute it and/or modify it
15.9 + * under the terms of the GNU General Public License version 2 only, as
15.10 + * published by the Free Software Foundation. Oracle designates this
15.11 + * particular file as subject to the "Classpath" exception as provided
15.12 + * by Oracle in the LICENSE file that accompanied this code.
15.13 + *
15.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
15.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
15.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
15.17 + * version 2 for more details (a copy is included in the LICENSE file that
15.18 + * accompanied this code).
15.19 + *
15.20 + * You should have received a copy of the GNU General Public License version
15.21 + * 2 along with this work; if not, write to the Free Software Foundation,
15.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
15.23 + *
15.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
15.25 + * or visit www.oracle.com if you need additional information or have any
15.26 + * questions.
15.27 + */
15.28 +
15.29 +package java.util;
15.30 +
15.31 +/**
15.32 + * A {@link Set} that further provides a <i>total ordering</i> on its elements.
15.33 + * The elements are ordered using their {@linkplain Comparable natural
15.34 + * ordering}, or by a {@link Comparator} typically provided at sorted
15.35 + * set creation time. The set's iterator will traverse the set in
15.36 + * ascending element order. Several additional operations are provided
15.37 + * to take advantage of the ordering. (This interface is the set
15.38 + * analogue of {@link SortedMap}.)
15.39 + *
15.40 + * <p>All elements inserted into a sorted set must implement the <tt>Comparable</tt>
15.41 + * interface (or be accepted by the specified comparator). Furthermore, all
15.42 + * such elements must be <i>mutually comparable</i>: <tt>e1.compareTo(e2)</tt>
15.43 + * (or <tt>comparator.compare(e1, e2)</tt>) must not throw a
15.44 + * <tt>ClassCastException</tt> for any elements <tt>e1</tt> and <tt>e2</tt> in
15.45 + * the sorted set. Attempts to violate this restriction will cause the
15.46 + * offending method or constructor invocation to throw a
15.47 + * <tt>ClassCastException</tt>.
15.48 + *
15.49 + * <p>Note that the ordering maintained by a sorted set (whether or not an
15.50 + * explicit comparator is provided) must be <i>consistent with equals</i> if
15.51 + * the sorted set is to correctly implement the <tt>Set</tt> interface. (See
15.52 + * the <tt>Comparable</tt> interface or <tt>Comparator</tt> interface for a
15.53 + * precise definition of <i>consistent with equals</i>.) This is so because
15.54 + * the <tt>Set</tt> interface is defined in terms of the <tt>equals</tt>
15.55 + * operation, but a sorted set performs all element comparisons using its
15.56 + * <tt>compareTo</tt> (or <tt>compare</tt>) method, so two elements that are
15.57 + * deemed equal by this method are, from the standpoint of the sorted set,
15.58 + * equal. The behavior of a sorted set <i>is</i> well-defined even if its
15.59 + * ordering is inconsistent with equals; it just fails to obey the general
15.60 + * contract of the <tt>Set</tt> interface.
15.61 + *
15.62 + * <p>All general-purpose sorted set implementation classes should
15.63 + * provide four "standard" constructors: 1) A void (no arguments)
15.64 + * constructor, which creates an empty sorted set sorted according to
15.65 + * the natural ordering of its elements. 2) A constructor with a
15.66 + * single argument of type <tt>Comparator</tt>, which creates an empty
15.67 + * sorted set sorted according to the specified comparator. 3) A
15.68 + * constructor with a single argument of type <tt>Collection</tt>,
15.69 + * which creates a new sorted set with the same elements as its
15.70 + * argument, sorted according to the natural ordering of the elements.
15.71 + * 4) A constructor with a single argument of type <tt>SortedSet</tt>,
15.72 + * which creates a new sorted set with the same elements and the same
15.73 + * ordering as the input sorted set. There is no way to enforce this
15.74 + * recommendation, as interfaces cannot contain constructors.
15.75 + *
15.76 + * <p>Note: several methods return subsets with restricted ranges.
15.77 + * Such ranges are <i>half-open</i>, that is, they include their low
15.78 + * endpoint but not their high endpoint (where applicable).
15.79 + * If you need a <i>closed range</i> (which includes both endpoints), and
15.80 + * the element type allows for calculation of the successor of a given
15.81 + * value, merely request the subrange from <tt>lowEndpoint</tt> to
15.82 + * <tt>successor(highEndpoint)</tt>. For example, suppose that <tt>s</tt>
15.83 + * is a sorted set of strings. The following idiom obtains a view
15.84 + * containing all of the strings in <tt>s</tt> from <tt>low</tt> to
15.85 + * <tt>high</tt>, inclusive:<pre>
15.86 + * SortedSet<String> sub = s.subSet(low, high+"\0");</pre>
15.87 + *
15.88 + * A similar technique can be used to generate an <i>open range</i> (which
15.89 + * contains neither endpoint). The following idiom obtains a view
15.90 + * containing all of the Strings in <tt>s</tt> from <tt>low</tt> to
15.91 + * <tt>high</tt>, exclusive:<pre>
15.92 + * SortedSet<String> sub = s.subSet(low+"\0", high);</pre>
15.93 + *
15.94 + * <p>This interface is a member of the
15.95 + * <a href="{@docRoot}/../technotes/guides/collections/index.html">
15.96 + * Java Collections Framework</a>.
15.97 + *
15.98 + * @param <E> the type of elements maintained by this set
15.99 + *
15.100 + * @author Josh Bloch
15.101 + * @see Set
15.102 + * @see TreeSet
15.103 + * @see SortedMap
15.104 + * @see Collection
15.105 + * @see Comparable
15.106 + * @see Comparator
15.107 + * @see ClassCastException
15.108 + * @since 1.2
15.109 + */
15.110 +
15.111 +public interface SortedSet<E> extends Set<E> {
15.112 + /**
15.113 + * Returns the comparator used to order the elements in this set,
15.114 + * or <tt>null</tt> if this set uses the {@linkplain Comparable
15.115 + * natural ordering} of its elements.
15.116 + *
15.117 + * @return the comparator used to order the elements in this set,
15.118 + * or <tt>null</tt> if this set uses the natural ordering
15.119 + * of its elements
15.120 + */
15.121 + Comparator<? super E> comparator();
15.122 +
15.123 + /**
15.124 + * Returns a view of the portion of this set whose elements range
15.125 + * from <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
15.126 + * exclusive. (If <tt>fromElement</tt> and <tt>toElement</tt> are
15.127 + * equal, the returned set is empty.) The returned set is backed
15.128 + * by this set, so changes in the returned set are reflected in
15.129 + * this set, and vice-versa. The returned set supports all
15.130 + * optional set operations that this set supports.
15.131 + *
15.132 + * <p>The returned set will throw an <tt>IllegalArgumentException</tt>
15.133 + * on an attempt to insert an element outside its range.
15.134 + *
15.135 + * @param fromElement low endpoint (inclusive) of the returned set
15.136 + * @param toElement high endpoint (exclusive) of the returned set
15.137 + * @return a view of the portion of this set whose elements range from
15.138 + * <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>, exclusive
15.139 + * @throws ClassCastException if <tt>fromElement</tt> and
15.140 + * <tt>toElement</tt> cannot be compared to one another using this
15.141 + * set's comparator (or, if the set has no comparator, using
15.142 + * natural ordering). Implementations may, but are not required
15.143 + * to, throw this exception if <tt>fromElement</tt> or
15.144 + * <tt>toElement</tt> cannot be compared to elements currently in
15.145 + * the set.
15.146 + * @throws NullPointerException if <tt>fromElement</tt> or
15.147 + * <tt>toElement</tt> is null and this set does not permit null
15.148 + * elements
15.149 + * @throws IllegalArgumentException if <tt>fromElement</tt> is
15.150 + * greater than <tt>toElement</tt>; or if this set itself
15.151 + * has a restricted range, and <tt>fromElement</tt> or
15.152 + * <tt>toElement</tt> lies outside the bounds of the range
15.153 + */
15.154 + SortedSet<E> subSet(E fromElement, E toElement);
15.155 +
15.156 + /**
15.157 + * Returns a view of the portion of this set whose elements are
15.158 + * strictly less than <tt>toElement</tt>. The returned set is
15.159 + * backed by this set, so changes in the returned set are
15.160 + * reflected in this set, and vice-versa. The returned set
15.161 + * supports all optional set operations that this set supports.
15.162 + *
15.163 + * <p>The returned set will throw an <tt>IllegalArgumentException</tt>
15.164 + * on an attempt to insert an element outside its range.
15.165 + *
15.166 + * @param toElement high endpoint (exclusive) of the returned set
15.167 + * @return a view of the portion of this set whose elements are strictly
15.168 + * less than <tt>toElement</tt>
15.169 + * @throws ClassCastException if <tt>toElement</tt> is not compatible
15.170 + * with this set's comparator (or, if the set has no comparator,
15.171 + * if <tt>toElement</tt> does not implement {@link Comparable}).
15.172 + * Implementations may, but are not required to, throw this
15.173 + * exception if <tt>toElement</tt> cannot be compared to elements
15.174 + * currently in the set.
15.175 + * @throws NullPointerException if <tt>toElement</tt> is null and
15.176 + * this set does not permit null elements
15.177 + * @throws IllegalArgumentException if this set itself has a
15.178 + * restricted range, and <tt>toElement</tt> lies outside the
15.179 + * bounds of the range
15.180 + */
15.181 + SortedSet<E> headSet(E toElement);
15.182 +
15.183 + /**
15.184 + * Returns a view of the portion of this set whose elements are
15.185 + * greater than or equal to <tt>fromElement</tt>. The returned
15.186 + * set is backed by this set, so changes in the returned set are
15.187 + * reflected in this set, and vice-versa. The returned set
15.188 + * supports all optional set operations that this set supports.
15.189 + *
15.190 + * <p>The returned set will throw an <tt>IllegalArgumentException</tt>
15.191 + * on an attempt to insert an element outside its range.
15.192 + *
15.193 + * @param fromElement low endpoint (inclusive) of the returned set
15.194 + * @return a view of the portion of this set whose elements are greater
15.195 + * than or equal to <tt>fromElement</tt>
15.196 + * @throws ClassCastException if <tt>fromElement</tt> is not compatible
15.197 + * with this set's comparator (or, if the set has no comparator,
15.198 + * if <tt>fromElement</tt> does not implement {@link Comparable}).
15.199 + * Implementations may, but are not required to, throw this
15.200 + * exception if <tt>fromElement</tt> cannot be compared to elements
15.201 + * currently in the set.
15.202 + * @throws NullPointerException if <tt>fromElement</tt> is null
15.203 + * and this set does not permit null elements
15.204 + * @throws IllegalArgumentException if this set itself has a
15.205 + * restricted range, and <tt>fromElement</tt> lies outside the
15.206 + * bounds of the range
15.207 + */
15.208 + SortedSet<E> tailSet(E fromElement);
15.209 +
15.210 + /**
15.211 + * Returns the first (lowest) element currently in this set.
15.212 + *
15.213 + * @return the first (lowest) element currently in this set
15.214 + * @throws NoSuchElementException if this set is empty
15.215 + */
15.216 + E first();
15.217 +
15.218 + /**
15.219 + * Returns the last (highest) element currently in this set.
15.220 + *
15.221 + * @return the last (highest) element currently in this set
15.222 + * @throws NoSuchElementException if this set is empty
15.223 + */
15.224 + E last();
15.225 +}
16.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
16.2 +++ b/emul/compact/src/main/java/java/util/Stack.java Mon Jan 28 13:28:02 2013 +0100
16.3 @@ -0,0 +1,141 @@
16.4 +/*
16.5 + * Copyright (c) 1994, 2010, Oracle and/or its affiliates. All rights reserved.
16.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
16.7 + *
16.8 + * This code is free software; you can redistribute it and/or modify it
16.9 + * under the terms of the GNU General Public License version 2 only, as
16.10 + * published by the Free Software Foundation. Oracle designates this
16.11 + * particular file as subject to the "Classpath" exception as provided
16.12 + * by Oracle in the LICENSE file that accompanied this code.
16.13 + *
16.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
16.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
16.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
16.17 + * version 2 for more details (a copy is included in the LICENSE file that
16.18 + * accompanied this code).
16.19 + *
16.20 + * You should have received a copy of the GNU General Public License version
16.21 + * 2 along with this work; if not, write to the Free Software Foundation,
16.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
16.23 + *
16.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
16.25 + * or visit www.oracle.com if you need additional information or have any
16.26 + * questions.
16.27 + */
16.28 +
16.29 +package java.util;
16.30 +
16.31 +/**
16.32 + * The <code>Stack</code> class represents a last-in-first-out
16.33 + * (LIFO) stack of objects. It extends class <tt>Vector</tt> with five
16.34 + * operations that allow a vector to be treated as a stack. The usual
16.35 + * <tt>push</tt> and <tt>pop</tt> operations are provided, as well as a
16.36 + * method to <tt>peek</tt> at the top item on the stack, a method to test
16.37 + * for whether the stack is <tt>empty</tt>, and a method to <tt>search</tt>
16.38 + * the stack for an item and discover how far it is from the top.
16.39 + * <p>
16.40 + * When a stack is first created, it contains no items.
16.41 + *
16.42 + * <p>A more complete and consistent set of LIFO stack operations is
16.43 + * provided by the {@link Deque} interface and its implementations, which
16.44 + * should be used in preference to this class. For example:
16.45 + * <pre> {@code
16.46 + * Deque<Integer> stack = new ArrayDeque<Integer>();}</pre>
16.47 + *
16.48 + * @author Jonathan Payne
16.49 + * @since JDK1.0
16.50 + */
16.51 +public
16.52 +class Stack<E> extends Vector<E> {
16.53 + /**
16.54 + * Creates an empty Stack.
16.55 + */
16.56 + public Stack() {
16.57 + }
16.58 +
16.59 + /**
16.60 + * Pushes an item onto the top of this stack. This has exactly
16.61 + * the same effect as:
16.62 + * <blockquote><pre>
16.63 + * addElement(item)</pre></blockquote>
16.64 + *
16.65 + * @param item the item to be pushed onto this stack.
16.66 + * @return the <code>item</code> argument.
16.67 + * @see java.util.Vector#addElement
16.68 + */
16.69 + public E push(E item) {
16.70 + addElement(item);
16.71 +
16.72 + return item;
16.73 + }
16.74 +
16.75 + /**
16.76 + * Removes the object at the top of this stack and returns that
16.77 + * object as the value of this function.
16.78 + *
16.79 + * @return The object at the top of this stack (the last item
16.80 + * of the <tt>Vector</tt> object).
16.81 + * @throws EmptyStackException if this stack is empty.
16.82 + */
16.83 + public synchronized E pop() {
16.84 + E obj;
16.85 + int len = size();
16.86 +
16.87 + obj = peek();
16.88 + removeElementAt(len - 1);
16.89 +
16.90 + return obj;
16.91 + }
16.92 +
16.93 + /**
16.94 + * Looks at the object at the top of this stack without removing it
16.95 + * from the stack.
16.96 + *
16.97 + * @return the object at the top of this stack (the last item
16.98 + * of the <tt>Vector</tt> object).
16.99 + * @throws EmptyStackException if this stack is empty.
16.100 + */
16.101 + public synchronized E peek() {
16.102 + int len = size();
16.103 +
16.104 + if (len == 0)
16.105 + throw new EmptyStackException();
16.106 + return elementAt(len - 1);
16.107 + }
16.108 +
16.109 + /**
16.110 + * Tests if this stack is empty.
16.111 + *
16.112 + * @return <code>true</code> if and only if this stack contains
16.113 + * no items; <code>false</code> otherwise.
16.114 + */
16.115 + public boolean empty() {
16.116 + return size() == 0;
16.117 + }
16.118 +
16.119 + /**
16.120 + * Returns the 1-based position where an object is on this stack.
16.121 + * If the object <tt>o</tt> occurs as an item in this stack, this
16.122 + * method returns the distance from the top of the stack of the
16.123 + * occurrence nearest the top of the stack; the topmost item on the
16.124 + * stack is considered to be at distance <tt>1</tt>. The <tt>equals</tt>
16.125 + * method is used to compare <tt>o</tt> to the
16.126 + * items in this stack.
16.127 + *
16.128 + * @param o the desired object.
16.129 + * @return the 1-based position from the top of the stack where
16.130 + * the object is located; the return value <code>-1</code>
16.131 + * indicates that the object is not on the stack.
16.132 + */
16.133 + public synchronized int search(Object o) {
16.134 + int i = lastIndexOf(o);
16.135 +
16.136 + if (i >= 0) {
16.137 + return size() - i;
16.138 + }
16.139 + return -1;
16.140 + }
16.141 +
16.142 + /** use serialVersionUID from JDK 1.0.2 for interoperability */
16.143 + private static final long serialVersionUID = 1224463164541339165L;
16.144 +}
17.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
17.2 +++ b/emul/compact/src/main/java/java/util/StringTokenizer.java Mon Jan 28 13:28:02 2013 +0100
17.3 @@ -0,0 +1,431 @@
17.4 +/*
17.5 + * Copyright (c) 1994, 2004, Oracle and/or its affiliates. All rights reserved.
17.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
17.7 + *
17.8 + * This code is free software; you can redistribute it and/or modify it
17.9 + * under the terms of the GNU General Public License version 2 only, as
17.10 + * published by the Free Software Foundation. Oracle designates this
17.11 + * particular file as subject to the "Classpath" exception as provided
17.12 + * by Oracle in the LICENSE file that accompanied this code.
17.13 + *
17.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
17.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
17.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
17.17 + * version 2 for more details (a copy is included in the LICENSE file that
17.18 + * accompanied this code).
17.19 + *
17.20 + * You should have received a copy of the GNU General Public License version
17.21 + * 2 along with this work; if not, write to the Free Software Foundation,
17.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
17.23 + *
17.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
17.25 + * or visit www.oracle.com if you need additional information or have any
17.26 + * questions.
17.27 + */
17.28 +
17.29 +package java.util;
17.30 +
17.31 +import java.lang.*;
17.32 +
17.33 +/**
17.34 + * The string tokenizer class allows an application to break a
17.35 + * string into tokens. The tokenization method is much simpler than
17.36 + * the one used by the <code>StreamTokenizer</code> class. The
17.37 + * <code>StringTokenizer</code> methods do not distinguish among
17.38 + * identifiers, numbers, and quoted strings, nor do they recognize
17.39 + * and skip comments.
17.40 + * <p>
17.41 + * The set of delimiters (the characters that separate tokens) may
17.42 + * be specified either at creation time or on a per-token basis.
17.43 + * <p>
17.44 + * An instance of <code>StringTokenizer</code> behaves in one of two
17.45 + * ways, depending on whether it was created with the
17.46 + * <code>returnDelims</code> flag having the value <code>true</code>
17.47 + * or <code>false</code>:
17.48 + * <ul>
17.49 + * <li>If the flag is <code>false</code>, delimiter characters serve to
17.50 + * separate tokens. A token is a maximal sequence of consecutive
17.51 + * characters that are not delimiters.
17.52 + * <li>If the flag is <code>true</code>, delimiter characters are themselves
17.53 + * considered to be tokens. A token is thus either one delimiter
17.54 + * character, or a maximal sequence of consecutive characters that are
17.55 + * not delimiters.
17.56 + * </ul><p>
17.57 + * A <tt>StringTokenizer</tt> object internally maintains a current
17.58 + * position within the string to be tokenized. Some operations advance this
17.59 + * current position past the characters processed.<p>
17.60 + * A token is returned by taking a substring of the string that was used to
17.61 + * create the <tt>StringTokenizer</tt> object.
17.62 + * <p>
17.63 + * The following is one example of the use of the tokenizer. The code:
17.64 + * <blockquote><pre>
17.65 + * StringTokenizer st = new StringTokenizer("this is a test");
17.66 + * while (st.hasMoreTokens()) {
17.67 + * System.out.println(st.nextToken());
17.68 + * }
17.69 + * </pre></blockquote>
17.70 + * <p>
17.71 + * prints the following output:
17.72 + * <blockquote><pre>
17.73 + * this
17.74 + * is
17.75 + * a
17.76 + * test
17.77 + * </pre></blockquote>
17.78 + *
17.79 + * <p>
17.80 + * <tt>StringTokenizer</tt> is a legacy class that is retained for
17.81 + * compatibility reasons although its use is discouraged in new code. It is
17.82 + * recommended that anyone seeking this functionality use the <tt>split</tt>
17.83 + * method of <tt>String</tt> or the java.util.regex package instead.
17.84 + * <p>
17.85 + * The following example illustrates how the <tt>String.split</tt>
17.86 + * method can be used to break up a string into its basic tokens:
17.87 + * <blockquote><pre>
17.88 + * String[] result = "this is a test".split("\\s");
17.89 + * for (int x=0; x<result.length; x++)
17.90 + * System.out.println(result[x]);
17.91 + * </pre></blockquote>
17.92 + * <p>
17.93 + * prints the following output:
17.94 + * <blockquote><pre>
17.95 + * this
17.96 + * is
17.97 + * a
17.98 + * test
17.99 + * </pre></blockquote>
17.100 + *
17.101 + * @author unascribed
17.102 + * @see java.io.StreamTokenizer
17.103 + * @since JDK1.0
17.104 + */
17.105 +public
17.106 +class StringTokenizer implements Enumeration<Object> {
17.107 + private int currentPosition;
17.108 + private int newPosition;
17.109 + private int maxPosition;
17.110 + private String str;
17.111 + private String delimiters;
17.112 + private boolean retDelims;
17.113 + private boolean delimsChanged;
17.114 +
17.115 + /**
17.116 + * maxDelimCodePoint stores the value of the delimiter character with the
17.117 + * highest value. It is used to optimize the detection of delimiter
17.118 + * characters.
17.119 + *
17.120 + * It is unlikely to provide any optimization benefit in the
17.121 + * hasSurrogates case because most string characters will be
17.122 + * smaller than the limit, but we keep it so that the two code
17.123 + * paths remain similar.
17.124 + */
17.125 + private int maxDelimCodePoint;
17.126 +
17.127 + /**
17.128 + * If delimiters include any surrogates (including surrogate
17.129 + * pairs), hasSurrogates is true and the tokenizer uses the
17.130 + * different code path. This is because String.indexOf(int)
17.131 + * doesn't handle unpaired surrogates as a single character.
17.132 + */
17.133 + private boolean hasSurrogates = false;
17.134 +
17.135 + /**
17.136 + * When hasSurrogates is true, delimiters are converted to code
17.137 + * points and isDelimiter(int) is used to determine if the given
17.138 + * codepoint is a delimiter.
17.139 + */
17.140 + private int[] delimiterCodePoints;
17.141 +
17.142 + /**
17.143 + * Set maxDelimCodePoint to the highest char in the delimiter set.
17.144 + */
17.145 + private void setMaxDelimCodePoint() {
17.146 + if (delimiters == null) {
17.147 + maxDelimCodePoint = 0;
17.148 + return;
17.149 + }
17.150 +
17.151 + int m = 0;
17.152 + int c;
17.153 + int count = 0;
17.154 + for (int i = 0; i < delimiters.length(); i += Character.charCount(c)) {
17.155 + c = delimiters.charAt(i);
17.156 + if (c >= Character.MIN_HIGH_SURROGATE && c <= Character.MAX_LOW_SURROGATE) {
17.157 + c = delimiters.codePointAt(i);
17.158 + hasSurrogates = true;
17.159 + }
17.160 + if (m < c)
17.161 + m = c;
17.162 + count++;
17.163 + }
17.164 + maxDelimCodePoint = m;
17.165 +
17.166 + if (hasSurrogates) {
17.167 + delimiterCodePoints = new int[count];
17.168 + for (int i = 0, j = 0; i < count; i++, j += Character.charCount(c)) {
17.169 + c = delimiters.codePointAt(j);
17.170 + delimiterCodePoints[i] = c;
17.171 + }
17.172 + }
17.173 + }
17.174 +
17.175 + /**
17.176 + * Constructs a string tokenizer for the specified string. All
17.177 + * characters in the <code>delim</code> argument are the delimiters
17.178 + * for separating tokens.
17.179 + * <p>
17.180 + * If the <code>returnDelims</code> flag is <code>true</code>, then
17.181 + * the delimiter characters are also returned as tokens. Each
17.182 + * delimiter is returned as a string of length one. If the flag is
17.183 + * <code>false</code>, the delimiter characters are skipped and only
17.184 + * serve as separators between tokens.
17.185 + * <p>
17.186 + * Note that if <tt>delim</tt> is <tt>null</tt>, this constructor does
17.187 + * not throw an exception. However, trying to invoke other methods on the
17.188 + * resulting <tt>StringTokenizer</tt> may result in a
17.189 + * <tt>NullPointerException</tt>.
17.190 + *
17.191 + * @param str a string to be parsed.
17.192 + * @param delim the delimiters.
17.193 + * @param returnDelims flag indicating whether to return the delimiters
17.194 + * as tokens.
17.195 + * @exception NullPointerException if str is <CODE>null</CODE>
17.196 + */
17.197 + public StringTokenizer(String str, String delim, boolean returnDelims) {
17.198 + currentPosition = 0;
17.199 + newPosition = -1;
17.200 + delimsChanged = false;
17.201 + this.str = str;
17.202 + maxPosition = str.length();
17.203 + delimiters = delim;
17.204 + retDelims = returnDelims;
17.205 + setMaxDelimCodePoint();
17.206 + }
17.207 +
17.208 + /**
17.209 + * Constructs a string tokenizer for the specified string. The
17.210 + * characters in the <code>delim</code> argument are the delimiters
17.211 + * for separating tokens. Delimiter characters themselves will not
17.212 + * be treated as tokens.
17.213 + * <p>
17.214 + * Note that if <tt>delim</tt> is <tt>null</tt>, this constructor does
17.215 + * not throw an exception. However, trying to invoke other methods on the
17.216 + * resulting <tt>StringTokenizer</tt> may result in a
17.217 + * <tt>NullPointerException</tt>.
17.218 + *
17.219 + * @param str a string to be parsed.
17.220 + * @param delim the delimiters.
17.221 + * @exception NullPointerException if str is <CODE>null</CODE>
17.222 + */
17.223 + public StringTokenizer(String str, String delim) {
17.224 + this(str, delim, false);
17.225 + }
17.226 +
17.227 + /**
17.228 + * Constructs a string tokenizer for the specified string. The
17.229 + * tokenizer uses the default delimiter set, which is
17.230 + * <code>" \t\n\r\f"</code>: the space character,
17.231 + * the tab character, the newline character, the carriage-return character,
17.232 + * and the form-feed character. Delimiter characters themselves will
17.233 + * not be treated as tokens.
17.234 + *
17.235 + * @param str a string to be parsed.
17.236 + * @exception NullPointerException if str is <CODE>null</CODE>
17.237 + */
17.238 + public StringTokenizer(String str) {
17.239 + this(str, " \t\n\r\f", false);
17.240 + }
17.241 +
17.242 + /**
17.243 + * Skips delimiters starting from the specified position. If retDelims
17.244 + * is false, returns the index of the first non-delimiter character at or
17.245 + * after startPos. If retDelims is true, startPos is returned.
17.246 + */
17.247 + private int skipDelimiters(int startPos) {
17.248 + if (delimiters == null)
17.249 + throw new NullPointerException();
17.250 +
17.251 + int position = startPos;
17.252 + while (!retDelims && position < maxPosition) {
17.253 + if (!hasSurrogates) {
17.254 + char c = str.charAt(position);
17.255 + if ((c > maxDelimCodePoint) || (delimiters.indexOf(c) < 0))
17.256 + break;
17.257 + position++;
17.258 + } else {
17.259 + int c = str.codePointAt(position);
17.260 + if ((c > maxDelimCodePoint) || !isDelimiter(c)) {
17.261 + break;
17.262 + }
17.263 + position += Character.charCount(c);
17.264 + }
17.265 + }
17.266 + return position;
17.267 + }
17.268 +
17.269 + /**
17.270 + * Skips ahead from startPos and returns the index of the next delimiter
17.271 + * character encountered, or maxPosition if no such delimiter is found.
17.272 + */
17.273 + private int scanToken(int startPos) {
17.274 + int position = startPos;
17.275 + while (position < maxPosition) {
17.276 + if (!hasSurrogates) {
17.277 + char c = str.charAt(position);
17.278 + if ((c <= maxDelimCodePoint) && (delimiters.indexOf(c) >= 0))
17.279 + break;
17.280 + position++;
17.281 + } else {
17.282 + int c = str.codePointAt(position);
17.283 + if ((c <= maxDelimCodePoint) && isDelimiter(c))
17.284 + break;
17.285 + position += Character.charCount(c);
17.286 + }
17.287 + }
17.288 + if (retDelims && (startPos == position)) {
17.289 + if (!hasSurrogates) {
17.290 + char c = str.charAt(position);
17.291 + if ((c <= maxDelimCodePoint) && (delimiters.indexOf(c) >= 0))
17.292 + position++;
17.293 + } else {
17.294 + int c = str.codePointAt(position);
17.295 + if ((c <= maxDelimCodePoint) && isDelimiter(c))
17.296 + position += Character.charCount(c);
17.297 + }
17.298 + }
17.299 + return position;
17.300 + }
17.301 +
17.302 + private boolean isDelimiter(int codePoint) {
17.303 + for (int i = 0; i < delimiterCodePoints.length; i++) {
17.304 + if (delimiterCodePoints[i] == codePoint) {
17.305 + return true;
17.306 + }
17.307 + }
17.308 + return false;
17.309 + }
17.310 +
17.311 + /**
17.312 + * Tests if there are more tokens available from this tokenizer's string.
17.313 + * If this method returns <tt>true</tt>, then a subsequent call to
17.314 + * <tt>nextToken</tt> with no argument will successfully return a token.
17.315 + *
17.316 + * @return <code>true</code> if and only if there is at least one token
17.317 + * in the string after the current position; <code>false</code>
17.318 + * otherwise.
17.319 + */
17.320 + public boolean hasMoreTokens() {
17.321 + /*
17.322 + * Temporarily store this position and use it in the following
17.323 + * nextToken() method only if the delimiters haven't been changed in
17.324 + * that nextToken() invocation.
17.325 + */
17.326 + newPosition = skipDelimiters(currentPosition);
17.327 + return (newPosition < maxPosition);
17.328 + }
17.329 +
17.330 + /**
17.331 + * Returns the next token from this string tokenizer.
17.332 + *
17.333 + * @return the next token from this string tokenizer.
17.334 + * @exception NoSuchElementException if there are no more tokens in this
17.335 + * tokenizer's string.
17.336 + */
17.337 + public String nextToken() {
17.338 + /*
17.339 + * If next position already computed in hasMoreElements() and
17.340 + * delimiters have changed between the computation and this invocation,
17.341 + * then use the computed value.
17.342 + */
17.343 +
17.344 + currentPosition = (newPosition >= 0 && !delimsChanged) ?
17.345 + newPosition : skipDelimiters(currentPosition);
17.346 +
17.347 + /* Reset these anyway */
17.348 + delimsChanged = false;
17.349 + newPosition = -1;
17.350 +
17.351 + if (currentPosition >= maxPosition)
17.352 + throw new NoSuchElementException();
17.353 + int start = currentPosition;
17.354 + currentPosition = scanToken(currentPosition);
17.355 + return str.substring(start, currentPosition);
17.356 + }
17.357 +
17.358 + /**
17.359 + * Returns the next token in this string tokenizer's string. First,
17.360 + * the set of characters considered to be delimiters by this
17.361 + * <tt>StringTokenizer</tt> object is changed to be the characters in
17.362 + * the string <tt>delim</tt>. Then the next token in the string
17.363 + * after the current position is returned. The current position is
17.364 + * advanced beyond the recognized token. The new delimiter set
17.365 + * remains the default after this call.
17.366 + *
17.367 + * @param delim the new delimiters.
17.368 + * @return the next token, after switching to the new delimiter set.
17.369 + * @exception NoSuchElementException if there are no more tokens in this
17.370 + * tokenizer's string.
17.371 + * @exception NullPointerException if delim is <CODE>null</CODE>
17.372 + */
17.373 + public String nextToken(String delim) {
17.374 + delimiters = delim;
17.375 +
17.376 + /* delimiter string specified, so set the appropriate flag. */
17.377 + delimsChanged = true;
17.378 +
17.379 + setMaxDelimCodePoint();
17.380 + return nextToken();
17.381 + }
17.382 +
17.383 + /**
17.384 + * Returns the same value as the <code>hasMoreTokens</code>
17.385 + * method. It exists so that this class can implement the
17.386 + * <code>Enumeration</code> interface.
17.387 + *
17.388 + * @return <code>true</code> if there are more tokens;
17.389 + * <code>false</code> otherwise.
17.390 + * @see java.util.Enumeration
17.391 + * @see java.util.StringTokenizer#hasMoreTokens()
17.392 + */
17.393 + public boolean hasMoreElements() {
17.394 + return hasMoreTokens();
17.395 + }
17.396 +
17.397 + /**
17.398 + * Returns the same value as the <code>nextToken</code> method,
17.399 + * except that its declared return value is <code>Object</code> rather than
17.400 + * <code>String</code>. It exists so that this class can implement the
17.401 + * <code>Enumeration</code> interface.
17.402 + *
17.403 + * @return the next token in the string.
17.404 + * @exception NoSuchElementException if there are no more tokens in this
17.405 + * tokenizer's string.
17.406 + * @see java.util.Enumeration
17.407 + * @see java.util.StringTokenizer#nextToken()
17.408 + */
17.409 + public Object nextElement() {
17.410 + return nextToken();
17.411 + }
17.412 +
17.413 + /**
17.414 + * Calculates the number of times that this tokenizer's
17.415 + * <code>nextToken</code> method can be called before it generates an
17.416 + * exception. The current position is not advanced.
17.417 + *
17.418 + * @return the number of tokens remaining in the string using the current
17.419 + * delimiter set.
17.420 + * @see java.util.StringTokenizer#nextToken()
17.421 + */
17.422 + public int countTokens() {
17.423 + int count = 0;
17.424 + int currpos = currentPosition;
17.425 + while (currpos < maxPosition) {
17.426 + currpos = skipDelimiters(currpos);
17.427 + if (currpos >= maxPosition)
17.428 + break;
17.429 + currpos = scanToken(currpos);
17.430 + count++;
17.431 + }
17.432 + return count;
17.433 + }
17.434 +}
18.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
18.2 +++ b/emul/compact/src/main/java/java/util/Vector.java Mon Jan 28 13:28:02 2013 +0100
18.3 @@ -0,0 +1,1212 @@
18.4 +/*
18.5 + * Copyright (c) 1994, 2011, Oracle and/or its affiliates. All rights reserved.
18.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
18.7 + *
18.8 + * This code is free software; you can redistribute it and/or modify it
18.9 + * under the terms of the GNU General Public License version 2 only, as
18.10 + * published by the Free Software Foundation. Oracle designates this
18.11 + * particular file as subject to the "Classpath" exception as provided
18.12 + * by Oracle in the LICENSE file that accompanied this code.
18.13 + *
18.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
18.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
18.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
18.17 + * version 2 for more details (a copy is included in the LICENSE file that
18.18 + * accompanied this code).
18.19 + *
18.20 + * You should have received a copy of the GNU General Public License version
18.21 + * 2 along with this work; if not, write to the Free Software Foundation,
18.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18.23 + *
18.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
18.25 + * or visit www.oracle.com if you need additional information or have any
18.26 + * questions.
18.27 + */
18.28 +
18.29 +package java.util;
18.30 +
18.31 +/**
18.32 + * The {@code Vector} class implements a growable array of
18.33 + * objects. Like an array, it contains components that can be
18.34 + * accessed using an integer index. However, the size of a
18.35 + * {@code Vector} can grow or shrink as needed to accommodate
18.36 + * adding and removing items after the {@code Vector} has been created.
18.37 + *
18.38 + * <p>Each vector tries to optimize storage management by maintaining a
18.39 + * {@code capacity} and a {@code capacityIncrement}. The
18.40 + * {@code capacity} is always at least as large as the vector
18.41 + * size; it is usually larger because as components are added to the
18.42 + * vector, the vector's storage increases in chunks the size of
18.43 + * {@code capacityIncrement}. An application can increase the
18.44 + * capacity of a vector before inserting a large number of
18.45 + * components; this reduces the amount of incremental reallocation.
18.46 + *
18.47 + * <p><a name="fail-fast"/>
18.48 + * The iterators returned by this class's {@link #iterator() iterator} and
18.49 + * {@link #listIterator(int) listIterator} methods are <em>fail-fast</em>:
18.50 + * if the vector is structurally modified at any time after the iterator is
18.51 + * created, in any way except through the iterator's own
18.52 + * {@link ListIterator#remove() remove} or
18.53 + * {@link ListIterator#add(Object) add} methods, the iterator will throw a
18.54 + * {@link ConcurrentModificationException}. Thus, in the face of
18.55 + * concurrent modification, the iterator fails quickly and cleanly, rather
18.56 + * than risking arbitrary, non-deterministic behavior at an undetermined
18.57 + * time in the future. The {@link Enumeration Enumerations} returned by
18.58 + * the {@link #elements() elements} method are <em>not</em> fail-fast.
18.59 + *
18.60 + * <p>Note that the fail-fast behavior of an iterator cannot be guaranteed
18.61 + * as it is, generally speaking, impossible to make any hard guarantees in the
18.62 + * presence of unsynchronized concurrent modification. Fail-fast iterators
18.63 + * throw {@code ConcurrentModificationException} on a best-effort basis.
18.64 + * Therefore, it would be wrong to write a program that depended on this
18.65 + * exception for its correctness: <i>the fail-fast behavior of iterators
18.66 + * should be used only to detect bugs.</i>
18.67 + *
18.68 + * <p>As of the Java 2 platform v1.2, this class was retrofitted to
18.69 + * implement the {@link List} interface, making it a member of the
18.70 + * <a href="{@docRoot}/../technotes/guides/collections/index.html">
18.71 + * Java Collections Framework</a>. Unlike the new collection
18.72 + * implementations, {@code Vector} is synchronized. If a thread-safe
18.73 + * implementation is not needed, it is recommended to use {@link
18.74 + * ArrayList} in place of {@code Vector}.
18.75 + *
18.76 + * @author Lee Boynton
18.77 + * @author Jonathan Payne
18.78 + * @see Collection
18.79 + * @see LinkedList
18.80 + * @since JDK1.0
18.81 + */
18.82 +public class Vector<E>
18.83 + extends AbstractList<E>
18.84 + implements List<E>, RandomAccess, Cloneable, java.io.Serializable
18.85 +{
18.86 + /**
18.87 + * The array buffer into which the components of the vector are
18.88 + * stored. The capacity of the vector is the length of this array buffer,
18.89 + * and is at least large enough to contain all the vector's elements.
18.90 + *
18.91 + * <p>Any array elements following the last element in the Vector are null.
18.92 + *
18.93 + * @serial
18.94 + */
18.95 + protected Object[] elementData;
18.96 +
18.97 + /**
18.98 + * The number of valid components in this {@code Vector} object.
18.99 + * Components {@code elementData[0]} through
18.100 + * {@code elementData[elementCount-1]} are the actual items.
18.101 + *
18.102 + * @serial
18.103 + */
18.104 + protected int elementCount;
18.105 +
18.106 + /**
18.107 + * The amount by which the capacity of the vector is automatically
18.108 + * incremented when its size becomes greater than its capacity. If
18.109 + * the capacity increment is less than or equal to zero, the capacity
18.110 + * of the vector is doubled each time it needs to grow.
18.111 + *
18.112 + * @serial
18.113 + */
18.114 + protected int capacityIncrement;
18.115 +
18.116 + /** use serialVersionUID from JDK 1.0.2 for interoperability */
18.117 + private static final long serialVersionUID = -2767605614048989439L;
18.118 +
18.119 + /**
18.120 + * Constructs an empty vector with the specified initial capacity and
18.121 + * capacity increment.
18.122 + *
18.123 + * @param initialCapacity the initial capacity of the vector
18.124 + * @param capacityIncrement the amount by which the capacity is
18.125 + * increased when the vector overflows
18.126 + * @throws IllegalArgumentException if the specified initial capacity
18.127 + * is negative
18.128 + */
18.129 + public Vector(int initialCapacity, int capacityIncrement) {
18.130 + super();
18.131 + if (initialCapacity < 0)
18.132 + throw new IllegalArgumentException("Illegal Capacity: "+
18.133 + initialCapacity);
18.134 + this.elementData = new Object[initialCapacity];
18.135 + this.capacityIncrement = capacityIncrement;
18.136 + }
18.137 +
18.138 + /**
18.139 + * Constructs an empty vector with the specified initial capacity and
18.140 + * with its capacity increment equal to zero.
18.141 + *
18.142 + * @param initialCapacity the initial capacity of the vector
18.143 + * @throws IllegalArgumentException if the specified initial capacity
18.144 + * is negative
18.145 + */
18.146 + public Vector(int initialCapacity) {
18.147 + this(initialCapacity, 0);
18.148 + }
18.149 +
18.150 + /**
18.151 + * Constructs an empty vector so that its internal data array
18.152 + * has size {@code 10} and its standard capacity increment is
18.153 + * zero.
18.154 + */
18.155 + public Vector() {
18.156 + this(10);
18.157 + }
18.158 +
18.159 + /**
18.160 + * Constructs a vector containing the elements of the specified
18.161 + * collection, in the order they are returned by the collection's
18.162 + * iterator.
18.163 + *
18.164 + * @param c the collection whose elements are to be placed into this
18.165 + * vector
18.166 + * @throws NullPointerException if the specified collection is null
18.167 + * @since 1.2
18.168 + */
18.169 + public Vector(Collection<? extends E> c) {
18.170 + elementData = c.toArray();
18.171 + elementCount = elementData.length;
18.172 + // c.toArray might (incorrectly) not return Object[] (see 6260652)
18.173 + if (elementData.getClass() != Object[].class)
18.174 + elementData = Arrays.copyOf(elementData, elementCount, Object[].class);
18.175 + }
18.176 +
18.177 + /**
18.178 + * Copies the components of this vector into the specified array.
18.179 + * The item at index {@code k} in this vector is copied into
18.180 + * component {@code k} of {@code anArray}.
18.181 + *
18.182 + * @param anArray the array into which the components get copied
18.183 + * @throws NullPointerException if the given array is null
18.184 + * @throws IndexOutOfBoundsException if the specified array is not
18.185 + * large enough to hold all the components of this vector
18.186 + * @throws ArrayStoreException if a component of this vector is not of
18.187 + * a runtime type that can be stored in the specified array
18.188 + * @see #toArray(Object[])
18.189 + */
18.190 + public synchronized void copyInto(Object[] anArray) {
18.191 + System.arraycopy(elementData, 0, anArray, 0, elementCount);
18.192 + }
18.193 +
18.194 + /**
18.195 + * Trims the capacity of this vector to be the vector's current
18.196 + * size. If the capacity of this vector is larger than its current
18.197 + * size, then the capacity is changed to equal the size by replacing
18.198 + * its internal data array, kept in the field {@code elementData},
18.199 + * with a smaller one. An application can use this operation to
18.200 + * minimize the storage of a vector.
18.201 + */
18.202 + public synchronized void trimToSize() {
18.203 + modCount++;
18.204 + int oldCapacity = elementData.length;
18.205 + if (elementCount < oldCapacity) {
18.206 + elementData = Arrays.copyOf(elementData, elementCount);
18.207 + }
18.208 + }
18.209 +
18.210 + /**
18.211 + * Increases the capacity of this vector, if necessary, to ensure
18.212 + * that it can hold at least the number of components specified by
18.213 + * the minimum capacity argument.
18.214 + *
18.215 + * <p>If the current capacity of this vector is less than
18.216 + * {@code minCapacity}, then its capacity is increased by replacing its
18.217 + * internal data array, kept in the field {@code elementData}, with a
18.218 + * larger one. The size of the new data array will be the old size plus
18.219 + * {@code capacityIncrement}, unless the value of
18.220 + * {@code capacityIncrement} is less than or equal to zero, in which case
18.221 + * the new capacity will be twice the old capacity; but if this new size
18.222 + * is still smaller than {@code minCapacity}, then the new capacity will
18.223 + * be {@code minCapacity}.
18.224 + *
18.225 + * @param minCapacity the desired minimum capacity
18.226 + */
18.227 + public synchronized void ensureCapacity(int minCapacity) {
18.228 + if (minCapacity > 0) {
18.229 + modCount++;
18.230 + ensureCapacityHelper(minCapacity);
18.231 + }
18.232 + }
18.233 +
18.234 + /**
18.235 + * This implements the unsynchronized semantics of ensureCapacity.
18.236 + * Synchronized methods in this class can internally call this
18.237 + * method for ensuring capacity without incurring the cost of an
18.238 + * extra synchronization.
18.239 + *
18.240 + * @see #ensureCapacity(int)
18.241 + */
18.242 + private void ensureCapacityHelper(int minCapacity) {
18.243 + // overflow-conscious code
18.244 + if (minCapacity - elementData.length > 0)
18.245 + grow(minCapacity);
18.246 + }
18.247 +
18.248 + /**
18.249 + * The maximum size of array to allocate.
18.250 + * Some VMs reserve some header words in an array.
18.251 + * Attempts to allocate larger arrays may result in
18.252 + * OutOfMemoryError: Requested array size exceeds VM limit
18.253 + */
18.254 + private static final int MAX_ARRAY_SIZE = Integer.MAX_VALUE - 8;
18.255 +
18.256 + private void grow(int minCapacity) {
18.257 + // overflow-conscious code
18.258 + int oldCapacity = elementData.length;
18.259 + int newCapacity = oldCapacity + ((capacityIncrement > 0) ?
18.260 + capacityIncrement : oldCapacity);
18.261 + if (newCapacity - minCapacity < 0)
18.262 + newCapacity = minCapacity;
18.263 + if (newCapacity - MAX_ARRAY_SIZE > 0)
18.264 + newCapacity = hugeCapacity(minCapacity);
18.265 + elementData = Arrays.copyOf(elementData, newCapacity);
18.266 + }
18.267 +
18.268 + private static int hugeCapacity(int minCapacity) {
18.269 + if (minCapacity < 0) // overflow
18.270 + throw new OutOfMemoryError();
18.271 + return (minCapacity > MAX_ARRAY_SIZE) ?
18.272 + Integer.MAX_VALUE :
18.273 + MAX_ARRAY_SIZE;
18.274 + }
18.275 +
18.276 + /**
18.277 + * Sets the size of this vector. If the new size is greater than the
18.278 + * current size, new {@code null} items are added to the end of
18.279 + * the vector. If the new size is less than the current size, all
18.280 + * components at index {@code newSize} and greater are discarded.
18.281 + *
18.282 + * @param newSize the new size of this vector
18.283 + * @throws ArrayIndexOutOfBoundsException if the new size is negative
18.284 + */
18.285 + public synchronized void setSize(int newSize) {
18.286 + modCount++;
18.287 + if (newSize > elementCount) {
18.288 + ensureCapacityHelper(newSize);
18.289 + } else {
18.290 + for (int i = newSize ; i < elementCount ; i++) {
18.291 + elementData[i] = null;
18.292 + }
18.293 + }
18.294 + elementCount = newSize;
18.295 + }
18.296 +
18.297 + /**
18.298 + * Returns the current capacity of this vector.
18.299 + *
18.300 + * @return the current capacity (the length of its internal
18.301 + * data array, kept in the field {@code elementData}
18.302 + * of this vector)
18.303 + */
18.304 + public synchronized int capacity() {
18.305 + return elementData.length;
18.306 + }
18.307 +
18.308 + /**
18.309 + * Returns the number of components in this vector.
18.310 + *
18.311 + * @return the number of components in this vector
18.312 + */
18.313 + public synchronized int size() {
18.314 + return elementCount;
18.315 + }
18.316 +
18.317 + /**
18.318 + * Tests if this vector has no components.
18.319 + *
18.320 + * @return {@code true} if and only if this vector has
18.321 + * no components, that is, its size is zero;
18.322 + * {@code false} otherwise.
18.323 + */
18.324 + public synchronized boolean isEmpty() {
18.325 + return elementCount == 0;
18.326 + }
18.327 +
18.328 + /**
18.329 + * Returns an enumeration of the components of this vector. The
18.330 + * returned {@code Enumeration} object will generate all items in
18.331 + * this vector. The first item generated is the item at index {@code 0},
18.332 + * then the item at index {@code 1}, and so on.
18.333 + *
18.334 + * @return an enumeration of the components of this vector
18.335 + * @see Iterator
18.336 + */
18.337 + public Enumeration<E> elements() {
18.338 + return new Enumeration<E>() {
18.339 + int count = 0;
18.340 +
18.341 + public boolean hasMoreElements() {
18.342 + return count < elementCount;
18.343 + }
18.344 +
18.345 + public E nextElement() {
18.346 + synchronized (Vector.this) {
18.347 + if (count < elementCount) {
18.348 + return elementData(count++);
18.349 + }
18.350 + }
18.351 + throw new NoSuchElementException("Vector Enumeration");
18.352 + }
18.353 + };
18.354 + }
18.355 +
18.356 + /**
18.357 + * Returns {@code true} if this vector contains the specified element.
18.358 + * More formally, returns {@code true} if and only if this vector
18.359 + * contains at least one element {@code e} such that
18.360 + * <tt>(o==null ? e==null : o.equals(e))</tt>.
18.361 + *
18.362 + * @param o element whose presence in this vector is to be tested
18.363 + * @return {@code true} if this vector contains the specified element
18.364 + */
18.365 + public boolean contains(Object o) {
18.366 + return indexOf(o, 0) >= 0;
18.367 + }
18.368 +
18.369 + /**
18.370 + * Returns the index of the first occurrence of the specified element
18.371 + * in this vector, or -1 if this vector does not contain the element.
18.372 + * More formally, returns the lowest index {@code i} such that
18.373 + * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
18.374 + * or -1 if there is no such index.
18.375 + *
18.376 + * @param o element to search for
18.377 + * @return the index of the first occurrence of the specified element in
18.378 + * this vector, or -1 if this vector does not contain the element
18.379 + */
18.380 + public int indexOf(Object o) {
18.381 + return indexOf(o, 0);
18.382 + }
18.383 +
18.384 + /**
18.385 + * Returns the index of the first occurrence of the specified element in
18.386 + * this vector, searching forwards from {@code index}, or returns -1 if
18.387 + * the element is not found.
18.388 + * More formally, returns the lowest index {@code i} such that
18.389 + * <tt>(i >= index && (o==null ? get(i)==null : o.equals(get(i))))</tt>,
18.390 + * or -1 if there is no such index.
18.391 + *
18.392 + * @param o element to search for
18.393 + * @param index index to start searching from
18.394 + * @return the index of the first occurrence of the element in
18.395 + * this vector at position {@code index} or later in the vector;
18.396 + * {@code -1} if the element is not found.
18.397 + * @throws IndexOutOfBoundsException if the specified index is negative
18.398 + * @see Object#equals(Object)
18.399 + */
18.400 + public synchronized int indexOf(Object o, int index) {
18.401 + if (o == null) {
18.402 + for (int i = index ; i < elementCount ; i++)
18.403 + if (elementData[i]==null)
18.404 + return i;
18.405 + } else {
18.406 + for (int i = index ; i < elementCount ; i++)
18.407 + if (o.equals(elementData[i]))
18.408 + return i;
18.409 + }
18.410 + return -1;
18.411 + }
18.412 +
18.413 + /**
18.414 + * Returns the index of the last occurrence of the specified element
18.415 + * in this vector, or -1 if this vector does not contain the element.
18.416 + * More formally, returns the highest index {@code i} such that
18.417 + * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
18.418 + * or -1 if there is no such index.
18.419 + *
18.420 + * @param o element to search for
18.421 + * @return the index of the last occurrence of the specified element in
18.422 + * this vector, or -1 if this vector does not contain the element
18.423 + */
18.424 + public synchronized int lastIndexOf(Object o) {
18.425 + return lastIndexOf(o, elementCount-1);
18.426 + }
18.427 +
18.428 + /**
18.429 + * Returns the index of the last occurrence of the specified element in
18.430 + * this vector, searching backwards from {@code index}, or returns -1 if
18.431 + * the element is not found.
18.432 + * More formally, returns the highest index {@code i} such that
18.433 + * <tt>(i <= index && (o==null ? get(i)==null : o.equals(get(i))))</tt>,
18.434 + * or -1 if there is no such index.
18.435 + *
18.436 + * @param o element to search for
18.437 + * @param index index to start searching backwards from
18.438 + * @return the index of the last occurrence of the element at position
18.439 + * less than or equal to {@code index} in this vector;
18.440 + * -1 if the element is not found.
18.441 + * @throws IndexOutOfBoundsException if the specified index is greater
18.442 + * than or equal to the current size of this vector
18.443 + */
18.444 + public synchronized int lastIndexOf(Object o, int index) {
18.445 + if (index >= elementCount)
18.446 + throw new IndexOutOfBoundsException(index + " >= "+ elementCount);
18.447 +
18.448 + if (o == null) {
18.449 + for (int i = index; i >= 0; i--)
18.450 + if (elementData[i]==null)
18.451 + return i;
18.452 + } else {
18.453 + for (int i = index; i >= 0; i--)
18.454 + if (o.equals(elementData[i]))
18.455 + return i;
18.456 + }
18.457 + return -1;
18.458 + }
18.459 +
18.460 + /**
18.461 + * Returns the component at the specified index.
18.462 + *
18.463 + * <p>This method is identical in functionality to the {@link #get(int)}
18.464 + * method (which is part of the {@link List} interface).
18.465 + *
18.466 + * @param index an index into this vector
18.467 + * @return the component at the specified index
18.468 + * @throws ArrayIndexOutOfBoundsException if the index is out of range
18.469 + * ({@code index < 0 || index >= size()})
18.470 + */
18.471 + public synchronized E elementAt(int index) {
18.472 + if (index >= elementCount) {
18.473 + throw new ArrayIndexOutOfBoundsException(index + " >= " + elementCount);
18.474 + }
18.475 +
18.476 + return elementData(index);
18.477 + }
18.478 +
18.479 + /**
18.480 + * Returns the first component (the item at index {@code 0}) of
18.481 + * this vector.
18.482 + *
18.483 + * @return the first component of this vector
18.484 + * @throws NoSuchElementException if this vector has no components
18.485 + */
18.486 + public synchronized E firstElement() {
18.487 + if (elementCount == 0) {
18.488 + throw new NoSuchElementException();
18.489 + }
18.490 + return elementData(0);
18.491 + }
18.492 +
18.493 + /**
18.494 + * Returns the last component of the vector.
18.495 + *
18.496 + * @return the last component of the vector, i.e., the component at index
18.497 + * <code>size() - 1</code>.
18.498 + * @throws NoSuchElementException if this vector is empty
18.499 + */
18.500 + public synchronized E lastElement() {
18.501 + if (elementCount == 0) {
18.502 + throw new NoSuchElementException();
18.503 + }
18.504 + return elementData(elementCount - 1);
18.505 + }
18.506 +
18.507 + /**
18.508 + * Sets the component at the specified {@code index} of this
18.509 + * vector to be the specified object. The previous component at that
18.510 + * position is discarded.
18.511 + *
18.512 + * <p>The index must be a value greater than or equal to {@code 0}
18.513 + * and less than the current size of the vector.
18.514 + *
18.515 + * <p>This method is identical in functionality to the
18.516 + * {@link #set(int, Object) set(int, E)}
18.517 + * method (which is part of the {@link List} interface). Note that the
18.518 + * {@code set} method reverses the order of the parameters, to more closely
18.519 + * match array usage. Note also that the {@code set} method returns the
18.520 + * old value that was stored at the specified position.
18.521 + *
18.522 + * @param obj what the component is to be set to
18.523 + * @param index the specified index
18.524 + * @throws ArrayIndexOutOfBoundsException if the index is out of range
18.525 + * ({@code index < 0 || index >= size()})
18.526 + */
18.527 + public synchronized void setElementAt(E obj, int index) {
18.528 + if (index >= elementCount) {
18.529 + throw new ArrayIndexOutOfBoundsException(index + " >= " +
18.530 + elementCount);
18.531 + }
18.532 + elementData[index] = obj;
18.533 + }
18.534 +
18.535 + /**
18.536 + * Deletes the component at the specified index. Each component in
18.537 + * this vector with an index greater or equal to the specified
18.538 + * {@code index} is shifted downward to have an index one
18.539 + * smaller than the value it had previously. The size of this vector
18.540 + * is decreased by {@code 1}.
18.541 + *
18.542 + * <p>The index must be a value greater than or equal to {@code 0}
18.543 + * and less than the current size of the vector.
18.544 + *
18.545 + * <p>This method is identical in functionality to the {@link #remove(int)}
18.546 + * method (which is part of the {@link List} interface). Note that the
18.547 + * {@code remove} method returns the old value that was stored at the
18.548 + * specified position.
18.549 + *
18.550 + * @param index the index of the object to remove
18.551 + * @throws ArrayIndexOutOfBoundsException if the index is out of range
18.552 + * ({@code index < 0 || index >= size()})
18.553 + */
18.554 + public synchronized void removeElementAt(int index) {
18.555 + modCount++;
18.556 + if (index >= elementCount) {
18.557 + throw new ArrayIndexOutOfBoundsException(index + " >= " +
18.558 + elementCount);
18.559 + }
18.560 + else if (index < 0) {
18.561 + throw new ArrayIndexOutOfBoundsException(index);
18.562 + }
18.563 + int j = elementCount - index - 1;
18.564 + if (j > 0) {
18.565 + System.arraycopy(elementData, index + 1, elementData, index, j);
18.566 + }
18.567 + elementCount--;
18.568 + elementData[elementCount] = null; /* to let gc do its work */
18.569 + }
18.570 +
18.571 + /**
18.572 + * Inserts the specified object as a component in this vector at the
18.573 + * specified {@code index}. Each component in this vector with
18.574 + * an index greater or equal to the specified {@code index} is
18.575 + * shifted upward to have an index one greater than the value it had
18.576 + * previously.
18.577 + *
18.578 + * <p>The index must be a value greater than or equal to {@code 0}
18.579 + * and less than or equal to the current size of the vector. (If the
18.580 + * index is equal to the current size of the vector, the new element
18.581 + * is appended to the Vector.)
18.582 + *
18.583 + * <p>This method is identical in functionality to the
18.584 + * {@link #add(int, Object) add(int, E)}
18.585 + * method (which is part of the {@link List} interface). Note that the
18.586 + * {@code add} method reverses the order of the parameters, to more closely
18.587 + * match array usage.
18.588 + *
18.589 + * @param obj the component to insert
18.590 + * @param index where to insert the new component
18.591 + * @throws ArrayIndexOutOfBoundsException if the index is out of range
18.592 + * ({@code index < 0 || index > size()})
18.593 + */
18.594 + public synchronized void insertElementAt(E obj, int index) {
18.595 + modCount++;
18.596 + if (index > elementCount) {
18.597 + throw new ArrayIndexOutOfBoundsException(index
18.598 + + " > " + elementCount);
18.599 + }
18.600 + ensureCapacityHelper(elementCount + 1);
18.601 + System.arraycopy(elementData, index, elementData, index + 1, elementCount - index);
18.602 + elementData[index] = obj;
18.603 + elementCount++;
18.604 + }
18.605 +
18.606 + /**
18.607 + * Adds the specified component to the end of this vector,
18.608 + * increasing its size by one. The capacity of this vector is
18.609 + * increased if its size becomes greater than its capacity.
18.610 + *
18.611 + * <p>This method is identical in functionality to the
18.612 + * {@link #add(Object) add(E)}
18.613 + * method (which is part of the {@link List} interface).
18.614 + *
18.615 + * @param obj the component to be added
18.616 + */
18.617 + public synchronized void addElement(E obj) {
18.618 + modCount++;
18.619 + ensureCapacityHelper(elementCount + 1);
18.620 + elementData[elementCount++] = obj;
18.621 + }
18.622 +
18.623 + /**
18.624 + * Removes the first (lowest-indexed) occurrence of the argument
18.625 + * from this vector. If the object is found in this vector, each
18.626 + * component in the vector with an index greater or equal to the
18.627 + * object's index is shifted downward to have an index one smaller
18.628 + * than the value it had previously.
18.629 + *
18.630 + * <p>This method is identical in functionality to the
18.631 + * {@link #remove(Object)} method (which is part of the
18.632 + * {@link List} interface).
18.633 + *
18.634 + * @param obj the component to be removed
18.635 + * @return {@code true} if the argument was a component of this
18.636 + * vector; {@code false} otherwise.
18.637 + */
18.638 + public synchronized boolean removeElement(Object obj) {
18.639 + modCount++;
18.640 + int i = indexOf(obj);
18.641 + if (i >= 0) {
18.642 + removeElementAt(i);
18.643 + return true;
18.644 + }
18.645 + return false;
18.646 + }
18.647 +
18.648 + /**
18.649 + * Removes all components from this vector and sets its size to zero.
18.650 + *
18.651 + * <p>This method is identical in functionality to the {@link #clear}
18.652 + * method (which is part of the {@link List} interface).
18.653 + */
18.654 + public synchronized void removeAllElements() {
18.655 + modCount++;
18.656 + // Let gc do its work
18.657 + for (int i = 0; i < elementCount; i++)
18.658 + elementData[i] = null;
18.659 +
18.660 + elementCount = 0;
18.661 + }
18.662 +
18.663 + /**
18.664 + * Returns a clone of this vector. The copy will contain a
18.665 + * reference to a clone of the internal data array, not a reference
18.666 + * to the original internal data array of this {@code Vector} object.
18.667 + *
18.668 + * @return a clone of this vector
18.669 + */
18.670 + public synchronized Object clone() {
18.671 + try {
18.672 + @SuppressWarnings("unchecked")
18.673 + Vector<E> v = (Vector<E>) super.clone();
18.674 + v.elementData = Arrays.copyOf(elementData, elementCount);
18.675 + v.modCount = 0;
18.676 + return v;
18.677 + } catch (CloneNotSupportedException e) {
18.678 + // this shouldn't happen, since we are Cloneable
18.679 + throw new InternalError();
18.680 + }
18.681 + }
18.682 +
18.683 + /**
18.684 + * Returns an array containing all of the elements in this Vector
18.685 + * in the correct order.
18.686 + *
18.687 + * @since 1.2
18.688 + */
18.689 + public synchronized Object[] toArray() {
18.690 + return Arrays.copyOf(elementData, elementCount);
18.691 + }
18.692 +
18.693 + /**
18.694 + * Returns an array containing all of the elements in this Vector in the
18.695 + * correct order; the runtime type of the returned array is that of the
18.696 + * specified array. If the Vector fits in the specified array, it is
18.697 + * returned therein. Otherwise, a new array is allocated with the runtime
18.698 + * type of the specified array and the size of this Vector.
18.699 + *
18.700 + * <p>If the Vector fits in the specified array with room to spare
18.701 + * (i.e., the array has more elements than the Vector),
18.702 + * the element in the array immediately following the end of the
18.703 + * Vector is set to null. (This is useful in determining the length
18.704 + * of the Vector <em>only</em> if the caller knows that the Vector
18.705 + * does not contain any null elements.)
18.706 + *
18.707 + * @param a the array into which the elements of the Vector are to
18.708 + * be stored, if it is big enough; otherwise, a new array of the
18.709 + * same runtime type is allocated for this purpose.
18.710 + * @return an array containing the elements of the Vector
18.711 + * @throws ArrayStoreException if the runtime type of a is not a supertype
18.712 + * of the runtime type of every element in this Vector
18.713 + * @throws NullPointerException if the given array is null
18.714 + * @since 1.2
18.715 + */
18.716 + @SuppressWarnings("unchecked")
18.717 + public synchronized <T> T[] toArray(T[] a) {
18.718 + if (a.length < elementCount)
18.719 + return (T[]) Arrays.copyOf(elementData, elementCount, a.getClass());
18.720 +
18.721 + System.arraycopy(elementData, 0, a, 0, elementCount);
18.722 +
18.723 + if (a.length > elementCount)
18.724 + a[elementCount] = null;
18.725 +
18.726 + return a;
18.727 + }
18.728 +
18.729 + // Positional Access Operations
18.730 +
18.731 + @SuppressWarnings("unchecked")
18.732 + E elementData(int index) {
18.733 + return (E) elementData[index];
18.734 + }
18.735 +
18.736 + /**
18.737 + * Returns the element at the specified position in this Vector.
18.738 + *
18.739 + * @param index index of the element to return
18.740 + * @return object at the specified index
18.741 + * @throws ArrayIndexOutOfBoundsException if the index is out of range
18.742 + * ({@code index < 0 || index >= size()})
18.743 + * @since 1.2
18.744 + */
18.745 + public synchronized E get(int index) {
18.746 + if (index >= elementCount)
18.747 + throw new ArrayIndexOutOfBoundsException(index);
18.748 +
18.749 + return elementData(index);
18.750 + }
18.751 +
18.752 + /**
18.753 + * Replaces the element at the specified position in this Vector with the
18.754 + * specified element.
18.755 + *
18.756 + * @param index index of the element to replace
18.757 + * @param element element to be stored at the specified position
18.758 + * @return the element previously at the specified position
18.759 + * @throws ArrayIndexOutOfBoundsException if the index is out of range
18.760 + * ({@code index < 0 || index >= size()})
18.761 + * @since 1.2
18.762 + */
18.763 + public synchronized E set(int index, E element) {
18.764 + if (index >= elementCount)
18.765 + throw new ArrayIndexOutOfBoundsException(index);
18.766 +
18.767 + E oldValue = elementData(index);
18.768 + elementData[index] = element;
18.769 + return oldValue;
18.770 + }
18.771 +
18.772 + /**
18.773 + * Appends the specified element to the end of this Vector.
18.774 + *
18.775 + * @param e element to be appended to this Vector
18.776 + * @return {@code true} (as specified by {@link Collection#add})
18.777 + * @since 1.2
18.778 + */
18.779 + public synchronized boolean add(E e) {
18.780 + modCount++;
18.781 + ensureCapacityHelper(elementCount + 1);
18.782 + elementData[elementCount++] = e;
18.783 + return true;
18.784 + }
18.785 +
18.786 + /**
18.787 + * Removes the first occurrence of the specified element in this Vector
18.788 + * If the Vector does not contain the element, it is unchanged. More
18.789 + * formally, removes the element with the lowest index i such that
18.790 + * {@code (o==null ? get(i)==null : o.equals(get(i)))} (if such
18.791 + * an element exists).
18.792 + *
18.793 + * @param o element to be removed from this Vector, if present
18.794 + * @return true if the Vector contained the specified element
18.795 + * @since 1.2
18.796 + */
18.797 + public boolean remove(Object o) {
18.798 + return removeElement(o);
18.799 + }
18.800 +
18.801 + /**
18.802 + * Inserts the specified element at the specified position in this Vector.
18.803 + * Shifts the element currently at that position (if any) and any
18.804 + * subsequent elements to the right (adds one to their indices).
18.805 + *
18.806 + * @param index index at which the specified element is to be inserted
18.807 + * @param element element to be inserted
18.808 + * @throws ArrayIndexOutOfBoundsException if the index is out of range
18.809 + * ({@code index < 0 || index > size()})
18.810 + * @since 1.2
18.811 + */
18.812 + public void add(int index, E element) {
18.813 + insertElementAt(element, index);
18.814 + }
18.815 +
18.816 + /**
18.817 + * Removes the element at the specified position in this Vector.
18.818 + * Shifts any subsequent elements to the left (subtracts one from their
18.819 + * indices). Returns the element that was removed from the Vector.
18.820 + *
18.821 + * @throws ArrayIndexOutOfBoundsException if the index is out of range
18.822 + * ({@code index < 0 || index >= size()})
18.823 + * @param index the index of the element to be removed
18.824 + * @return element that was removed
18.825 + * @since 1.2
18.826 + */
18.827 + public synchronized E remove(int index) {
18.828 + modCount++;
18.829 + if (index >= elementCount)
18.830 + throw new ArrayIndexOutOfBoundsException(index);
18.831 + E oldValue = elementData(index);
18.832 +
18.833 + int numMoved = elementCount - index - 1;
18.834 + if (numMoved > 0)
18.835 + System.arraycopy(elementData, index+1, elementData, index,
18.836 + numMoved);
18.837 + elementData[--elementCount] = null; // Let gc do its work
18.838 +
18.839 + return oldValue;
18.840 + }
18.841 +
18.842 + /**
18.843 + * Removes all of the elements from this Vector. The Vector will
18.844 + * be empty after this call returns (unless it throws an exception).
18.845 + *
18.846 + * @since 1.2
18.847 + */
18.848 + public void clear() {
18.849 + removeAllElements();
18.850 + }
18.851 +
18.852 + // Bulk Operations
18.853 +
18.854 + /**
18.855 + * Returns true if this Vector contains all of the elements in the
18.856 + * specified Collection.
18.857 + *
18.858 + * @param c a collection whose elements will be tested for containment
18.859 + * in this Vector
18.860 + * @return true if this Vector contains all of the elements in the
18.861 + * specified collection
18.862 + * @throws NullPointerException if the specified collection is null
18.863 + */
18.864 + public synchronized boolean containsAll(Collection<?> c) {
18.865 + return super.containsAll(c);
18.866 + }
18.867 +
18.868 + /**
18.869 + * Appends all of the elements in the specified Collection to the end of
18.870 + * this Vector, in the order that they are returned by the specified
18.871 + * Collection's Iterator. The behavior of this operation is undefined if
18.872 + * the specified Collection is modified while the operation is in progress.
18.873 + * (This implies that the behavior of this call is undefined if the
18.874 + * specified Collection is this Vector, and this Vector is nonempty.)
18.875 + *
18.876 + * @param c elements to be inserted into this Vector
18.877 + * @return {@code true} if this Vector changed as a result of the call
18.878 + * @throws NullPointerException if the specified collection is null
18.879 + * @since 1.2
18.880 + */
18.881 + public synchronized boolean addAll(Collection<? extends E> c) {
18.882 + modCount++;
18.883 + Object[] a = c.toArray();
18.884 + int numNew = a.length;
18.885 + ensureCapacityHelper(elementCount + numNew);
18.886 + System.arraycopy(a, 0, elementData, elementCount, numNew);
18.887 + elementCount += numNew;
18.888 + return numNew != 0;
18.889 + }
18.890 +
18.891 + /**
18.892 + * Removes from this Vector all of its elements that are contained in the
18.893 + * specified Collection.
18.894 + *
18.895 + * @param c a collection of elements to be removed from the Vector
18.896 + * @return true if this Vector changed as a result of the call
18.897 + * @throws ClassCastException if the types of one or more elements
18.898 + * in this vector are incompatible with the specified
18.899 + * collection
18.900 + * (<a href="Collection.html#optional-restrictions">optional</a>)
18.901 + * @throws NullPointerException if this vector contains one or more null
18.902 + * elements and the specified collection does not support null
18.903 + * elements
18.904 + * (<a href="Collection.html#optional-restrictions">optional</a>),
18.905 + * or if the specified collection is null
18.906 + * @since 1.2
18.907 + */
18.908 + public synchronized boolean removeAll(Collection<?> c) {
18.909 + return super.removeAll(c);
18.910 + }
18.911 +
18.912 + /**
18.913 + * Retains only the elements in this Vector that are contained in the
18.914 + * specified Collection. In other words, removes from this Vector all
18.915 + * of its elements that are not contained in the specified Collection.
18.916 + *
18.917 + * @param c a collection of elements to be retained in this Vector
18.918 + * (all other elements are removed)
18.919 + * @return true if this Vector changed as a result of the call
18.920 + * @throws ClassCastException if the types of one or more elements
18.921 + * in this vector are incompatible with the specified
18.922 + * collection
18.923 + * (<a href="Collection.html#optional-restrictions">optional</a>)
18.924 + * @throws NullPointerException if this vector contains one or more null
18.925 + * elements and the specified collection does not support null
18.926 + * elements
18.927 + * (<a href="Collection.html#optional-restrictions">optional</a>),
18.928 + * or if the specified collection is null
18.929 + * @since 1.2
18.930 + */
18.931 + public synchronized boolean retainAll(Collection<?> c) {
18.932 + return super.retainAll(c);
18.933 + }
18.934 +
18.935 + /**
18.936 + * Inserts all of the elements in the specified Collection into this
18.937 + * Vector at the specified position. Shifts the element currently at
18.938 + * that position (if any) and any subsequent elements to the right
18.939 + * (increases their indices). The new elements will appear in the Vector
18.940 + * in the order that they are returned by the specified Collection's
18.941 + * iterator.
18.942 + *
18.943 + * @param index index at which to insert the first element from the
18.944 + * specified collection
18.945 + * @param c elements to be inserted into this Vector
18.946 + * @return {@code true} if this Vector changed as a result of the call
18.947 + * @throws ArrayIndexOutOfBoundsException if the index is out of range
18.948 + * ({@code index < 0 || index > size()})
18.949 + * @throws NullPointerException if the specified collection is null
18.950 + * @since 1.2
18.951 + */
18.952 + public synchronized boolean addAll(int index, Collection<? extends E> c) {
18.953 + modCount++;
18.954 + if (index < 0 || index > elementCount)
18.955 + throw new ArrayIndexOutOfBoundsException(index);
18.956 +
18.957 + Object[] a = c.toArray();
18.958 + int numNew = a.length;
18.959 + ensureCapacityHelper(elementCount + numNew);
18.960 +
18.961 + int numMoved = elementCount - index;
18.962 + if (numMoved > 0)
18.963 + System.arraycopy(elementData, index, elementData, index + numNew,
18.964 + numMoved);
18.965 +
18.966 + System.arraycopy(a, 0, elementData, index, numNew);
18.967 + elementCount += numNew;
18.968 + return numNew != 0;
18.969 + }
18.970 +
18.971 + /**
18.972 + * Compares the specified Object with this Vector for equality. Returns
18.973 + * true if and only if the specified Object is also a List, both Lists
18.974 + * have the same size, and all corresponding pairs of elements in the two
18.975 + * Lists are <em>equal</em>. (Two elements {@code e1} and
18.976 + * {@code e2} are <em>equal</em> if {@code (e1==null ? e2==null :
18.977 + * e1.equals(e2))}.) In other words, two Lists are defined to be
18.978 + * equal if they contain the same elements in the same order.
18.979 + *
18.980 + * @param o the Object to be compared for equality with this Vector
18.981 + * @return true if the specified Object is equal to this Vector
18.982 + */
18.983 + public synchronized boolean equals(Object o) {
18.984 + return super.equals(o);
18.985 + }
18.986 +
18.987 + /**
18.988 + * Returns the hash code value for this Vector.
18.989 + */
18.990 + public synchronized int hashCode() {
18.991 + return super.hashCode();
18.992 + }
18.993 +
18.994 + /**
18.995 + * Returns a string representation of this Vector, containing
18.996 + * the String representation of each element.
18.997 + */
18.998 + public synchronized String toString() {
18.999 + return super.toString();
18.1000 + }
18.1001 +
18.1002 + /**
18.1003 + * Returns a view of the portion of this List between fromIndex,
18.1004 + * inclusive, and toIndex, exclusive. (If fromIndex and toIndex are
18.1005 + * equal, the returned List is empty.) The returned List is backed by this
18.1006 + * List, so changes in the returned List are reflected in this List, and
18.1007 + * vice-versa. The returned List supports all of the optional List
18.1008 + * operations supported by this List.
18.1009 + *
18.1010 + * <p>This method eliminates the need for explicit range operations (of
18.1011 + * the sort that commonly exist for arrays). Any operation that expects
18.1012 + * a List can be used as a range operation by operating on a subList view
18.1013 + * instead of a whole List. For example, the following idiom
18.1014 + * removes a range of elements from a List:
18.1015 + * <pre>
18.1016 + * list.subList(from, to).clear();
18.1017 + * </pre>
18.1018 + * Similar idioms may be constructed for indexOf and lastIndexOf,
18.1019 + * and all of the algorithms in the Collections class can be applied to
18.1020 + * a subList.
18.1021 + *
18.1022 + * <p>The semantics of the List returned by this method become undefined if
18.1023 + * the backing list (i.e., this List) is <i>structurally modified</i> in
18.1024 + * any way other than via the returned List. (Structural modifications are
18.1025 + * those that change the size of the List, or otherwise perturb it in such
18.1026 + * a fashion that iterations in progress may yield incorrect results.)
18.1027 + *
18.1028 + * @param fromIndex low endpoint (inclusive) of the subList
18.1029 + * @param toIndex high endpoint (exclusive) of the subList
18.1030 + * @return a view of the specified range within this List
18.1031 + * @throws IndexOutOfBoundsException if an endpoint index value is out of range
18.1032 + * {@code (fromIndex < 0 || toIndex > size)}
18.1033 + * @throws IllegalArgumentException if the endpoint indices are out of order
18.1034 + * {@code (fromIndex > toIndex)}
18.1035 + */
18.1036 + public synchronized List<E> subList(int fromIndex, int toIndex) {
18.1037 + return Collections.synchronizedList(super.subList(fromIndex, toIndex),
18.1038 + this);
18.1039 + }
18.1040 +
18.1041 + /**
18.1042 + * Removes from this list all of the elements whose index is between
18.1043 + * {@code fromIndex}, inclusive, and {@code toIndex}, exclusive.
18.1044 + * Shifts any succeeding elements to the left (reduces their index).
18.1045 + * This call shortens the list by {@code (toIndex - fromIndex)} elements.
18.1046 + * (If {@code toIndex==fromIndex}, this operation has no effect.)
18.1047 + */
18.1048 + protected synchronized void removeRange(int fromIndex, int toIndex) {
18.1049 + modCount++;
18.1050 + int numMoved = elementCount - toIndex;
18.1051 + System.arraycopy(elementData, toIndex, elementData, fromIndex,
18.1052 + numMoved);
18.1053 +
18.1054 + // Let gc do its work
18.1055 + int newElementCount = elementCount - (toIndex-fromIndex);
18.1056 + while (elementCount != newElementCount)
18.1057 + elementData[--elementCount] = null;
18.1058 + }
18.1059 +
18.1060 + /**
18.1061 + * Save the state of the {@code Vector} instance to a stream (that
18.1062 + * is, serialize it).
18.1063 + * This method performs synchronization to ensure the consistency
18.1064 + * of the serialized data.
18.1065 + */
18.1066 + private void writeObject(java.io.ObjectOutputStream s)
18.1067 + throws java.io.IOException {
18.1068 + final java.io.ObjectOutputStream.PutField fields = s.putFields();
18.1069 + final Object[] data;
18.1070 + synchronized (this) {
18.1071 + fields.put("capacityIncrement", capacityIncrement);
18.1072 + fields.put("elementCount", elementCount);
18.1073 + data = elementData.clone();
18.1074 + }
18.1075 + fields.put("elementData", data);
18.1076 + s.writeFields();
18.1077 + }
18.1078 +
18.1079 + /**
18.1080 + * Returns a list iterator over the elements in this list (in proper
18.1081 + * sequence), starting at the specified position in the list.
18.1082 + * The specified index indicates the first element that would be
18.1083 + * returned by an initial call to {@link ListIterator#next next}.
18.1084 + * An initial call to {@link ListIterator#previous previous} would
18.1085 + * return the element with the specified index minus one.
18.1086 + *
18.1087 + * <p>The returned list iterator is <a href="#fail-fast"><i>fail-fast</i></a>.
18.1088 + *
18.1089 + * @throws IndexOutOfBoundsException {@inheritDoc}
18.1090 + */
18.1091 + public synchronized ListIterator<E> listIterator(int index) {
18.1092 + if (index < 0 || index > elementCount)
18.1093 + throw new IndexOutOfBoundsException("Index: "+index);
18.1094 + return new ListItr(index);
18.1095 + }
18.1096 +
18.1097 + /**
18.1098 + * Returns a list iterator over the elements in this list (in proper
18.1099 + * sequence).
18.1100 + *
18.1101 + * <p>The returned list iterator is <a href="#fail-fast"><i>fail-fast</i></a>.
18.1102 + *
18.1103 + * @see #listIterator(int)
18.1104 + */
18.1105 + public synchronized ListIterator<E> listIterator() {
18.1106 + return new ListItr(0);
18.1107 + }
18.1108 +
18.1109 + /**
18.1110 + * Returns an iterator over the elements in this list in proper sequence.
18.1111 + *
18.1112 + * <p>The returned iterator is <a href="#fail-fast"><i>fail-fast</i></a>.
18.1113 + *
18.1114 + * @return an iterator over the elements in this list in proper sequence
18.1115 + */
18.1116 + public synchronized Iterator<E> iterator() {
18.1117 + return new Itr();
18.1118 + }
18.1119 +
18.1120 + /**
18.1121 + * An optimized version of AbstractList.Itr
18.1122 + */
18.1123 + private class Itr implements Iterator<E> {
18.1124 + int cursor; // index of next element to return
18.1125 + int lastRet = -1; // index of last element returned; -1 if no such
18.1126 + int expectedModCount = modCount;
18.1127 +
18.1128 + public boolean hasNext() {
18.1129 + // Racy but within spec, since modifications are checked
18.1130 + // within or after synchronization in next/previous
18.1131 + return cursor != elementCount;
18.1132 + }
18.1133 +
18.1134 + public E next() {
18.1135 + synchronized (Vector.this) {
18.1136 + checkForComodification();
18.1137 + int i = cursor;
18.1138 + if (i >= elementCount)
18.1139 + throw new NoSuchElementException();
18.1140 + cursor = i + 1;
18.1141 + return elementData(lastRet = i);
18.1142 + }
18.1143 + }
18.1144 +
18.1145 + public void remove() {
18.1146 + if (lastRet == -1)
18.1147 + throw new IllegalStateException();
18.1148 + synchronized (Vector.this) {
18.1149 + checkForComodification();
18.1150 + Vector.this.remove(lastRet);
18.1151 + expectedModCount = modCount;
18.1152 + }
18.1153 + cursor = lastRet;
18.1154 + lastRet = -1;
18.1155 + }
18.1156 +
18.1157 + final void checkForComodification() {
18.1158 + if (modCount != expectedModCount)
18.1159 + throw new ConcurrentModificationException();
18.1160 + }
18.1161 + }
18.1162 +
18.1163 + /**
18.1164 + * An optimized version of AbstractList.ListItr
18.1165 + */
18.1166 + final class ListItr extends Itr implements ListIterator<E> {
18.1167 + ListItr(int index) {
18.1168 + super();
18.1169 + cursor = index;
18.1170 + }
18.1171 +
18.1172 + public boolean hasPrevious() {
18.1173 + return cursor != 0;
18.1174 + }
18.1175 +
18.1176 + public int nextIndex() {
18.1177 + return cursor;
18.1178 + }
18.1179 +
18.1180 + public int previousIndex() {
18.1181 + return cursor - 1;
18.1182 + }
18.1183 +
18.1184 + public E previous() {
18.1185 + synchronized (Vector.this) {
18.1186 + checkForComodification();
18.1187 + int i = cursor - 1;
18.1188 + if (i < 0)
18.1189 + throw new NoSuchElementException();
18.1190 + cursor = i;
18.1191 + return elementData(lastRet = i);
18.1192 + }
18.1193 + }
18.1194 +
18.1195 + public void set(E e) {
18.1196 + if (lastRet == -1)
18.1197 + throw new IllegalStateException();
18.1198 + synchronized (Vector.this) {
18.1199 + checkForComodification();
18.1200 + Vector.this.set(lastRet, e);
18.1201 + }
18.1202 + }
18.1203 +
18.1204 + public void add(E e) {
18.1205 + int i = cursor;
18.1206 + synchronized (Vector.this) {
18.1207 + checkForComodification();
18.1208 + Vector.this.add(i, e);
18.1209 + expectedModCount = modCount;
18.1210 + }
18.1211 + cursor = i + 1;
18.1212 + lastRet = -1;
18.1213 + }
18.1214 + }
18.1215 +}
19.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
19.2 +++ b/emul/mini/src/main/java/java/lang/ArrayStoreException.java Mon Jan 28 13:28:02 2013 +0100
19.3 @@ -0,0 +1,60 @@
19.4 +/*
19.5 + * Copyright (c) 1995, 2008, Oracle and/or its affiliates. All rights reserved.
19.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
19.7 + *
19.8 + * This code is free software; you can redistribute it and/or modify it
19.9 + * under the terms of the GNU General Public License version 2 only, as
19.10 + * published by the Free Software Foundation. Oracle designates this
19.11 + * particular file as subject to the "Classpath" exception as provided
19.12 + * by Oracle in the LICENSE file that accompanied this code.
19.13 + *
19.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
19.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
19.17 + * version 2 for more details (a copy is included in the LICENSE file that
19.18 + * accompanied this code).
19.19 + *
19.20 + * You should have received a copy of the GNU General Public License version
19.21 + * 2 along with this work; if not, write to the Free Software Foundation,
19.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19.23 + *
19.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
19.25 + * or visit www.oracle.com if you need additional information or have any
19.26 + * questions.
19.27 + */
19.28 +
19.29 +package java.lang;
19.30 +
19.31 +/**
19.32 + * Thrown to indicate that an attempt has been made to store the
19.33 + * wrong type of object into an array of objects. For example, the
19.34 + * following code generates an <code>ArrayStoreException</code>:
19.35 + * <p><blockquote><pre>
19.36 + * Object x[] = new String[3];
19.37 + * x[0] = new Integer(0);
19.38 + * </pre></blockquote>
19.39 + *
19.40 + * @author unascribed
19.41 + * @since JDK1.0
19.42 + */
19.43 +public
19.44 +class ArrayStoreException extends RuntimeException {
19.45 + private static final long serialVersionUID = -4522193890499838241L;
19.46 +
19.47 + /**
19.48 + * Constructs an <code>ArrayStoreException</code> with no detail message.
19.49 + */
19.50 + public ArrayStoreException() {
19.51 + super();
19.52 + }
19.53 +
19.54 + /**
19.55 + * Constructs an <code>ArrayStoreException</code> with the specified
19.56 + * detail message.
19.57 + *
19.58 + * @param s the detail message.
19.59 + */
19.60 + public ArrayStoreException(String s) {
19.61 + super(s);
19.62 + }
19.63 +}
20.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
20.2 +++ b/emul/mini/src/main/java/java/lang/Override.java Mon Jan 28 13:28:02 2013 +0100
20.3 @@ -0,0 +1,52 @@
20.4 +/*
20.5 + * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
20.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
20.7 + *
20.8 + * This code is free software; you can redistribute it and/or modify it
20.9 + * under the terms of the GNU General Public License version 2 only, as
20.10 + * published by the Free Software Foundation. Oracle designates this
20.11 + * particular file as subject to the "Classpath" exception as provided
20.12 + * by Oracle in the LICENSE file that accompanied this code.
20.13 + *
20.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
20.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
20.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20.17 + * version 2 for more details (a copy is included in the LICENSE file that
20.18 + * accompanied this code).
20.19 + *
20.20 + * You should have received a copy of the GNU General Public License version
20.21 + * 2 along with this work; if not, write to the Free Software Foundation,
20.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20.23 + *
20.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20.25 + * or visit www.oracle.com if you need additional information or have any
20.26 + * questions.
20.27 + */
20.28 +
20.29 +package java.lang;
20.30 +
20.31 +import java.lang.annotation.*;
20.32 +
20.33 +/**
20.34 + * Indicates that a method declaration is intended to override a
20.35 + * method declaration in a supertype. If a method is annotated with
20.36 + * this annotation type compilers are required to generate an error
20.37 + * message unless at least one of the following conditions hold:
20.38 + *
20.39 + * <ul><li>
20.40 + * The method does override or implement a method declared in a
20.41 + * supertype.
20.42 + * </li><li>
20.43 + * The method has a signature that is override-equivalent to that of
20.44 + * any public method declared in {@linkplain Object}.
20.45 + * </li></ul>
20.46 + *
20.47 + * @author Peter von der Ahé
20.48 + * @author Joshua Bloch
20.49 + * @jls 9.6.1.4 Override
20.50 + * @since 1.5
20.51 + */
20.52 +@Target(ElementType.METHOD)
20.53 +@Retention(RetentionPolicy.SOURCE)
20.54 +public @interface Override {
20.55 +}