Интерфейс Collection<E>

Основной интерфейс в иерархии коллекций. Коллекция представляет собой группу объектов, известных как её элементы. Некоторые коллекции допускают дублирование элементов, а другие — нет. Некоторые упорядочены, а другие — нет. JDK не предоставляет никаких прямых реализаций этого интерфейса: он предоставляет реализации более конкретных подинтерфейсов, таких как Set и List. Этот интерфейс обычно используется для передачи коллекций и манипулирования ими там, где требуется максимальная общность.

Множества или мультимножества (неупорядоченные коллекции, которые могут содержать дублированные элементы) должны реализовывать этот интерфейс напрямую.

Все общеупотребительные Collection реализующие классы (которые обычно реализуют Collection косвенно через один из его подинтерфейсов) должны предоставлять два «стандартных» конструктора: конструктор без аргументов, который создаёт пустую коллекцию, и конструктор с одним аргументом типа Collection, который создаёт новую коллекцию с теми же элементами, что и её аргумент. По сути, последний конструктор позволяет пользователю копировать любую коллекцию, создавая эквивалентную коллекцию нужного типа реализации. Нет способа закрепить эту конвенцию (так как интерфейсы не могут содержать конструкторы), но все общеупотребительные Collection реализации в библиотеках Java платформы соответствуют ей.

«Деструктивные» методы, содержащиеся в этом интерфейсе, то есть методы, изменяющие коллекцию, на которой они работают, указаны так, что выбросят UnsupportedOperationException, если эта коллекция не поддерживает операцию. В этом случае эти методы могут, но не обязаны, выбросить UnsupportedOperationException, если вызов не окажет никакого влияния на коллекцию. Например, вызов метода addAll(Collection) на неизменяемой коллекции может, но не обязан, выбросить исключение, если добавляемая коллекция пуста.

Некоторые реализации коллекций имеют ограничения на элементы, которые они могут содержать. Например, некоторые реализации запрещают null-элементы, а некоторые имеют ограничения на типы своих элементов. Попытка добавить неприемлемый элемент вызывает неуправляемое исключение, обычно NullPointerException или ClassCastException. Попытка запросить наличие неприемлемого элемента может вызвать исключение или просто вернуть false; некоторые реализации проявят первое поведение, а некоторые — второе. Более общо, попытка выполнить операцию с неприемлемым элементом, завершение которой не приведет к вставке неприемлемого элемента в коллекцию, может вызвать исключение или успешно завершиться по выбору реализации. Такие исключения помечены как «необязательные» в спецификации этого интерфейса.

Каждая коллекция самостоятельно определяет свою политику синхронизации. При отсутствии более сильного гарантии со стороны реализации вызов любого метода на коллекции, которая изменяется другой нитью, может привести к неопределённому поведению; это включает прямые вызовы, передачу коллекции методу, который может выполнить вызовы, и использование существующего итератора для просмотра коллекции.

Многие методы интерфейсов Collections Framework определены с точки зрения метода equals. Например, спецификация метода contains(Object o) гласит: «возвращает true тогда и только тогда, когда эта коллекция содержит по крайней мере один элемент e такой, что (o==null ? e==null : o.equals(e))». Данная спецификация не должна толковаться как подразумевающая, что вызов Collection.contains с ненулевым аргументом o вызовет o.equals(e) для любого элемента e. Реализации могут использовать оптимизации, в которых вызов equals избегается, например, сначала сравнивая коды хэшей двух элементов. (Спецификация Object.hashCode() гарантирует, что два объекта с разными кодами хэшей не могут быть равны.) Более общо, реализации различных интерфейсов Collections Framework могут использовать указанное поведение базовых методов Object где им это кажется уместным.

Некоторые операции над коллекциями, выполняющие рекурсивное обход коллекции, могут завершиться исключением для самоссылочных экземпляров, где коллекция непосредственно или косвенно содержит себя. Это включает методы clone(), equals(), hashCode() и toString(). Реализации могут выборочно обрабатывать сценарии самоссылки, однако большинство текущих реализаций этого не делают.

Этот интерфейс является членом Java Collections Framework.

Методы

size

int size()

Возвращает количество элементов в этом наборе. Если этот набор содержит более Integer.MAX_VALUE элементов, возвращает Integer.MAX_VALUE.

Возвращает:

количество элементов в этом наборе

isEmpty

boolean isEmpty()

Возвращает true, если этот набор не содержит элементов.

Возвращает:

true если этот набор не содержит элементов

contains

boolean contains(Object o)

Возвращает true, если этот набор содержит указанный элемент. Более формально, возвращает true тогда и только тогда, когда этот набор содержит по крайней мере один элемент e такой, что (o==null ? e==null : o.equals(e)).

Параметры:

o - элемент, присутствие которого в этом наборе необходимо проверить

Возвращает:

true если этот набор содержит указанный элемент

Исключения:

ClassCastException - если тип указанного элемента несовместим с этим набором (необязательно)

NullPointerException - если указанный элемент равен null, а этот набор не допускает null-элементы (необязательно)

iterator

Iterator<E> iterator()

Возвращает итератор по элементам в этом наборе. Гарантий относительно порядка возвращения элементов нет (за исключением случаев, когда этот набор является экземпляром класса, предоставляющего такую гарантию).

Определено в:

iterator в интерфейсе Iterable<E>

Возвращает:

итератор по элементам в этом наборе

toArray

Object[] toArray()

Возвращает:

массив, содержащий все элементы в этом наборе

toArray

<T> T[] toArray(T[] a)

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

Параметры типа:

T - тип времени выполнения массива, который будет содержать набор

Параметры:

a - массив, в который должны быть помещены элементы этого набора, если он достаточно велик; в противном случае для этой цели выделяется новый массив того же типа времени выполнения.

Возвращает:

массив, содержащий все элементы в этом наборе

Исключения:

ArrayStoreException - если тип времени выполнения указанного массива не является супертипом типа времени выполнения каждого элемента в этом наборе

NullPointerException - если указанный массив равен null

add

boolean add(E e)

Параметры:

e - элемент, присутствие которого в этом наборе должно быть гарантировано

Возвращает:

true если этот набор изменился в результате вызова

Исключения:

UnsupportedOperationException - если операция add не поддерживается этим набором

ClassCastException - если класс указанного элемента препятствует его добавлению в этот набор

NullPointerException - если указанный элемент равен null, а этот набор не допускает null-элементы

IllegalArgumentException - если какое-либо свойство элемента препятствует его добавлению в этот набор

IllegalStateException - если элемент не может быть добавлен в данный момент из-за ограничений вставки

remove

boolean remove(Object o)

Удаляет единственный экземпляр указанного элемента из этого набора, если он присутствует (необязательная операция). Более формально, удаляет элемент e такой, что (o==null ? e==null : o.equals(e)), если этот набор содержит один или несколько таких элементов. Возвращает true если этот набор содержал указанный элемент (или, что эквивалентно, если этот набор изменился в результате вызова).

Параметры:

o - элемент, который необходимо удалить из этого набора, если он присутствует

Возвращает:

true если элемент был удалён в результате этого вызова

Исключения:

ClassCastException - если тип указанного элемента несовместим с этим набором (необязательно)

NullPointerException - если указанный элемент равен null, а этот набор не допускает null-элементы (необязательно)

UnsupportedOperationException - если операция remove не поддерживается этим набором

containsAll

boolean containsAll(Collection<?> c)

Возвращает true если этот набор содержит все элементы в указанном наборе.

Параметры:

c - набор, проверяемый на наличие в этом наборе

Возвращает:

true если этот набор содержит все элементы в указанном наборе

Исключения:

ClassCastException - если типы одного или нескольких элементов в указанном наборе несовместимы с этим набором (необязательно)

NullPointerException - если указанный набор содержит один или несколько null-элементов, а этот набор не допускает null-элементы (необязательно), или если указанный набор равен null.

См. также:

contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

Добавляет все элементы из указанного набора в этот набор (необязательная операция). Поведение этой операции не определено, если указанный набор изменяется во время выполнения операции. (Это подразумевает, что поведение этого вызова не определено, если указанный набор — это этот набор, и этот набор непуст.)

Параметры:

c - набор, содержащий элементы, которые нужно добавить в этот набор

Возвращает:

true если этот набор изменился в результате вызова

Исключения:

UnsupportedOperationException - если операция addAll не поддерживается этим набором

ClassCastException - если класс элемента указанного набора препятствует его добавлению в этот набор

NullPointerException - если указанный набор содержит null-элемент, а этот набор не допускает null-элементы, или если указанный набор равен null

IllegalArgumentException - если какое-либо свойство элемента указанного набора препятствует его добавлению в этот набор

IllegalStateException - если не все элементы могут быть добавлены в данный момент из-за ограничений вставки

См. также:

add(Object)

removeAll

boolean removeAll(Collection<?> c)

Удаляет все элементы этого набора, которые также содержатся в указанном наборе (необязательная операция). После возврата этого вызова в этом наборе не будет общих элементов с указанным набором.

Параметры:

c - коллекция, содержащая элементы, которые нужно удалить из этой коллекции

Возвращает:

true если эта коллекция изменилась в результате вызова

Выбрасывает:

UnsupportedOperationException - если метод removeAll не поддерживается этой коллекцией

ClassCastException - если типы одного или нескольких элементов в этой коллекции несовместимы со специфицированной коллекцией (необязательно)

NullPointerException - если эта коллекция содержит один или несколько нулевых элементов, а специфицированная коллекция не поддерживает нулевые элементы (необязательно), или если специфицированная коллекция равна null

См. также:

remove(Object), contains(Object)

removeIf

default boolean removeIf(Predicate<? super E> filter)

Удаляет все элементы этой коллекции, удовлетворяющие заданному предикату. Ошибки или исключения времени выполнения, выброшенные во время итерации или предикатом, передаются вызывающей стороне.

Требования к реализации:

Стандартная реализация проходит по всем элементам коллекции с помощью своего iterator(). Каждый соответствующий элемент удаляется с помощью Iterator.remove(). Если итератор коллекции не поддерживает удаление, то на первом сопоставленном элементе будет выброшено UnsupportedOperationException.

Параметры:

filter - предикат, возвращающий true для элементов, подлежащих удалению

Возвращает:

true если были удалены какие-либо элементы

Выбрасывает:

NullPointerException - если указанный фильтр равен null

UnsupportedOperationException - если элементы не могут быть удалены из этой коллекции. Реализации могут выбросить это исключение, если соответствующий элемент не может быть удален или если в целом удаление не поддерживается.

C момента:

1.8

retainAll

boolean retainAll(Collection<?> c)

Оставляет только элементы в этой коллекции, которые содержатся в указанной коллекции (необязательная операция). Другими словами, удаляет из этой коллекции все ее элементы, которые не содержатся в указанной коллекции.

Параметры:

c - коллекция, содержащая элементы, которые нужно сохранить в этой коллекции

Возвращает:

true если эта коллекция изменилась в результате вызова

Выбрасывает:

UnsupportedOperationException - если операция retainAll не поддерживается этой коллекцией

ClassCastException - если типы одного или нескольких элементов в этой коллекции несовместимы со специфицированной коллекцией (необязательно)

NullPointerException - если эта коллекция содержит один или несколько нулевых элементов, а специфицированная коллекция не допускает нулевых элементов (необязательно), или если специфицированная коллекция равна null

См. также:

remove(Object), contains(Object)

clear

void clear()

Удаляет все элементы из этой коллекции (необязательная операция). Коллекция будет пустой после возврата этого метода.

Выбрасывает:

UnsupportedOperationException - если операция clear не поддерживается этой коллекцией

equals

boolean equals(Object o)

Переопределяет:

equals в классе Object

Параметры:

o - объект, который нужно сравнить на равенство с этой коллекцией

Возвращает:

true если указанный объект равен этой коллекции

См. также:

Object.equals(Object), Set.equals(Object), List.equals(Object)

hashCode

int hashCode()

Возвращает значение хэш-кода для этой коллекции. Хотя интерфейс Collection не добавляет никаких условий к общему контракту для метода Object.hashCode, программисты должны обратить внимание на то, что любой класс, переопределяющий метод Object.equals, должен также переопределить метод Object.hashCode, чтобы удовлетворить общему контракту для метода Object.hashCode. В частности, c1.equals(c2) подразумевает, что c1.hashCode()==c2.hashCode().

Переопределяет:

hashCode в классе Object

Возвращает:

значение хэш-кода для этой коллекции

См. также:

Object.hashCode(), Object.equals(Object)

spliterator

default Spliterator<E> spliterator()

Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics)

Указано в:

spliterator в интерфейсе Iterable<E>

Требования к реализации:

Стандартная реализация создает отложенно-связанный разделитель из итератора коллекции. Разделитель наследует свойства fail-fast итератора коллекции.

Созданный Spliterator сообщает Spliterator.SIZED.

Примечание к реализации:

Созданный Spliterator дополнительно сообщает Spliterator.SUBSIZED.

Если разделитель не охватывает ни одного элемента, то сообщение дополнительных характеристик, помимо SIZED и SUBSIZED, не помогает клиентам контролировать, специализировать или упрощать вычисления. Однако это позволяет совместно использовать неизменяемый и пустой экземпляр разделителя (см. Spliterators.emptySpliterator()) для пустых коллекций и позволяет клиентам определить, охватывает ли такой разделитель какие-либо элементы.

Возвращает:

Spliterator над элементами в этой коллекции

C момента:

1.8

stream

default Stream<E> stream()

Требования к реализации:

Стандартная реализация создает последовательный Stream из итератора коллекции.

Возвращает:

последовательный Stream над элементами в этой коллекции

C момента:

1.8

parallelStream

default Stream<E> parallelStream()

Требования к реализации:

Стандартная реализация создает параллельный Stream из итератора коллекции.

Возвращает:

потенциально параллельный Stream над элементами в этой коллекции

C момента:

1.8