package java.util;

import ej.annotation.Nullable;

/**
 * This exception may be thrown by methods that have detected concurrent modification of an object
 * when such modification is not permissible.
 * <p>
 * For example, it is not generally permissible for one thread to modify a Collection while another
 * thread is iterating over it. In general, the results of the iteration are undefined under these
 * circumstances. Some Iterator implementations (including those of all the general purpose
 * collection implementations provided by the JRE) may choose to throw this exception if this
 * behavior is detected. Iterators that do this are known as <i>fail-fast</i> iterators, as they
 * fail quickly and cleanly, rather that risking arbitrary, non-deterministic behavior at an
 * undetermined time in the future.
 * <p>
 * Note that this exception does not always indicate that an object has been concurrently modified
 * by a <i>different</i> thread. If a single thread issues a sequence of method invocations that
 * violates the contract of an object, the object may throw this exception. For example, if a thread
 * modifies a collection directly while it is iterating over the collection with a fail-fast
 * iterator, the iterator will throw this exception.
 *
 * <p>
 * Note that fail-fast behavior cannot be guaranteed as it is, generally speaking, impossible to
 * make any hard guarantees in the presence of unsynchronized concurrent modification. Fail-fast
 * operations throw {@code ConcurrentModificationException} on a best-effort basis. Therefore, it
 * would be wrong to write a program that depended on this exception for its correctness: <i>
 * {@code ConcurrentModificationException} should be used only to detect bugs.</i>
 *
 * @see Collection
 * @see Iterator
 * @see ListIterator
 * @see Vector
 * @see Hashtable
 * @see AbstractList
 *
 */
public class ConcurrentModificationException extends RuntimeException {

	/**
	 * Constructs a ConcurrentModificationException with no detail message.
	 */
	public ConcurrentModificationException() {
		throw new RuntimeException();
	}

	/**
	 * Constructs a {@code ConcurrentModificationException} with the specified detail message.
	 *
	 * @param message
	 *        the detail message pertaining to this exception.
	 */
	public ConcurrentModificationException(String message) {
		throw new RuntimeException();
	}

	/**
	 * Constructs a new exception with the specified detail message and cause.
	 *
	 * <p>
	 * Note that the detail message associated with <code>cause</code> is <i>not</i> automatically
	 * incorporated in this exception's detail message.
	 *
	 * @param message
	 *        the detail message (which is saved for later retrieval by the
	 *        {@link Throwable#getMessage()} method).
	 * @param cause
	 *        the cause (which is saved for later retrieval by the {@link Throwable#getCause()} method).
	 *        (A {@code null} value is permitted, and indicates that the cause is nonexistent or
	 *        unknown.)
	 */
	public ConcurrentModificationException(String message, @Nullable Throwable cause) {
		throw new RuntimeException();
	}

	/**
	 * Constructs a new exception with the specified cause and a detail message of
	 * {@code (cause==null ? null : cause.toString())} (which typically contains the class and detail
	 * message of {@code cause}.
	 *
	 * @param cause
	 *        the cause (which is saved for later retrieval by the {@link Throwable#getCause()} method).
	 *        (A {@code null} value is permitted, and indicates that the cause is nonexistent or
	 *        unknown.)
	 */
	public ConcurrentModificationException(@Nullable Throwable cause) {
		throw new RuntimeException();
	}
}