org.apache.myfaces.trinidad.util

## Class CollectionUtils

- java.lang.Object
- - org.apache.myfaces.trinidad.util.CollectionUtils

-     public final class CollectionUtils
      extends Object

  This class contains Collection utilities.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `CollectionUtils.AccessHookMap<K,V>`
    `protected static class` | `CollectionUtils.CompositeCollection<E>` Note: Requires contents to be disjoint!
    `protected static class` | `CollectionUtils.CompositeSet<E>` Note: Requires contents to be disjoint!
    `protected static class` | `CollectionUtils.DelegatingCollection<E>`
    `protected static class` | `CollectionUtils.DelegatingEntry<K,V>`
    `protected static class` | `CollectionUtils.DelegatingMap<K,V>`
    `protected static class` | `CollectionUtils.ExternalAccessHookMap<K,V>`
    `protected static class` | `CollectionUtils.LenientCompositeSet<E>` Live composite set where both sets are allowed to be disjoint.
    `static interface` | `CollectionUtils.MapMutationHooks<K,V>` Interface for trapping mutations to a Map.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <T> ArrayList<T>` | `arrayList(Iterator<T> iterator)` Returns an ArrayList containing all of the elements of the Iterator
    `static <T> Set<T>` | `asSet(T... a)` Returns a minimal Set containing the elements passed in.
    `static <T> Set<T>` | `asUnmodifiableSet(T... a)` Returns an unmodifiable Set containing the elements passed in.
    `static <T> Set<T>` | `compositeSet(Set<T> primarySet, Set<T> secondarySet)` Given two disjoint sets, returns a live composition of the two Sets that maintains the disjoint invariant.
    `protected static <T> T[]` | `copyOf(T[] original, int newLength)`
    `protected static <T,U> T[]` | `copyOf(U[] original, int newLength, Class<? extends T[]> newType)`
    `static <T> Iterator<T>` | `emptyIterator()` Returns an empty, unmodifiable, Iterator.
    `static <T> ListIterator<T>` | `emptyListIterator()` Returns an empty, unmodifiable, ListIterator.
    `static <T> Queue<T>` | `emptyQueue()` Returns an empty, unmodifiable, Serializable Queue.
    `static <K,V> Map<K,V>` | `getCheckedSerializationMap(Map<K,V> map)` Creates a Map that dynamically verifies that all keys and values added to it will succeed Serialization.
    `static <K,V> Map<K,V>` | `getCheckedSerializationMap(Map<K,V> map, boolean requireSerializable)` Creates a Map that dynamically verifies that all keys and values added to it will succeed Serialization.
    `static <T> Collection<T>` | `getSerializableCollection(Collection<T> c)` Returns a Collection based on the passed in Collection `c`, guaranteed to be Serializable.
    `static <T> List<T>` | `getSerializableList(List<T> l)` Returns a List based on the passed in List `l`, guaranteed to be Serializable.
    `static <E> int` | `getUnionSize(Collection<? extends E> firstCollection, Collection<? extends E> secondCollection)` Given two Collections, return the size of their union
    `static <K,V> Map<K,V>` | `newMutationHookedMap(Map<K,V> map, CollectionUtils.MapMutationHooks<K,V> hooks)` Creates a new Map that informs the MapMutationHooks of any direct mutations.
    `static <T> List<T>` | `newSerializableList(List<T> l)` Returns a List based on the passed in List `l`, guaranteed to be Serializable.
    `static <T> Set<T>` | `overlappingCompositeSet(Set<T> primarySet, Set<T> secondarySet)` Given two possibly overlapping sets, returns a live composition of the two Sets.
    `static <K,V> Iterator<V>` | `subsetValueIterator(Map<? extends K,? extends V> map, Collection<? extends K> allowedKeys)` Return an iterator of the values in `map` with entries in `allowedLeys`
    `static <K,V> Iterator<V>` | `subsetValueIterator(Map<? extends K,? extends V> map, Iterator<? extends K> allowedKeys)` Return an iterator of the values in `map` with entries in `allowedLeys` The values returned in the iterator will be in the same order as their corresponding keys in allowedKeys.
    `static <T> T[]` | `toArray(Iterator<? extends T> iterator, Class<T> type)` Returns an array containing all of the elements of the Iterator
    `static <E extends Enum<E>> Set<E>` | `unmodifiableCopyOfEnumSet(Set<E> s)` Returns an unmodifiable versions of the Set of Enums.

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

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

- - ### Method Detail

    - #### arrayList

          public static <T> ArrayList<T> arrayList(Iterator<T> iterator)

      Returns an ArrayList containing all of the elements of the Iterator
      Parameters:
        `iterator` - Iterator to copy the contexts of
      Returns:
        an ArrayList containing a copy of the iterator contents

    - #### toArray

          public static <T> T[] toArray(Iterator<? extends T> iterator,
                        Class<T> type)

      Returns an array containing all of the elements of the Iterator
      Parameters:
        `iterator` - Iterator to copy the contexts of
      Returns:
        an array containing a copy of the iterator contents

    - #### emptyQueue

          public static <T> Queue<T> emptyQueue()

      Returns an empty, unmodifiable, Serializable Queue.
      Returns:
        an empty, unmodifiable, Serializable Queue.

    - #### emptyIterator

          public static <T> Iterator<T> emptyIterator()

      Returns an empty, unmodifiable, Iterator.
      Returns:
        an empty, unmodifiable, Iterator.

    - #### emptyListIterator

          public static <T> ListIterator<T> emptyListIterator()

      Returns an empty, unmodifiable, ListIterator.
      Returns:
        an empty, unmodifiable, ListIterator.

    - #### subsetValueIterator

          public static <K,V> Iterator<V> subsetValueIterator(Map<? extends K,? extends V> map,
                                              Collection<? extends K> allowedKeys)

      Return an iterator of the values in `map` with entries in `allowedLeys`
      Type Parameters:
        `K` - Map key type
        `V` - Map value type
      Parameters:
        `map` - Map of keys and values
        `allowedKeys` - Collection of keys to return values for if present in map
      Returns:
        Iterator of values for which the map contains a key from allowedKeys

    - #### subsetValueIterator

          public static <K,V> Iterator<V> subsetValueIterator(Map<? extends K,? extends V> map,
                                              Iterator<? extends K> allowedKeys)

      Return an iterator of the values in `map` with entries in `allowedLeys` The values returned in the iterator will be in the same order as their corresponding keys in allowedKeys.
      Type Parameters:
        `K` - Map key type
        `V` - Map value type
      Parameters:
        `map` - Map of keys and values
        `allowedKeys` - Iterator of keys to return values for if present in map
      Returns:
        Iterator of values for which the map contains a key from allowedKeys

    - #### asSet

          public static <T> Set<T> asSet(T... a)

      Returns a minimal Set containing the elements passed in. There is no guarantee that the returned set is mutable or immutable.
      Type Parameters:
        `T` -
      Parameters:
        `a` - The elements to add to the Set
      Returns:
        A set containing the elements passed in.
      See Also:
        `asUnmodifiableSet(T...)`

    - #### asUnmodifiableSet

          public static <T> Set<T> asUnmodifiableSet(T... a)

      Returns an unmodifiable Set containing the elements passed in.
      Type Parameters:
        `T` -
      Parameters:
        `a` - The elements to add to the Set
      Returns:
        A set containing the elements passed in.
      See Also:
        `asSet(T...)`

    - #### unmodifiableCopyOfEnumSet

          public static <E extends Enum<E>> Set<E> unmodifiableCopyOfEnumSet(Set<E> s)

      Returns an unmodifiable versions of the Set of Enums. If the contents of the set are known to be unmodifiable by the caller in any way, the set itself will be retured, otherwise an unmodifiable copy of the Set will be returned.
      Parameters:
        `s` - Set to get the tamper-proof version of
      Returns:
        An unmodifiable tamper-proof version of the set

    - #### compositeSet

          public static <T> Set<T> compositeSet(Set<T> primarySet,
                                Set<T> secondarySet)

      Given two disjoint sets, returns a live composition of the two Sets that maintains the disjoint invariant. If both Sets are Serializable, the returned implementation will be Serializable as well. The returned Set implementation is not thread safe.
      Parameters:
        `primarySet` - The Set that modifications will be applied to
        `secondarySet` - The other Set. Modifications will be applied in response to changes to the primary set to ensure that the disjoint invariant is maintained
      Returns:
        The composition of the two disjoint Sets
      Throws:
        `NullPointerException` - of primarySet or secondarySet are `null`
      See Also:
        `overlappingCompositeSet(java.util.Set<T>, java.util.Set<T>)`

    - #### overlappingCompositeSet

          public static <T> Set<T> overlappingCompositeSet(Set<T> primarySet,
                                           Set<T> secondarySet)

      Given two possibly overlapping sets, returns a live composition of the two Sets. If both Sets are Serializable, the returned implementation will be Serializable as well. The lack of the disjoint invariant makes operations such as calculating the size of the Set expensive. If the disjoint invariant can be guaranteed, `compositeSet` should be used instead. The returned Set implementation is not thread safe.
      Parameters:
        `primarySet` - The Set that modifications will be applied to
        `secondarySet` - The other Set. If a removal is performed on the primarySet, it will also be applied to the secondarySet to ensure that the element is logically removed from the Set.
      Returns:
        The composition of the two possibly overallping Sets
      Throws:
        `NullPointerException` - of primarySet or secondarySet are `null`
      See Also:
        `compositeSet(java.util.Set<T>, java.util.Set<T>)`

    - #### getSerializableCollection

          public static <T> Collection<T> getSerializableCollection(Collection<T> c)

      Returns a Collection based on the passed in Collection `c`, guaranteed to be Serializable. If `c` is Serializable, `c` will be returned, otherwise, `c` will be wrapped in a Collection that implements Serializable and upon Serialization the contents of `c` will be copied into the result.

      The results is very similar to creating a new ArrayList with the contents of `c`, but no wrapper is created unless necessary and the actual creation of the Serializable copy is deferred until Serialization occurs.

      Parameters:
        `c` - The Collection to get a Serializable version of
      Returns:
        A Serializable version of Collection `c`
      See Also:
        `getSerializableList(java.util.List<T>)`

    - #### newSerializableList

          public static <T> List<T> newSerializableList(List<T> l)

      Returns a List based on the passed in List `l`, guaranteed to be Serializable. List `l` will be wrapped in a List that implements Serializable and upon Serialization the contents of `l` will be copied into the result.

      If `l` implements RandomAccess, any returned List will also implement RandomAccess.

      The results is very similar to creating a new ArrayList with the contents of `l`, but no wrapper is created unless necessary and the actual creation of the Serializable copy is deferred until Serialization occurs.

      Code that calls List.subList() and needs the result to be Serializable should always use `newSerializableList` rather than `getSerializableList` because the `java.util.Collections` implementations of `checkedList`, `unmodifiableList`, and `synchronizedList` all lie and always implement Serializable, regardless of the serializability of their backing List.

      Parameters:
        `l` - The List to get a Serializable version of
      Returns:
        A Serializable version of List `l`
      See Also:
        `getSerializableList(java.util.List<T>)`, `getSerializableCollection(java.util.Collection<T>)`

    - #### getSerializableList

          public static <T> List<T> getSerializableList(List<T> l)

      Returns a List based on the passed in List `l`, guaranteed to be Serializable. If `l` is Serializable, `l` will be returned, otherwise, `l` will be wrapped in a List that implements Serializable and upon Serialization the contents of `l` will be copied into the result.

      If `l` implements RandomAccess, any returned List will also implement RandomAccess.

      The results is very similar to creating a new ArrayList with the contents of `l`, but no wrapper is created unless necessary and the actual creation of the Serializable copy is deferred until Serialization occurs.

      Code that calls List.subList() and needs the result to be Serializable should always use `newSerializableList` rather than `getSerializableList` because the `java.util.Collections` implementations of `checkedList`, `unmodifiableList`, and `synchronizedList` all lie and always implement Serializable, regardless of the serializability of their backing List.

      Parameters:
        `l` - The List to get a Serializable version of
      Returns:
        A Serializable version of List `l`
      See Also:
        `newSerializableList(java.util.List<T>)`, `getSerializableCollection(java.util.Collection<T>)`

    - #### newMutationHookedMap

          public static <K,V> Map<K,V> newMutationHookedMap(Map<K,V> map,
                                            CollectionUtils.MapMutationHooks<K,V> hooks)

      Creates a new Map that informs the MapMutationHooks of any direct mutations. Mutations to the underlying Map will not be caught. If the base map is Serializable, the returned Map will be Serializable
      Type Parameters:
        `K` - type of the keys of the Map
        `V` - type of the values of the Map
      Parameters:
        `map` - Underlying map to trap mutations of
        `hooks` - MapMutationHooks to inform of mutations to the returned Map
      Returns:
        a new Map that traps the mutations to the underlying Map
      Throws:
        `NullPointerException` - if map or hooks are null

    - #### getCheckedSerializationMap

          public static <K,V> Map<K,V> getCheckedSerializationMap(Map<K,V> map)

      Creates a Map that dynamically verifies that all keys and values added to it will succeed Serialization. The validations checks not only that the keys and values added to the Map implement Serializable, but that these instances will actually succeed Serialization.

      This checking can be defeated by either modifying the backing map directly or by modifying an object added to the checked Map after adding it.

      Parameters:
        `map` - Map to wrap for Serialization validation
      Returns:
        Map where all modifications are checked to ensure that they will succeeed if serialized

    - #### getCheckedSerializationMap

          public static <K,V> Map<K,V> getCheckedSerializationMap(Map<K,V> map,
                                                  boolean requireSerializable)

      Creates a Map that dynamically verifies that all keys and values added to it will succeed Serialization. The validations checks not only that the keys and values added to the Map implement Serializable, but that these instances will actually succeed Serialization.

      This checking can be defeated by either modifying the backing map directly or by modifying an object added to the checked Map after adding it.

      Parameters:
        `map` - Map to wrap for Serialization validation
        `requireSerializable` - if `true`, require that all values in the map implement Serializable.
      Returns:
        Map where modifications are checked to ensure that they will succeeed if serialized

    - #### getUnionSize

          public static <E> int getUnionSize(Collection<? extends E> firstCollection,
                             Collection<? extends E> secondCollection)

      Given two Collections, return the size of their union
      Parameters:
        `firstCollection` - The first collection. `null` is allowed.
        `secondCollection` - The second collection. `null` is allowed.
      Returns:

    - #### copyOf

          protected static <T> T[] copyOf(T[] original,
                       int newLength)

    - #### copyOf

          protected static <T,U> T[] copyOf(U[] original,
                         int newLength,
                         Class<? extends T[]> newType)

Copyright © 2001-2017 The Apache Software Foundation. All Rights Reserved.