Class BreakableCollection<E>

java.lang.Object
org.soliscode.test.OptionalMethodSupport
org.soliscode.test.breakable.AbstractBreakable
org.soliscode.test.breakable.BreakableIterable<E>
org.soliscode.test.breakable.BreakableCollection<E>
Type Parameters:
E - The elements type for the Collection.
All Implemented Interfaces:
Iterable<E>, Collection<E>, Breakable, SupportedMethods
Direct Known Subclasses:
BreakableSequencedCollection
public class BreakableCollection<E> extends BreakableIterable<E> implements Collection<E>

A collection that can be broken in well-defined ways in order to test collection utilities or testing classes.

Breaks

The breaks that are supported for this class are listed in the description of the method that they impact. In addition it supports the breaks in the BreakableIterable, BreakableIterator, and BreakableSpliterator classes. Any iterator or spliterator breaks that are added to this iterable will be passes along to iterator or spliterator instances that are created.

Any breaks that are not listed in the supported classes can be added to an instance of BreakableCollection, but will not have any impact on how it functions.

Builder methods are provided to make declaring a broken collection easier, for example:

    BreakableCollection<Integer> broken = Breakables.buildCollection.of(1, 2)
        .withBreak(CollectionBreaks,EMPTY_ALWAYS_RETURNS_TRUE)
        .build();
Since:
1.0.0
Author:
evanbergstrom
See Also:

  • Field Details

    • ADD_DOES_NOT_ADD_ELEMENT

      public static final Break ADD_DOES_NOT_ADD_ELEMENT
      The add method does not add an element to the collection
      See Also:

    • ADD_ALWAYS_RETURNS_TRUE

      public static final Break ADD_ALWAYS_RETURNS_TRUE
      The add method always return a result of true, even if the element is not added.
      See Also:

    • ADD_ALWAYS_RETURNS_FALSE

      public static final Break ADD_ALWAYS_RETURNS_FALSE
      The add method always return a result of false, even if the element is added.
      See Also:

    • ADD_ALWAYS_RETURNS_OPPOSITE_VALUE

      public static final Break ADD_ALWAYS_RETURNS_OPPOSITE_VALUE
      The add method always returns the opposite of the appropriate result.
      See Also:

    • ADD_ALL_DOES_NOT_ADD_ANY_ELEMENTS

      public static final Break ADD_ALL_DOES_NOT_ADD_ANY_ELEMENTS
      The addAll method will not add any elements to the collection
      See Also:

    • ADD_ALL_ALWAYS_RETURNS_TRUE

      public static final Break ADD_ALL_ALWAYS_RETURNS_TRUE
      The addAll method always return a result of true, even if the element is not added.
      See Also:

    • ADD_ALL_ALWAYS_RETURNS_FALSE

      public static final Break ADD_ALL_ALWAYS_RETURNS_FALSE
      The addAll method always return a result of false, even if the element is added.
      See Also:

    • ADD_ALL_ALWAYS_RETURNS_OPPOSITE_VALUE

      public static final Break ADD_ALL_ALWAYS_RETURNS_OPPOSITE_VALUE
      The addAll method always returns the opposite of the appropriate result.
      See Also:

    • ADD_ALL_SKIPS_FIRST_ELEMENT

      public static final Break ADD_ALL_SKIPS_FIRST_ELEMENT
      The addAll method skips the first element to be added.
      See Also:

    • ADD_ALL_SKIPS_LAST_ELEMENT

      public static final Break ADD_ALL_SKIPS_LAST_ELEMENT
      The addAll method skips the last element to be added.
      See Also:

    • CLEAR_DOES_NOT_REMOVE_ANY_ELEMENTS

      public static final Break CLEAR_DOES_NOT_REMOVE_ANY_ELEMENTS
      The clear method doers not remove any elements,
      See Also:

    • CLEAR_SKIPS_FIRST_ELEMENT

      public static final Break CLEAR_SKIPS_FIRST_ELEMENT
      The clear method skips the first element,
      See Also:

    • CLEAR_SKIPS_LAST_ELEMENT

      public static final Break CLEAR_SKIPS_LAST_ELEMENT
      The clear method skips the last element,
      See Also:

    • CONTAINS_ALWAYS_RETURNS_TRUE

      public static final Break CONTAINS_ALWAYS_RETURNS_TRUE
      The contains method will always return a true.
      See Also:

    • CONTAINS_ALWAYS_RETURNS_FALSE

      public static final Break CONTAINS_ALWAYS_RETURNS_FALSE
      The contains method will always return a false.
      See Also:

    • CONTAINS_RETURNS_OPPOSITE_VALUE

      public static final Break CONTAINS_RETURNS_OPPOSITE_VALUE
      The contains method will return the opposite value.
      See Also:

    • CONTAINS_ALL_ALWAYS_RETURNS_TRUE

      public static final Break CONTAINS_ALL_ALWAYS_RETURNS_TRUE
      The containsAll method will always return a true.
      See Also:

    • CONTAINS_ALL_ALWAYS_RETURNS_FALSE

      public static final Break CONTAINS_ALL_ALWAYS_RETURNS_FALSE
      The containsAll method will always return a false.
      See Also:

    • CONTAINS_ALL_RETURNS_OPPOSITE_VALUE

      public static final Break CONTAINS_ALL_RETURNS_OPPOSITE_VALUE
      The containsAll method will return the opposite value.
      See Also:

    • IS_EMPTY_ALWAYS_RETURNS_TRUE

      public static final Break IS_EMPTY_ALWAYS_RETURNS_TRUE
      The isEmpty method will always return a true.
      See Also:

    • IS_EMPTY_ALWAYS_RETURNS_FALSE

      public static final Break IS_EMPTY_ALWAYS_RETURNS_FALSE
      The isEmpty method will always return a false.
      See Also:

    • IS_EMPTY_RETURNS_OPPOSITE_VALUE

      public static final Break IS_EMPTY_RETURNS_OPPOSITE_VALUE
      The isEmpty method will return the opposite value.
      See Also:

    • REMOVE_DOES_NOT_REMOVE_ELEMENT

      public static final Break REMOVE_DOES_NOT_REMOVE_ELEMENT
      The remove method will not remove an element to the collection
      See Also:

    • REMOVE_ALWAYS_RETURNS_TRUE

      public static final Break REMOVE_ALWAYS_RETURNS_TRUE
      The remove method always return a result of true, even if the element is not removed.
      See Also:

    • REMOVE_ALWAYS_RETURNS_FALSE

      public static final Break REMOVE_ALWAYS_RETURNS_FALSE
      The remove method always return a result of false, even if the element is removed.
      See Also:

    • REMOVE_ALWAYS_RETURNS_OPPOSITE_VALUE

      public static final Break REMOVE_ALWAYS_RETURNS_OPPOSITE_VALUE
      The remove method always returns the opposite of the appropriate result.
      See Also:

    • REMOVE_ALL_DOES_NOT_REMOVE_ANY_ELEMENTS

      public static final Break REMOVE_ALL_DOES_NOT_REMOVE_ANY_ELEMENTS
      The removeAll method will not remove any elements to the collection
      See Also:

    • REMOVE_ALL_ALWAYS_RETURNS_TRUE

      public static final Break REMOVE_ALL_ALWAYS_RETURNS_TRUE
      The removeAll method always return a result of true, even if the element is not removed.
      See Also:

    • REMOVE_ALL_ALWAYS_RETURNS_FALSE

      public static final Break REMOVE_ALL_ALWAYS_RETURNS_FALSE
      The removeAll method always return a result of false, even any of the elements are removed.
      See Also:

    • REMOVE_ALL_ALWAYS_RETURNS_OPPOSITE_VALUE

      public static final Break REMOVE_ALL_ALWAYS_RETURNS_OPPOSITE_VALUE
      The removeAll method always returns the opposite of the appropriate result.
      See Also:

    • REMOVE_ALL_SKIPS_FIRST_ELEMENT

      public static final Break REMOVE_ALL_SKIPS_FIRST_ELEMENT
      The removeAll method skips the first element to be removed.
      See Also:

    • REMOVE_ALL_SKIPS_LAST_ELEMENT

      public static final Break REMOVE_ALL_SKIPS_LAST_ELEMENT
      The removeAll method skips the last element to be removed.
      See Also:

    • REMOVE_IF_DOES_NOT_REMOVE_ANY_ELEMENTS

      public static final Break REMOVE_IF_DOES_NOT_REMOVE_ANY_ELEMENTS
      The removeIf method will not remove any elements to the collection
      See Also:

    • REMOVE_IF_ALWAYS_RETURNS_TRUE

      public static final Break REMOVE_IF_ALWAYS_RETURNS_TRUE
      The removeIf method always return a result of true, even if the element is not removed.
      See Also:

    • REMOVE_IF_ALWAYS_RETURNS_FALSE

      public static final Break REMOVE_IF_ALWAYS_RETURNS_FALSE
      The removeIf method always return a result of false, even any of the elements are removed.
      See Also:

    • REMOVE_IF_ALWAYS_RETURNS_OPPOSITE_VALUE

      public static final Break REMOVE_IF_ALWAYS_RETURNS_OPPOSITE_VALUE
      The removeIf method always returns the opposite of the appropriate result.
      See Also:

    • REMOVE_IF_SKIPS_FIRST_ELEMENT

      public static final Break REMOVE_IF_SKIPS_FIRST_ELEMENT
      The removeIf method skips the first element to be removed.
      See Also:

    • REMOVE_IF_SKIPS_LAST_ELEMENT

      public static final Break REMOVE_IF_SKIPS_LAST_ELEMENT
      The removeIf method skips the last element to be removed.
      See Also:

    • RETAIN_ALL_DOES_NOT_RETAIN_ANY_ELEMENTS

      public static final Break RETAIN_ALL_DOES_NOT_RETAIN_ANY_ELEMENTS
      The retainAll method will not retain any elements to the collection
      See Also:

    • RETAIN_ALL_ALWAYS_RETURNS_TRUE

      public static final Break RETAIN_ALL_ALWAYS_RETURNS_TRUE
      The retainAll method always return a result of true, even if the collection is not modified.
      See Also:

    • RETAIN_ALL_ALWAYS_RETURNS_FALSE

      public static final Break RETAIN_ALL_ALWAYS_RETURNS_FALSE
      The retainAll method always return a result of false, even the collection is modified
      See Also:

    • RETAIN_ALL_ALWAYS_RETURNS_OPPOSITE_VALUE

      public static final Break RETAIN_ALL_ALWAYS_RETURNS_OPPOSITE_VALUE
      The retainAll method always returns the opposite of the appropriate result.
      See Also:

    • RETAIN_ALL_SKIPS_FIRST_ELEMENT

      public static final Break RETAIN_ALL_SKIPS_FIRST_ELEMENT
      The retainAll method skips the first element to be retained.
      See Also:

    • RETAIN_ALL_SKIPS_LAST_ELEMENT

      public static final Break RETAIN_ALL_SKIPS_LAST_ELEMENT
      The retainAll method skips the last element to be retained.
      See Also:

    • SIZE_ALWAYS_RETURNS_ZERO

      public static final Break SIZE_ALWAYS_RETURNS_ZERO
      The size method will always return zero.
      See Also:

    • SIZE_ALWAYS_RETURNS_CONSTANT_VALUE

      public static final Break SIZE_ALWAYS_RETURNS_CONSTANT_VALUE
      The size method will always return a constant value.
      See Also:

    • TO_ARRAY_RETURNS_EMPTY_ARRAY

      public static final Break TO_ARRAY_RETURNS_EMPTY_ARRAY
      The 'toArray' method will always return an empty array
      See Also:

    • TO_ARRAY_RETURNS_NULL

      public static final Break TO_ARRAY_RETURNS_NULL
      The 'toArray' method will always return null
      See Also:

    • TO_ARRAY_MISSING_FIRST_ELEMENT

      public static final Break TO_ARRAY_MISSING_FIRST_ELEMENT
      The 'toArray' method will always return an array missing the first element
      See Also:

    • TO_ARRAY_MISSING_LAST_ELEMENT

      public static final Break TO_ARRAY_MISSING_LAST_ELEMENT
      The 'toArray' method will always return an array missing the last element
      See Also:

    • TO_ARRAY_STORE_DOES_NOT_COPY_ELEMENTS

      public static final Break TO_ARRAY_STORE_DOES_NOT_COPY_ELEMENTS
      The 'toArray([])' method does not copy the elements into the array
      See Also:

    • TO_ARRAY_STORE_RETURNS_EMPTY_ARRAY

      public static final Break TO_ARRAY_STORE_RETURNS_EMPTY_ARRAY
      The 'toArray' method will always return an empty array
      See Also:

    • TO_ARRAY_STORE_RETURNS_NULL

      public static final Break TO_ARRAY_STORE_RETURNS_NULL
      The 'toArray' method will always return null
      See Also:

    • TO_ARRAY_STORE_MISSING_FIRST_ELEMENT

      public static final Break TO_ARRAY_STORE_MISSING_FIRST_ELEMENT
      The 'toArray' method will always return an array missing the first element
      See Also:

    • TO_ARRAY_STORE_MISSING_LAST_ELEMENT

      public static final Break TO_ARRAY_STORE_MISSING_LAST_ELEMENT
      The 'toArray' method will always return an array missing the last element
      See Also:

  • Constructor Details

    • BreakableCollection

      public BreakableCollection()
      Creates an empty collection that has no breaks.

    • BreakableCollection

      public BreakableCollection(@NotNull @NotNull BreakableCollection<E> other)
      Creates a breakable collection from an existing instance.
      Parameters:
      other - the breakable collection to copy.

    • BreakableCollection

      public BreakableCollection(@NotNull @NotNull Collection<E> collection)
      Creates a breakable iterable from an iterable.
      Parameters:
      collection - the iterator to use for the elements.

    • BreakableCollection

      public BreakableCollection(@NotNull @NotNull Collection<E> c, @NotNull @NotNull Collection<Break> breaks, int characteristics)
      Creates a BreakableCollection from en existing collection and specifying the breaks and collection characteristics. Rather than calling this constructor directly, consider using the builder BreakableCollection.Builder.
      Parameters:
      c - the initial elements for the breakable collection.
      breaks - the breaks for the collection.
      characteristics - the characteristics for the collection.
      Throws:
      NullPointerException - if either the c or the breaks parameters are null.

  • Method Details

    • permitsNulls

      public boolean permitsNulls()
      Indicates if the collection permits null values as elements.
      Returns:
      true if the collection permits null elements, false if it does not.

    • setPermitsNulls

      public void setPermitsNulls(boolean permitsNulls)
      Sets how the collection handles null elements.
      Parameters:
      permitsNulls - specifies if the collection permits null values, true if null values are permitted and false if they are not.

    • permitsDuplicates

      public boolean permitsDuplicates()
      Indicates if the collection permits duplicate elements.
      Returns:
      true if the collection permits duplicate elements, false if it does not.

    • setPermitsDuplicates

      public void setPermitsDuplicates(boolean permitsDuplicates)
      Sets how the collection handles duplicate elements.
      Parameters:
      permitsDuplicates - specifies if the collection permits duplicate values, true if duplicate values are permitted and false if they are not.

    • permitsIncompatibleTypes

      public boolean permitsIncompatibleTypes()
      Indicates if the collection permits elements with incompatible types as arguments.
      Returns:
      true if the collection permits elements with incompatible types, false if it does not.

    • setPermitsIncompatibleTypes

      public void setPermitsIncompatibleTypes(boolean permitsIncompatibleTypes)
      Sets how the collection handles elements with incompatible types as arguments.
      Parameters:
      permitsIncompatibleTypes - specifies if the collection permits elements with incompatible types as arguments, true if duplicate values are permitted and false if they are not.

    • size

      public int size()

      Implements the size method from the Collection interface. This method can be broken using the following collection breaks:

      A collection that has any of these breaks can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .withBreak(SIZE_ALWAYS_RETURNS_ZERO)
        .build();
      Specified by:
      size in interface Collection<E>
      Returns:
      The number of elements in the collection, or a different value if the collection has been broken.
      See Also:

    • isEmpty

      public boolean isEmpty()

      Implements the isEmpty method from the Collection interface. This method can be broken using the following collection breaks:

      A collection that has any of these breaks can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .withBreak(IS_EMPTY_RETURNS_OPPOSITE_VALUE)
        .build();
      Specified by:
      isEmpty in interface Collection<E>
      Returns:
      The number of elements in the collection, or a different value if the collection has been broken.
      See Also:

    • contains

      public boolean contains(Object o)

      Implements the contains method from the Collection interface. This method can be broken using the following collection breaks:

      A collection that has any of these breaks can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .withBreak(CONTAINS_ALWAYS_RETURNS_FALSE)
        .build();
      Specified by:
      contains in interface Collection<E>
      Returns:
      true if this collection contains the specified element or false if it does not, or some other value if the collection is broken.
      Throws:
      NullPointerException - if the argument is null and collection does not support null values.
      ClassCastException - if the argument is an incompatible type and the collection does not support incompatible types.
      See Also:

    • toArray

      public Object[] toArray()

      Implements the toArray method from the Collection interface. This method can be broken using the following collection breaks:

      A collection that has any of these breaks can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .withBreak(TO_ARRAY_RETURNS_NULL)
        .build();
      Specified by:
      toArray in interface Collection<E>
      Returns:
      An array with the elements from the collection, or some other value if the collection is broken.
      See Also:

    • toArray

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

      Implements the toArray method from the Collection interface. This method can be broken using the following collection breaks:

      A collection that has any of these breaks can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .withBreak(TO_ARRAY_STORE_RETURNS_NULL)
        .build();
      Specified by:
      toArray in interface Collection<E>
      Returns:
      An array with the elements from the collection, or some other value if the collection is broken.
      See Also:

    • add

      public boolean add(E e)

      Implements the add method from the Collection interface. This method can be broken using the following collection breaks:

      A collection that has any of these breaks can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .withBreak(ADD_DOES_NOT_ADD_ELEMENT)
        .build();

      This is an optional method of the Collection interface. Support for this method can be removed using the optional method identifier CollectionMethods.Add. A collection that does not support the add method can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .doesNotSupportsMethod(OptionalCollectionMethod.Add)
        .build();
      Specified by:
      add in interface Collection<E>
      Returns:
      'true' if the element is added, 'false' if it isn't, or possibly a different value if the collection has been broken.
      Throws:
      NullPointerException - if the argument is null and collection does not support null values.
      IllegalArgumentException - if the argument is already contained in the collections, and it does not support duplicate values.
      ClassCastException - if the argument is an incompatible type and the collection does not support incompatible types.
      UnsupportedOperationException - if this collection does not support this method.

    • remove

      public boolean remove(Object o)

      Implements the remove method from the Collection interface. This method can be broken using the following collection breaks:

      A collection that has any of these breaks can be constructed using the builder:

          Collection<Integer> collection = BreakableCollection.of(1,2,3,4,5)
        .withBreak(REMOVE_DOES_NOT_REMOVE_ELEMENT)
        .build();

      This is an optional method of the Collection interface. Support for this method can be removed using the optional method identifier CollectionMethods.Remove. A collection that does not support the remove method can be constructed using the builder:

          Collection<Integer> collection = BreakableCollection.of(1,2,3,4,5)
        .doesNotSupportsMethod(OptionalCollectionMethod.Remove)
        .build();
      Specified by:
      remove in interface Collection<E>
      Returns:
      'true' if the element is removed, 'false' if it isn't, or possibly a different value if the collection has been broken.
      Throws:
      NullPointerException - if the argument is null and collection does not support null values.
      ClassCastException - if the argument is an incompatible type and the collection does not support incompatible types.

    • containsAll

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

      Implements the containsAll method from the Collection interface. This method can b broken using the following collection breaks:

      A collection that has any of these breaks can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .withBreak(CONTAINS_ALL_ALWAYS_RETURNS_FALSE)
        .build();
      Specified by:
      containsAll in interface Collection<E>
      Returns:
      true if this collection contains the specified elements or false if it does not, or some other value if the collection is broken.
      Throws:
      NullPointerException - if the argument contains a null and collection does not support null values.
      ClassCastException - if the argument is contains an incompatible type and the collection does not support incompatible types.
      See Also:

    • addAll

      public boolean addAll(@NotNull @NotNull Collection<? extends E> c)

      Implements the addAll method from the Collection interface. This method can be broken using the following collection breaks:

      A collection that has any of these breaks can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .withBreak(ADD_ALL_DOES_NOT_ADD_ANY_ELEMENTS)
        .build();

      This is an optional method of the Collection interface. Support for this method can be removed using the optional method identifier CollectionMethods.AddAll. A collection that does not support the addAll method can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .doesNotSupportsMethod(OptionalCollectionMethod.AddAll)
        .build();
      Specified by:
      addAll in interface Collection<E>
      Returns:
      'true' if all of the elements are added, 'false' otherwise, or possibly a different value if the collection has been broken.
      Throws:
      NullPointerException - if the argument contains any null values and collection does not support null values.
      ClassCastException - if the argument contains any elements an incompatible type and the collection does not support incompatible types.
      UnsupportedOperationException - if this collection does not support this method.

    • removeAll

      @Contract(mutates="this") public boolean removeAll(@NotNull @NotNull Collection<?> c)

      Implements the removeAll method from the Collection interface. This method can be broken using the following collection breaks:

      A collection that has any of these breaks can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .withBreak(REMOVE_ALL_DOES_NOT_ADD_ANY_ELEMENTS)
        .build();

      This is an optional method of the Collection interface. Support for this method can be removed using the optional method identifier CollectionMethods.RemoveAll. A collection that does not support the removeAll method can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .doesNotSupportsMethod(OptionalCollectionMethod.RemoveAll)
        .build();
      Specified by:
      removeAll in interface Collection<E>
      Returns:
      'true' if all of the elements are removed, 'false' otherwise, or possibly a different value if the collection has been broken.
      Throws:
      NullPointerException - if the argument contains any null values and collection does not support null values.
      ClassCastException - if the argument contains any elements an incompatible type and the collection does not support incompatible types.
      UnsupportedOperationException - if this collection does not support this method.

    • removeIf

      @Contract(mutates="this") public boolean removeIf(Predicate<? super E> filter)

      Implements the removeIf method from the Collection interface. This method can be broken using the following collection breaks:

      A collection that has any of these breaks can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .withBreak(REMOVE_IF_DOES_NOT_REMOVE_ANY_ELEMENTS)
        .build();

      This is an optional method of the Collection interface. Support for this method can be removed using the optional method identifier CollectionMethods.RemoveIf. A collection that does not support the removeIf method can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .doesNotSupportsMethod(OptionalCollectionMethod.RemoveIf)
        .build();
      Specified by:
      removeIf in interface Collection<E>
      Parameters:
      filter - a predicate which returns true for elements to be removed
      Returns:
      true if any elements were removed
      Throws:
      NullPointerException - if the specified filter is null
      UnsupportedOperationException - if the removeIf operation is not supported by this collection

    • retainAll

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

      Implements the retainAll method from the Collection interface. This method can be broken using the following collection breaks:

      A collection that has any of these breaks can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .withBreak(RETAIN_ALL_DOES_NOT_ADD_ANY_ELEMENTS)
        .build();

      This is an optional method of the Collection interface. Support for this method can be removed using the optional method identifier CollectionMethods.RetainAll. A collection that does not support the retainAll method can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .doesNotSupportsMethod(OptionalCollectionMethod.RetainAll)
        .build();
      Specified by:
      retainAll in interface Collection<E>
      Returns:
      'true' if the collection is modified, 'false' otherwise, or possibly a different value if the collection has been broken.
      Throws:
      NullPointerException - if the argument contains any null values and collection does not support null values.
      ClassCastException - if the argument contains any elements an incompatible type and the collection does not support incompatible types.
      UnsupportedOperationException - if this collection does not support this method.

    • clear

      public void clear()

      Implements the clear method from the Collection interface. This method can be broken using the following collection breaks:

      A collection that has any of these breaks can be constructed using the builder:

          Collection<Integer> collection = Breakables.buildCollection(1,2,3,4,5)
        .withBreak(CLEAR_DOES_NOT_REMOVE_ANY_ELEMENTS)
        .build();
      Specified by:
      clear in interface Collection<E>
      See Also:

    • unbroken

      @NotNull public @NotNull Collection<E> unbroken()
      returns the elements as an unbroken instance of `Collection'
      Overrides:
      unbroken in class BreakableIterable<E>
      Returns:
      an unbroken collection.

    • checkArgument

      protected void checkArgument(Object arg)

      Checks that the argument is valid for this collection. This will check that:

      • The argument is not null or the collection permits nulls
      • The argument is a compatible type or the collection permits incompatible types.
      Parameters:
      arg - the argument to check.
      Throws:
      NullPointerException - if the argument is 'null' and the collection does not permit nulls.
      ClassCastException - if the argument is not compatible and the collection does not permit incompatible types.

    • checkNewElement

      protected boolean checkNewElement(E e)
      Checks that the element is valid to add to this collection. This will check that the element is not a duplicate, or the collection permits duplicate values.
      Parameters:
      e - the element to check.
      Throws:
      NullPointerException - if the argument is 'null' and the collection does not permit nulls.
      ClassCastException - if the argument is not compatible and the collection does not permit incompatible types.

    • collectionProvider

      @NotNull public static <E> @NotNull CollectionProvider<E,BreakableCollection<E>> collectionProvider(@NotNull @NotNull ObjectProvider<E> elementProvider)
      Creates a collection provider for instances of BreakableCollection, given an element provider.
      Type Parameters:
      E - the element type.
      Parameters:
      elementProvider - the element provider to use.
      Returns:
      a collection provider for breakable collections.

    • collectionProvider

      @NotNull public static <E> @NotNull CollectionProvider<E,BreakableCollection<E>> collectionProvider(@NotNull @NotNull ObjectProvider<E> elementProvider, @NotNull @NotNull Set<Break> breaks)
      Creates a collection provider for instances of BreakableCollection, given an element provider and a set of breaks.
      Type Parameters:
      E - the element type.
      Parameters:
      elementProvider - the element provider to use.
      breaks - the breaks to apply to each instance of BreakableCollection.
      Returns:
      a collection provider for breakable collections.