java.util

Интерфейсный Набор <E>

Введите Параметры:

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

Все Суперинтерфейсы:

Повторяемый <E>

Все Известные Подынтерфейсы:

BeanContext, BeanContextServices, BlockingDeque <E>, BlockingQueue <E>, Двухсторонняя очередь <E>, Список <E>, NavigableSet <E>, Очередь <E>, Набор <E>, SortedSet <E>, TransferQueue <E>

Все Известные Классы с реализацией:

AbstractCollection, AbstractList, AbstractQueue, AbstractSequentialList, AbstractSet, ArrayBlockingQueue, ArrayDeque, ArrayList, AttributeList, BeanContextServicesSupport, BeanContextSupport, ConcurrentLinkedDeque, ConcurrentLinkedQueue, ConcurrentSkipListSet, CopyOnWriteArrayList, CopyOnWriteArraySet, DelayQueue, EnumSet, HashSet, JobStateReasons, LinkedBlockingDeque, LinkedBlockingQueue, LinkedHashSet, LinkedList, LinkedTransferQueue, PriorityBlockingQueue, PriorityQueue, RoleList, RoleUnresolvedList, Стек, SynchronousQueue, TreeSet, Вектор

public interface Collection<E>
extends Iterable<E>

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

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

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

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

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

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

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

Этот интерфейс является элементом Платформы Наборов Java.

С тех пор:

1.2

См. Также:

Set, List, Map, SortedSet, SortedMap, HashSet, TreeSet, ArrayList, LinkedList, Vector, Collections, Arrays, AbstractCollection

Сводка метода

Методы

Модификатор и Тип	Метод и Описание
boolean	add(E e) Гарантирует, что этот набор содержит указанный элемент (дополнительная работа).
boolean	addAll(Collection<? extends E> c) Добавляют все элементы в указанном наборе к этому набору (дополнительная работа).
void	clear() Удаляет все элементы от этого набора (дополнительная работа).
boolean	contains(Object o) true возвратов, если этот набор содержит указанный элемент.
boolean	containsAll(Collection<?> c) true возвратов, если этот набор содержит все элементы в указанном наборе.
boolean	equals(Object o) Сравнивает указанный объект с этим набором для равенства.
int	hashCode() Возвращает значение хэш-кода для этого набора.
boolean	isEmpty() true возвратов, если этот набор не содержит элементов.
Iterator<E>	iterator() Возвращает iterator по элементам в этом наборе.
boolean	remove(Object o) Удаляет единственный экземпляр указанного элемента от этого набора, если это присутствует (дополнительная работа).
boolean	removeAll(Collection<?> c) Удаляет все элементы этого набора, которые также содержатся в указанном наборе (дополнительная работа).
boolean	retainAll(Collection<?> c) Сохраняет только элементы в этом наборе, которые содержатся в указанном наборе (дополнительная работа).
int	size() Возвращает число элементов в этом наборе.
Объект[]	toArray() Возвращает массив, содержащий все элементы в этом наборе.
<T> T[]	toArray(T[] a) Возвращает массив, содержащий все элементы в этом наборе; тип времени выполнения возвращенного массива является типом указанного массива.

Деталь метода

размер

int size()

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

Возвраты:

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

isEmpty

boolean isEmpty()

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

Возвраты:

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

содержит

boolean contains(Object o)

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

Параметры:

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

Возвраты:

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

Броски:

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

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

iterator

Iterator<E> iterator()

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

Определенный:

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

Возвраты:

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

toArray

Object[] toArray()

Возвращает массив, содержащий все элементы в этом наборе. Если этот набор делает какие-либо гарантии относительно того, какой порядок его элементы возвращаются его iterator, этот метод должен возвратить элементы в том же самом порядке.

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

Этот метод действует как мост между основанными на массиве и основанными на наборе API.

Возвраты:

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

toArray

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

Возвращает массив, содержащий все элементы в этом наборе; тип времени выполнения возвращенного массива является типом указанного массива. Если набор помещается в указанный массив, он возвращается туда. Иначе, новый массив выделяется с типом времени выполнения указанного массива и размером этого набора.

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

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

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

Предположите, что x является набором, который, как известно, содержал только строки. Следующий код может использоваться, чтобы вывести набор в недавно выделенный массив String:

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

Отметьте, что toArray(new Object[0]) идентичен в функции toArray().

Параметры:

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

Возвраты:

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

Броски:

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

NullPointerException - если указанный массив является нулем

добавить

boolean add(E e)

Гарантирует, что этот набор содержит указанный элемент (дополнительная работа). true возвратов, если этот набор изменился в результате вызова. (Возвраты false, если этот набор не разрешает копии и уже содержит указанный элемент.)

Наборы, которые поддерживают эту работу, могут поместить ограничения на то, какие элементы могут быть добавлены к этому набору. В частности некоторые наборы откажутся добавить элементы null, и другие введут ограничения для типа элементов, которые могут быть добавлены. Классы набора должны ясно определить в их документации любые ограничения на то, какие элементы могут быть добавлены.

Если набор отказывается добавить определенный элемент по какой-либо причине, кроме которой он уже содержит элемент, он должен выдать исключение (вместо того, чтобы возвратить false). Это сохраняет инвариант, что набор всегда содержит указанный элемент после этого вызова возвраты.

Параметры:

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

Возвраты:

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

Броски:

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

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

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

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

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

удалить

boolean remove(Object o)

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

Параметры:

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

Возвраты:

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

Броски:

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

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

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

containsAll

boolean containsAll(Collection<?> c)

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

Параметры:

c - набор, который будет проверен на включение в этом наборе

Возвраты:

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

Броски:

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

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

См. Также:

contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

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

Параметры:

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

Возвраты:

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

Броски:

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

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

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

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

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

См. Также:

add(Object)

removeAll

boolean removeAll(Collection<?> c)

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

Параметры:

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

Возвраты:

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

Броски:

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

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

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

См. Также:

remove(Object), contains(Object)

retainAll

boolean retainAll(Collection<?> c)

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

Параметры:

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

Возвраты:

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

Броски:

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

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

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

См. Также:

remove(Object), contains(Object)

очистить

void clear()

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

Броски:

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

равняется

boolean equals(Object o)

Сравнивает указанный объект с этим набором для равенства.

В то время как интерфейс Collection не добавляет соглашений к общему контракту для Object.equals, программисты, которые реализуют интерфейс Collection "непосредственно" (другими словами, создают класс, который является Collection, но не является Set или List), должны осуществить заботу, если они хотят переопределять Object.equals. Не необходимо сделать так, и самый простой план действий должен положиться на реализацию Object, но конструктор может хотеть реализовать "сравнение значения" вместо "ссылочного сравнения по умолчанию." (List и интерфейсы Set передают под мандат такие сравнения значения.)

Общий контракт для состояний метода Object.equals, который равняется, должен быть симметричным (другими словами, a.equals(b) если и только если b.equals(a)). Контракты для List.equals и Set.equals утверждают, что списки только равны другим спискам, и устанавливает в другие наборы. Таким образом пользовательский метод equals для класса набора, который не реализует ни List, ни интерфейса Set, должен возвратить false, когда этот набор по сравнению с любым списком или набором. (Той же самой логикой не возможно записать класс, который правильно реализует и Set и интерфейсы List.)

Переопределения:

equals в классе Object

Параметры:

o - объект, который будет сравнен для равенства с этим набором

Возвраты:

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

См. Также:

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

хэш-код

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)