de.caff.generics

## Class SynchronizedList<T>

- java.lang.Object
- - de.caff.generics.SynchronizedList<T>

- All Implemented Interfaces:
    java.lang.Iterable<T>, java.util.Collection<T>, java.util.List<T>

      public class SynchronizedList<T>
      extends java.lang.Object
      implements java.util.List<T>

  Synchronized list.

  This does synchronization a bit different than the collection returned by standard Java `Collections.synchronizedList(List)`.

  Especially iterators are running over a copy of the original list, so the list has not to stay synchronized via any iteration.

  Please note that this does not support sublisting.

  It is adamant that all accesses to the underlying list are done via this list, otherwise the synchronization guarantee is void.

  Author:
    Rammi
  See Also:
    `Types.synchronizedCollection(Collection)`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SynchronizedList(java.util.List<T> baseList)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(int index, T element)` Inserts the specified element at the specified position in this list (optional operation).
    `boolean` | `add(T o)` Ensures that this collection contains the specified element (optional operation).
    `boolean` | `addAll(java.util.Collection<? extends T> c)` Adds all of the elements in the specified collection to this collection (optional operation).
    `boolean` | `addAll(int index, java.util.Collection<? extends T> c)` Inserts all of the elements in the specified collection into this list at the specified position (optional operation).
    `void` | `clear()` Removes all of the elements from this collection (optional operation).
    `boolean` | `contains(java.lang.Object o)` Returns `true` if this collection contains the specified element.
    `boolean` | `containsAll(java.util.Collection<?> c)` Returns `true` if this collection contains all of the elements in the specified collection.
    `static <U> SynchronizedList<U>` | `create(java.util.List<U> basicList)` Create a synchronized list from the given basic list.
    `T` | `get(int index)` Returns the element at the specified position in this list.
    `int` | `indexOf(java.lang.Object o)` Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element.
    `boolean` | `isEmpty()` Returns `true` if this collection contains no elements.
    `java.util.Iterator<T>` | `iterator()` Returns an iterator over the elements in this collection.
    `int` | `lastIndexOf(java.lang.Object o)` Returns the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element.
    `java.util.ListIterator<T>` | `listIterator()` Returns a list iterator over the elements in this list (in proper sequence).
    `java.util.ListIterator<T>` | `listIterator(int index)` Returns a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list.
    `T` | `remove(int index)` Removes the element at the specified position in this list (optional operation).
    `boolean` | `remove(java.lang.Object o)` Removes a single instance of the specified element from this collection, if it is present (optional operation).
    `boolean` | `removeAll(java.util.Collection<?> c)` Removes all this collection's elements that are also contained in the specified collection (optional operation).
    `boolean` | `retainAll(java.util.Collection<?> c)` Retains only the elements in this collection that are contained in the specified collection (optional operation).
    `T` | `set(int index, T element)` Replaces the element at the specified position in this list with the specified element (optional operation).
    `int` | `size()` Returns the number of elements in this collection.
    `void` | `sort(java.util.Comparator<? super T> c)`
    `java.util.List<T>` | `subList(int fromIndex, int toIndex)` Returns a view of the portion of this list between the specified `fromIndex`, inclusive, and `toIndex`, exclusive.
    `java.lang.Object[]` | `toArray()` Returns an array containing all of the elements in this collection.
    `<U> U[]` | `toArray(U[] a)` Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface java.util.List

      `equals, hashCode, replaceAll, spliterator`

    - ### Methods inherited from interface java.util.Collection

      `parallelStream, removeIf, stream`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach`

- - ### Constructor Detail

    - #### SynchronizedList

          public SynchronizedList(@NotNull
                                  java.util.List<T> baseList)

      Constructor.
      Parameters:
        `baseList` - the base list wrapped by this synchronizer

  - ### Method Detail

    - #### size

          public int size()

      Returns the number of elements in this collection. If this collection contains more than `Integer.MAX_VALUE` elements, returns `Integer.MAX_VALUE`.
      Specified by:
        `size` in interface `java.util.Collection<T>`
      Specified by:
        `size` in interface `java.util.List<T>`
      Returns:
        the number of elements in this collection

    - #### isEmpty

          public boolean isEmpty()

      Returns `true` if this collection contains no elements.
      Specified by:
        `isEmpty` in interface `java.util.Collection<T>`
      Specified by:
        `isEmpty` in interface `java.util.List<T>`
      Returns:
        `true` if this collection contains no elements

    - #### contains

          public boolean contains(java.lang.Object o)

      Returns `true` if this collection contains the specified element. More formally, returns `true` if and only if this collection contains at least one element `e` such that `(o==null ? e==null : o.equals(e))`.
      Specified by:
        `contains` in interface `java.util.Collection<T>`
      Specified by:
        `contains` in interface `java.util.List<T>`
      Parameters:
        `o` - element whose presence in this collection is to be tested.
      Returns:
        `true` if this collection contains the specified element
      Throws:
        `java.lang.ClassCastException` - if the type of the specified element is incompatible with this collection (optional).
        `java.lang.NullPointerException` - if the specified element is null and this collection does not support null elements (optional).

    - #### iterator

          @NotNull
          public java.util.Iterator<T> iterator()

      Returns an iterator over the elements in this collection. There are no guarantees concerning the order in which the elements are returned (unless this collection is an instance of some class that provides a guarantee).
      Specified by:
        `iterator` in interface `java.lang.Iterable<T>`
      Specified by:
        `iterator` in interface `java.util.Collection<T>`
      Specified by:
        `iterator` in interface `java.util.List<T>`
      Returns:
        an `Iterator` over the elements in this collection

    - #### listIterator

          @NotNull
          public java.util.ListIterator<T> listIterator()

      Returns a list iterator over the elements in this list (in proper sequence).
      Specified by:
        `listIterator` in interface `java.util.List<T>`
      Returns:
        a list iterator over the elements in this list (in proper sequence)

    - #### listIterator

          @NotNull
          public java.util.ListIterator<T> listIterator(int index)

      Returns a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list. The specified index indicates the first element that would be returned by an initial call to `next`. An initial call to `previous` would return the element with the specified index minus one.
      Specified by:
        `listIterator` in interface `java.util.List<T>`
      Parameters:
        `index` - index of the first element to be returned from the list iterator (by a call to `next`)
      Returns:
        a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of range (`index &lt; 0 || index &gt; size()`)

    - #### toArray

          @NotNull
          public java.lang.Object[] toArray()

      Returns an array containing all of the elements in this collection. If the collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

      The returned array will be "safe" in that no references to it are maintained by this collection. (In other words, this method must allocate a new array even if this collection is backed by an array). The caller is thus free to modify the returned array.

      This method acts as bridge between array-based and collection-based APIs.

      Specified by:
        `toArray` in interface `java.util.Collection<T>`
      Specified by:
        `toArray` in interface `java.util.List<T>`
      Returns:
        an array containing all of the elements in this collection

    - #### toArray

          @NotNull
          public <U> U[] toArray(@NotNull
                                          U[] a)

      Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array. If the collection fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this collection.

      If this collection fits in the specified array with room to spare (i.e., the array has more elements than this collection), the element in the array immediately following the end of the collection is set to `null`. This is useful in determining the length of this collection only if the caller knows that this collection does not contain any `null` elements.)

      If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

      Like the `toArray` method, this method acts as bridge between array-based and collection-based APIs. Further, this method allows precise control over the runtime type of the output array, and may, under certain circumstances, be used to save allocation costs

      Suppose `l` is a `List` known to contain only strings. The following code can be used to dump the list into a newly allocated array of `String`:

               String[] x = (String[]) v.toArray(new String[0]);

      Note that `toArray(new Object[0])` is identical in function to `toArray()`.

      Specified by:
        `toArray` in interface `java.util.Collection<T>`
      Specified by:
        `toArray` in interface `java.util.List<T>`
      Parameters:
        `a` - the array into which the elements of this collection are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.
      Returns:
        an array containing the elements of this collection
      Throws:
        `java.lang.ArrayStoreException` - the runtime type of the specified array is not a supertype of the runtime type of every element in this collection.
        `java.lang.NullPointerException` - if the specified array is `null`.

    - #### add

          public boolean add(T o)

      Ensures that this collection contains the specified element (optional operation). Returns `true` if this collection changed as a result of the call. (Returns `false` if this collection does not permit duplicates and already contains the specified element.)

      Collections that support this operation may place limitations on what elements may be added to this collection. In particular, some collections will refuse to add `null` elements, and others will impose restrictions on the type of elements that may be added. Collection classes should clearly specify in their documentation any restrictions on what elements may be added.

      If a collection refuses to add a particular element for any reason other than that it already contains the element, it must throw an exception (rather than returning `false`). This preserves the invariant that a collection always contains the specified element after this call returns.

      Specified by:
        `add` in interface `java.util.Collection<T>`
      Specified by:
        `add` in interface `java.util.List<T>`
      Parameters:
        `o` - element whose presence in this collection is to be ensured.
      Returns:
        `true` if this collection changed as a result of the call
      Throws:
        `java.lang.UnsupportedOperationException` - `add` is not supported by this collection.
        `java.lang.ClassCastException` - class of the specified element prevents it from being added to this collection.
        `java.lang.NullPointerException` - if the specified element is null and this collection does not support null elements.
        `java.lang.IllegalArgumentException` - some aspect of this element prevents it from being added to this collection.

    - #### remove

          public boolean remove(java.lang.Object o)

      Removes a single instance of the specified element from this collection, if it is present (optional operation). More formally, removes an element `e` such that `(o==null ? e==null : o.equals(e))`, if this collection contains one or more such elements. Returns true if this collection contained the specified element (or equivalently, if this collection changed as a result of the call).
      Specified by:
        `remove` in interface `java.util.Collection<T>`
      Specified by:
        `remove` in interface `java.util.List<T>`
      Parameters:
        `o` - element to be removed from this collection, if present.
      Returns:
        `true` if this collection changed as a result of the call
      Throws:
        `java.lang.ClassCastException` - if the type of the specified element is incompatible with this collection (optional).
        `java.lang.NullPointerException` - if the specified element is null and this collection does not support null elements (optional).
        `java.lang.UnsupportedOperationException` - remove is not supported by this collection.

    - #### containsAll

          public boolean containsAll(@NotNull
                                     java.util.Collection<?> c)

      Returns `true` if this collection contains all of the elements in the specified collection.
      Specified by:
        `containsAll` in interface `java.util.Collection<T>`
      Specified by:
        `containsAll` in interface `java.util.List<T>`
      Parameters:
        `c` - collection to be checked for containment in this collection.
      Returns:
        `true` if this collection contains all of the elements in the specified collection
      Throws:
        `java.lang.ClassCastException` - if the types of one or more elements in the specified collection are incompatible with this collection (optional).
        `java.lang.NullPointerException` - if the specified collection contains one or more null elements and this collection does not support null elements (optional); or if the specified collection is `null`.
      See Also:
        `contains(Object)`

    - #### addAll

          public boolean addAll(@NotNull
                                java.util.Collection<? extends T> c)

      Adds all of the elements in the specified collection to this collection (optional operation). The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (This implies that the behavior of this call is undefined if the specified collection is this collection, and this collection is nonempty.)
      Specified by:
        `addAll` in interface `java.util.Collection<T>`
      Specified by:
        `addAll` in interface `java.util.List<T>`
      Parameters:
        `c` - elements to be inserted into this collection.
      Returns:
        `true` if this collection changed as a result of the call
      Throws:
        `java.lang.UnsupportedOperationException` - if this collection does not support the `addAll` method.
        `java.lang.ClassCastException` - if the class of an element of the specified collection prevents it from being added to this collection.
        `java.lang.NullPointerException` - if the specified collection contains one or more null elements and this collection does not support null elements, or if the specified collection is `null`.
        `java.lang.IllegalArgumentException` - some aspect of an element of the specified collection prevents it from being added to this collection.
      See Also:
        `add(Object)`

    - #### removeAll

          public boolean removeAll(@NotNull
                                   java.util.Collection<?> c)

      Removes all this collection's elements that are also contained in the specified collection (optional operation). After this call returns, this collection will contain no elements in common with the specified collection.
      Specified by:
        `removeAll` in interface `java.util.Collection<T>`
      Specified by:
        `removeAll` in interface `java.util.List<T>`
      Parameters:
        `c` - elements to be removed from this collection.
      Returns:
        `true` if this collection changed as a result of the call
      Throws:
        `java.lang.UnsupportedOperationException` - if the `removeAll` method is not supported by this collection.
        `java.lang.ClassCastException` - if the types of one or more elements in this collection are incompatible with the specified collection (optional).
        `java.lang.NullPointerException` - if this collection contains one or more null elements and the specified collection does not support null elements (optional); or if the specified collection is `null`.
      See Also:
        `remove(Object)`, `contains(Object)`

    - #### retainAll

          public boolean retainAll(@NotNull
                                   java.util.Collection<?> c)

      Retains only the elements in this collection that are contained in the specified collection (optional operation). In other words, removes from this collection all of its elements that are not contained in the specified collection.
      Specified by:
        `retainAll` in interface `java.util.Collection<T>`
      Specified by:
        `retainAll` in interface `java.util.List<T>`
      Parameters:
        `c` - elements to be retained in this collection.
      Returns:
        `true` if this collection changed as a result of the call
      Throws:
        `java.lang.UnsupportedOperationException` - if the `retainAll` method is not supported by this Collection.
        `java.lang.ClassCastException` - if the types of one or more elements in this collection are incompatible with the specified collection (optional).
        `java.lang.NullPointerException` - if this collection contains one or more null elements and the specified collection does not support null elements (optional); or if the specified collection is `null`.
      See Also:
        `remove(Object)`, `contains(Object)`

    - #### clear

          public void clear()

      Removes all of the elements from this collection (optional operation). This collection will be empty after this method returns unless it throws an exception.
      Specified by:
        `clear` in interface `java.util.Collection<T>`
      Specified by:
        `clear` in interface `java.util.List<T>`
      Throws:
        `java.lang.UnsupportedOperationException` - if the `clear` method is not supported by this collection.

    - #### addAll

          public boolean addAll(int index,
                                @NotNull
                                java.util.Collection<? extends T> c)

      Inserts all of the elements in the specified collection into this list at the specified position (optional operation). Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in this list in the order that they are returned by the specified collection's iterator. The behavior of this operation is undefined if the specified collection is modified while the operation is in progress. (Note that this will occur if the specified collection is this list, and it's nonempty.)
      Specified by:
        `addAll` in interface `java.util.List<T>`
      Parameters:
        `index` - index at which to insert the first element from the specified collection
        `c` - collection containing elements to be added to this list
      Returns:
        `true` if this list changed as a result of the call
      Throws:
        `java.lang.UnsupportedOperationException` - if the `addAll` operation is not supported by this list
        `java.lang.ClassCastException` - if the class of an element of the specified collection prevents it from being added to this list
        `java.lang.NullPointerException` - if the specified collection contains one or more null elements and this list does not permit null elements, or if the specified collection is null
        `java.lang.IllegalArgumentException` - if some property of an element of the specified collection prevents it from being added to this list
        `java.lang.IndexOutOfBoundsException` - if the index is out of range (`index < 0 || index > size()`)

    - #### get

          public T get(int index)

      Returns the element at the specified position in this list.
      Specified by:
        `get` in interface `java.util.List<T>`
      Parameters:
        `index` - index of the element to return
      Returns:
        the element at the specified position in this list
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of range (`index < 0 || index >= size()`)

    - #### set

          public T set(int index,
                       T element)

      Replaces the element at the specified position in this list with the specified element (optional operation).
      Specified by:
        `set` in interface `java.util.List<T>`
      Parameters:
        `index` - index of the element to replace
        `element` - element to be stored at the specified position
      Returns:
        the element previously at the specified position
      Throws:
        `java.lang.UnsupportedOperationException` - if the `set` operation is not supported by this list
        `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this list
        `java.lang.NullPointerException` - if the specified element is null and this list does not permit null elements
        `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this list
        `java.lang.IndexOutOfBoundsException` - if the index is out of range (`index < 0 || index >= size()`)

    - #### add

          public void add(int index,
                          T element)

      Inserts the specified element at the specified position in this list (optional operation). Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).
      Specified by:
        `add` in interface `java.util.List<T>`
      Parameters:
        `index` - index at which the specified element is to be inserted
        `element` - element to be inserted
      Throws:
        `java.lang.UnsupportedOperationException` - if the `add` operation is not supported by this list
        `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this list
        `java.lang.NullPointerException` - if the specified element is null and this list does not permit null elements
        `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this list
        `java.lang.IndexOutOfBoundsException` - if the index is out of range (`index < 0 || index > size()`)

    - #### remove

          public T remove(int index)

      Removes the element at the specified position in this list (optional operation). Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list.
      Specified by:
        `remove` in interface `java.util.List<T>`
      Parameters:
        `index` - the index of the element to be removed
      Returns:
        the element previously at the specified position
      Throws:
        `java.lang.UnsupportedOperationException` - if the `remove` operation is not supported by this list
        `java.lang.IndexOutOfBoundsException` - if the index is out of range (`index < 0 || index >= size()`)

    - #### indexOf

          public int indexOf(java.lang.Object o)

      Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element. More formally, returns the lowest index `i` such that `(o==null ? get(i)==null : o.equals(get(i)))`, or -1 if there is no such index.
      Specified by:
        `indexOf` in interface `java.util.List<T>`
      Parameters:
        `o` - element to search for
      Returns:
        the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element
      Throws:
        `java.lang.ClassCastException` - if the type of the specified element is incompatible with this list (optional)
        `java.lang.NullPointerException` - if the specified element is null and this list does not permit null elements (optional)

    - #### lastIndexOf

          public int lastIndexOf(java.lang.Object o)

      Returns the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element. More formally, returns the highest index `i` such that `(o==null ? get(i)==null : o.equals(get(i)))`, or -1 if there is no such index.
      Specified by:
        `lastIndexOf` in interface `java.util.List<T>`
      Parameters:
        `o` - element to search for
      Returns:
        the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element
      Throws:
        `java.lang.ClassCastException` - if the type of the specified element is incompatible with this list (optional)
        `java.lang.NullPointerException` - if the specified element is null and this list does not permit null elements (optional)

    - #### subList

          @NotNull
          public java.util.List<T> subList(int fromIndex,
                                                    int toIndex)

      Returns a view of the portion of this list between the specified `fromIndex`, inclusive, and `toIndex`, exclusive. (If `fromIndex` and `toIndex` are equal, the returned list is empty.) The returned list is backed by this list, so non-structural changes in the returned list are reflected in this list, and vice-versa. The returned list supports all of the optional list operations supported by this list.

      This method eliminates the need for explicit range operations (of the sort that commonly exist for arrays). Any operation that expects a list can be used as a range operation by passing a subList view instead of a whole list. For example, the following idiom removes a range of elements from a list:

                list.subList(from, to).clear();

      Similar idioms may be constructed for `indexOf` and `lastIndexOf`, and all of the algorithms in the `Collections` class can be applied to a subList.

      The semantics of the list returned by this method become undefined if the backing list (i.e., this list) is structurally modified in any way other than via the returned list. (Structural modifications are those that change the size of this list, or otherwise perturb it in such a fashion that iterations in progress may yield incorrect results.)

      Specified by:
        `subList` in interface `java.util.List<T>`
      Parameters:
        `fromIndex` - low endpoint (inclusive) of the subList
        `toIndex` - high endpoint (exclusive) of the subList
      Returns:
        a view of the specified range within this list
      Throws:
        `java.lang.UnsupportedOperationException` - sublisting is not supported

    - #### sort

          public void sort(java.util.Comparator<? super T> c)

      Specified by:
        `sort` in interface `java.util.List<T>`

    - #### create

          @NotNull
          public static <U> SynchronizedList<U> create(@NotNull
                                                                java.util.List<U> basicList)

      Create a synchronized list from the given basic list.
      Type Parameters:
        `U` - type of list
      Parameters:
        `basicList` - basic list
      Returns:
        synchronized list