1 package org.djutils.immutablecollections; 2 3 import java.io.Serializable; 4 import java.util.Collection; 5 import java.util.Spliterator; 6 import java.util.Spliterators; 7 import java.util.stream.Stream; 8 import java.util.stream.StreamSupport; 9 10 /** 11 * A Collection interface without the methods that can change it. 12 * <p> 13 * Copyright (c) 2016-2019 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See 14 * for project information <a href="https://djutils.org" target="_blank"> https://djutils.org</a>. The DJUTILS project is 15 * distributed under a three-clause BSD-style license, which can be found at 16 * <a href="https://djutils.org/docs/license.html" target="_blank"> https://djutils.org/docs/license.html</a>. 17 * </p> 18 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a> 19 * @author <a href="https://www.tudelft.nl/staff/p.knoppers/">Peter Knoppers</a> 20 * @author <a href="https://www.transport.citg.tudelft.nl">Wouter Schakel</a> 21 * @param <E> the type of content of this Collection 22 */ 23 public interface ImmutableCollection<E> extends Iterable<E>, Serializable 24 { 25 /** 26 * Returns the number of elements in this immutable collection. If this immutable collection contains more than 27 * <code>Integer.MAX_VALUE</code> elements, returns <code>Integer.MAX_VALUE</code>. 28 * @return the number of elements in this immutable collection 29 */ 30 int size(); 31 32 /** 33 * Returns <code>true</code> if this immutable collection contains no elements. 34 * @return <code>true</code> if this immutable collection contains no elements 35 */ 36 boolean isEmpty(); 37 38 /** 39 * Returns <code>true</code> if this immutable collection contains the specified element. More formally, returns <code>true</code> 40 * if and only if this immutable collection contains at least one element <code>e</code> such that 41 * <code>(o==null ? e==null : o.equals(e))</code>. 42 * @param o Object; element whose presence in this immutable collection is to be tested 43 * @return <code>true</code> if this immutable collection contains the specified element 44 * @throws ClassCastException if the type of the specified element is incompatible with this immutable collection 45 * @throws NullPointerException if the specified element is null and this immutable collection does not permit null elements 46 */ 47 boolean contains(Object o); 48 49 /** 50 * Returns an immutable iterator over the elements in this immutable collection. There are no guarantees concerning the 51 * order in which the elements are returned (unless this immutable collection is an instance of some class that provides a 52 * guarantee). The ImmutableIterator is an Iterator where the remove() operation will throw an exception. 53 * @return an <code>ImmutableIterator</code> over the elements in this immutable collection 54 */ 55 @Override 56 ImmutableIterator<E> iterator(); 57 58 /** 59 * Returns an array containing all of the elements in this immutable collection. If this immutable collection makes any 60 * guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same 61 * order. 62 * <p> 63 * See java.util.Collection.toArray() for more details. 64 * @return an array containing all of the elements in this immutable collection 65 */ 66 Object[] toArray(); 67 68 /** 69 * Returns an array containing all of the elements in this immutable collection; the runtime type of the returned array is 70 * that of the specified array. If the immutable collection fits in the specified array, it is returned therein. Otherwise, 71 * a new array is allocated with the runtime type of the specified array and the size of this immutable collection. 72 * <p> 73 * See java.util.Collection.toArray(T[]) for more details. 74 * @param <T> the runtime type of the array to contain the immutable collection 75 * @param a the array into which the elements of this immutable collection are to be stored, if it is big enough; otherwise, 76 * a new array of the same runtime type is allocated for this purpose. 77 * @return an array containing all of the elements in this immutable collection 78 * @throws ArrayStoreException if the runtime type of the specified array is not a supertype of the runtime type of every 79 * element in this immutable collection 80 * @throws NullPointerException if the specified array is null 81 */ 82 <T> T[] toArray(T[] a); 83 84 /** 85 * Returns <code>true</code> if this immutable collection contains all of the elements in the specified collection. 86 * @param c Collection<?>; collection to be checked for containment in this immutable collection 87 * @return <code>true</code> if this immutable collection contains all of the elements in the specified collection 88 * @throws ClassCastException if the types of one or more elements in the specified collection are incompatible with this 89 * immutable collection 90 * @throws NullPointerException if the specified collection contains one or more null elements and this immutable collection 91 * does not permit null elements, or if the specified collection is null. 92 * @see #contains(Object) 93 */ 94 boolean containsAll(Collection<?> c); 95 96 /** 97 * Returns <code>true</code> if this immutable collection contains all of the elements in the specified immutable collection. 98 * @param c ImmutableCollection<?>; immutable collection to be checked for containment in this immutable collection 99 * @return <code>true</code> if this immutable collection contains all of the elements in the specified immutable collection 100 * @throws ClassCastException if the types of one or more elements in the specified immutable collection are incompatible 101 * with this immutable collection 102 * @throws NullPointerException if the specified immutable collection contains one or more null elements and this immutable 103 * collection does not permit null elements, or if the specified immutable collection is null. 104 * @see #contains(Object) 105 */ 106 boolean containsAll(ImmutableCollection<?> c); 107 108 /** 109 * Creates a Spliterator over the elements in this collection. Implementations should document characteristic values 110 * reported by the spliterator. See java.util.Collection for more information. 111 * @return a {@code Spliterator} over the elements in this collection 112 */ 113 @Override 114 default Spliterator<E> spliterator() 115 { 116 return Spliterators.spliterator(toCollection(), 0); 117 } 118 119 /** 120 * Returns a sequential {@code Stream} with this collection as its source. 121 * <p> 122 * This method should be overridden when the {@link #spliterator()} method cannot return a spliterator that is 123 * {@code IMMUTABLE}, {@code CONCURRENT}, or <em>late-binding</em>. (See {@link #spliterator()} for details.) 124 * @return a sequential {@code Stream} over the elements in this collection 125 */ 126 default Stream<E> stream() 127 { 128 return StreamSupport.stream(spliterator(), false); 129 } 130 131 /** 132 * Returns a possibly parallel {@code Stream} with this collection as its source. It is allowable for this method to return 133 * a sequential stream. 134 * <p> 135 * This method should be overridden when the {@link #spliterator()} method cannot return a spliterator that is 136 * {@code IMMUTABLE}, {@code CONCURRENT}, or <em>late-binding</em>. (See {@link #spliterator()} for details.) 137 * @return a possibly parallel {@code Stream} over the elements in this collection 138 */ 139 default Stream<E> parallelStream() 140 { 141 return StreamSupport.stream(spliterator(), true); 142 } 143 144 /** 145 * Returns a modifiable copy of this immutable collection. 146 * @return a modifiable copy of this immutable collection. 147 */ 148 Collection<E> toCollection(); 149 150 /** 151 * Force to redefine equals for the implementations of immutable collection classes. 152 * @param obj Object; the object to compare this collection with 153 * @return whether the objects are equal 154 */ 155 @Override 156 boolean equals(final Object obj); 157 158 /** 159 * Force to redefine hashCode for the implementations of immutable collection classes. 160 * @return the calculated hashCode 161 */ 162 @Override 163 int hashCode(); 164 165 /** 166 * Return whether the internal storage is a wrapped pointer to the original collection. If true, this means that anyone 167 * holding a pointer to this data structure can still change it. The users of the ImmutableCollection itself can, however, 168 * not make any changes. 169 * @return boolean; whether the internal storage is a wrapped pointer to the original collection 170 */ 171 boolean isWrap(); 172 173 /** 174 * Return whether the internal storage is a (shallow) copy of the original collection. If true, this means that anyone 175 * holding a pointer to the original of the data structure can not change it anymore. Nor can the users of the 176 * ImmutableCollection itself make any changes. 177 * @return boolean; whether the internal storage is a safe copy of the original collection 178 */ 179 default boolean isCopy() 180 { 181 return !isWrap(); 182 } 183 184 }