Spec-Zone .ru
спецификации, руководства, описания, API
|
E
- тип элементов в этом набореpublic interface Collection<E> extends Iterable<E>
Сумки или мультимножества (неупорядоченный наборы, которые могут содержать двойные элементы) должны реализовать этот интерфейс непосредственно.
Все классы реализации 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.
Collection
у реализации есть определенный протокол синхронизации, тогда она должна переопределить реализации по умолчанию, чтобы применить тот протокол.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 по элементам в этом наборе.
|
default Stream<E> |
parallelStream()
Возвращается возможно параллель
Stream с этим набором как его источник. |
boolean |
remove(Object o)
Удаляет единственный экземпляр указанного элемента от этого набора, если это присутствует (дополнительная работа).
|
boolean |
removeAll(Collection<?> c)
Удаляет все элементы этого набора, которые также содержатся в указанном наборе (дополнительная работа).
|
default boolean |
removeIf(Predicate<? super E> filter)
Удаляет все элементы этого набора, которые удовлетворяют данный предикат.
|
boolean |
retainAll(Collection<?> c)
Сохраняет только элементы в этом наборе, которые содержатся в указанном наборе (дополнительная работа).
|
int |
size()
Возвращает число элементов в этом наборе.
|
default Spliterator<E> |
spliterator()
Создает a
Spliterator по элементам в этом наборе. |
default Stream<E> |
stream()
Возвращает последовательное
Stream с этим набором как его источник. |
Объект[] |
toArray()
Возвращает массив, содержащий все элементы в этом наборе.
|
<T> T[] |
toArray(T[] a)
Возвращает массив, содержащий все элементы в этом наборе; тип времени выполнения возвращенного массива является типом указанного массива.
|
forEach
int size()
boolean isEmpty()
boolean contains(Object o)
o
- элемент, присутствие которого в этом наборе должно быть протестированоClassCastException
- если тип указанного элемента является несовместимым с этим (дополнительным) наборомNullPointerException
- если указанный элемент является нулем, и этот набор не разрешает нулевые (дополнительные) элементыIterator<E> iterator()
Object[] toArray()
Возвращенный массив будет "безопасен" в этом, никакие ссылки на него не сохраняются этим набором. (Другими словами этот метод должен выделить новый массив, даже если этот набор поддерживается массивом). Вызывающая сторона таким образом свободна изменить возвращенный массив.
Этот метод действует как мост между основанными на массиве и основанными на наборе API.
<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)
Наборы, которые поддерживают эту работу, могут поместить ограничения на то, какие элементы могут быть добавлены к этому набору. В частности некоторые наборы откажутся добавить элементы null, и другие введут ограничения для типа элементов, которые могут быть добавлены. Классы набора должны ясно определить в их документации любые ограничения на то, какие элементы могут быть добавлены.
Если набор отказывается добавить определенный элемент по какой-либо причине, кроме которой он уже содержит элемент, он должен выдать исключение (вместо того, чтобы возвратить false). Это сохраняет инвариант, что набор всегда содержит указанный элемент после этого вызова возвраты.
e
- элемент, присутствие которого в этом наборе должно быть обеспеченоUnsupportedOperationException
- если работа add не поддерживается этим наборомClassCastException
- если class указанного элемента препятствует тому, чтобы это было добавлено к этому наборуNullPointerException
- если указанный элемент является нулем, и этот набор не разрешает нулевые элементыIllegalArgumentException
- если некоторое свойство элемента препятствует тому, чтобы это было добавлено к этому наборуIllegalStateException
- если элемент не может быть добавлен в это время из-за ограничений вставкиboolean remove(Object o)
o
- элемент, который будет удален из этого набора, если существующийClassCastException
- если тип указанного элемента является несовместимым с этим (дополнительным) наборомNullPointerException
- если указанный элемент является нулем, и этот набор не разрешает нулевые (дополнительные) элементыUnsupportedOperationException
- если работа remove не поддерживается этим наборомboolean containsAll(Collection<?> c)
c
- набор, который будет проверен на включение в этом набореClassCastException
- если типы одного или более элементов в указанном наборе являются несовместимыми с этим (дополнительным) наборомNullPointerException
- если указанный набор содержит один или более нулевых элементов, и этот набор не разрешает нулевые (дополнительные) элементы, или если указанный набор является нулем.contains(Object)
boolean addAll(Collection<? extends E> c)
c
- набор, содержащий элементы, которые будут добавлены к этому наборуUnsupportedOperationException
- если работа addAll не поддерживается этим наборомClassCastException
- если class элемента указанного набора препятствует тому, чтобы это было добавлено к этому наборуNullPointerException
- если указанный набор содержит нулевой элемент, и этот набор не разрешает нулевые элементы, или если указанный набор является нулемIllegalArgumentException
- если некоторое свойство элемента указанного набора препятствует тому, чтобы это было добавлено к этому наборуIllegalStateException
- если не все элементы могут быть добавлены в это время из-за ограничений вставкиadd(Object)
boolean removeAll(Collection<?> c)
c
- набор, содержащий элементы, которые будут удалены из этого набораUnsupportedOperationException
- если метод removeAll не поддерживается этим наборомClassCastException
- если типы одного или более элементов в этом наборе являются несовместимыми с указанным (дополнительным) наборомNullPointerException
- если этот набор содержит один или более нулевых элементов, и указанный набор не поддерживает нулевые (дополнительные) элементы, или если указанный набор является нулемremove(Object)
, contains(Object)
default boolean removeIf(Predicate<? super E> filter)
iterator()
. Каждый элемент соответствия удаляется, используя Iterator.remove()
. Если iterator набора не поддерживает удаление тогда UnsupportedOperationException
будет брошен в первый элемент соответствия.filter
- предикат, который возвращается true
для элементов, которые будут удаленыtrue
если какие-либо элементы были удаленыNullPointerException
- если указанный фильтр является нулемUnsupportedOperationException
- если remove
метод не поддерживается этим набором iterator()
boolean retainAll(Collection<?> c)
c
- набор, содержащий элементы, которые будут сохранены в этом набореUnsupportedOperationException
- если работа retainAll не поддерживается этим наборомClassCastException
- если типы одного или более элементов в этом наборе являются несовместимыми с указанным (дополнительным) наборомNullPointerException
- если этот набор содержит один или более нулевых элементов, и указанный набор не разрешает нулевые (дополнительные) элементы, или если указанный набор является нулемremove(Object)
, contains(Object)
void clear()
UnsupportedOperationException
- если работа clear не поддерживается этим наборомboolean equals(Object o)
В то время как интерфейс Collection не добавляет соглашений к общему контракту для Object.equals, программисты, которые реализуют интерфейс Collection "непосредственно" (другими словами, создают class, который является Collection, но не является Set или List), должны осуществить заботу, если они хотят переопределять Object.equals. Не необходимо сделать так, и самый простой план действий должен положиться на реализацию Object, но конструктор может хотеть реализовать "сравнение значения" вместо значения по умолчанию "ссылочное сравнение." (List и интерфейсы Set передают под мандат такие сравнения значения.)
Общий контракт для состояний метода Object.equals, который равняется, должен быть симметричным (другими словами, a.equals(b) если и только если b.equals(a)). Контракты для List.equals и Set.equals утверждают, что списки только равны другим спискам, и устанавливает в другие наборы. Таким образом, пользовательский метод equals для набора, class, который не реализует ни List, ни интерфейса Set, должен возвратить false, когда этот набор по сравнению с любым списком или набором. (Той же самой логикой не возможно записать class, который правильно реализует и Set и интерфейсы List.)
equals
в class Object
o
- объект, который будет сравнен для равенства с этим наборомObject.equals(Object)
, Set.equals(Object)
, List.equals(Object)
int hashCode()
hashCode
в class Object
Object.hashCode()
, Object.equals(Object)
default Spliterator<E> spliterator()
Spliterator
по элементам в этом наборе. Возвращенный Spliterator
должна сообщить характеристика Spliterator.SIZED
; реализации должны задокументировать любые дополнительные характеристические значения, о которых сообщает возвращенный Spliterator.
Реализация по умолчанию должна быть переопределена подклассами, которые могут возвратить более эффективный spliterator. Чтобы сохранить ожидаемое поведение лени для stream()
и parallelStream()
} у методов, spliterators должна или быть характеристика IMMUTABLE
или CONCURRENT
, или быть поздним связыванием. Если ни один из них не практичен, переопределение class должен описать задокументированную политику spliterator привязки и структурной интерференции, и должен переопределить stream()
и parallelStream()
методы, чтобы создать потоки, используя a Supplier
из spliterator, как в:
Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics)
Эти требования гарантируют что потоки, произведенные stream()
и parallelStream()
методы отразят содержание набора с инициирования терминальной операции с потоками.
Iterator
. spliterator наследовал свойства сбоя быстро iterator набора.Spliterator
дополнительно отчеты Spliterator.SUBSIZED
.Spliterator
по элементам в этом набореdefault Stream<E> stream()
Stream
с этим набором как его источник. Этот метод должен быть переопределен когда spliterator()
метод не может возвратить spliterator, который является IMMUTABLE
, CONCURRENT
, или позднее связывание. (См. spliterator()
для деталей.)
Stream
от набора Spliterator
.Stream
по элементам в этом набореdefault Stream<E> parallelStream()
Stream
с этим набором как его источник. Это допустимо для этого метода, чтобы возвратить последовательный поток. Этот метод должен быть переопределен когда spliterator()
метод не может возвратить spliterator, который является IMMUTABLE
, CONCURRENT
, или позднее связывание. (См. spliterator()
для деталей.)
Stream
от набора Spliterator
.Stream
по элементам в этом наборе
Для дальнейшей ссылки API и документации разработчика, см. Java Документация SE. Та документация содержит более подробные, предназначенные разработчиком описания, с концептуальными краткими обзорами, определениями сроков, обходных решений, и рабочих примеров кода.
Авторское право © 1993, 2013, Oracle и/или его филиалы. Все права защищены.
Проект сборка-b92