Класс Collections

public static final Set EMPTY_SET

Пустое множество (неизменяемое). Это множество сериализуемо.

public static final List EMPTY_LIST

Пустой список (неизменяемый). Этот список сериализуем.

public static final Map EMPTY_MAP

Пустая карта (неизменяемая). Эта карта сериализуема.

public static <T extends Comparable<? super T>> void sort(List<T> list)

Сортирует указанный список в порядке возрастания в соответствии с естественным порядком его элементов. Все элементы в списке должны реализовывать интерфейс Comparable. Кроме того, все элементы в списке должны быть взаимно сравнимы (то есть, e1.compareTo(e2) не должно вызывать ClassCastException для любых элементов e1 и e2 в списке).

Эта сортировка гарантированно стабильна: равные элементы не будут переупорядочены в результате сортировки.

Указанный список должен быть изменяемым, но не обязательно изменяемым по размеру.

public static <T> void sort(List<T> list, Comparator<? super T> c)

Сортирует указанный список в соответствии с порядком, индуцированным указанным компаратором. Все элементы в списке должны быть взаимно сравнимыми с помощью указанного компаратора (то есть, c.compare(e1, e2) не должно вызывать ClassCastException для любых элементов e1 и e2 в списке).

Эта сортировка гарантированно стабильна: равные элементы не будут переупорядочены в результате сортировки.

Указанный список должен быть изменяемым, но не обязательно изменяемым по размеру.

public static <T> int binarySearch(List<? extends Comparable<? super T>> list, T key)

Ищет в указанном списке указанный объект с помощью алгоритма бинарного поиска. Список должен быть отсортирован в порядке возрастания в соответствии с естественным порядком его элементов (как в методе sort(List)) перед вызовом этого метода. Если он не отсортирован, результаты не определены. Если список содержит несколько элементов, равных указанному объекту, нет гарантии, какой из них будет найден.

Этот метод работает за время log(n) для списка с «случайным доступом» (который обеспечивает почти постоянное время доступа к позиции). Если указанный список не реализует интерфейс RandomAccess и большой, этот метод выполнит поиск в двоичном формате на основе итератора, который выполняет O(n) обходов связей и O(log n) сравнений элементов.

public static <T> int binarySearch(List<? extends T> list, T key, Comparator<? super T> c)

Ищет в указанном списке указанный объект с помощью алгоритма бинарного поиска. Список должен быть отсортирован в порядке возрастания в соответствии с указанным компаратором (как в методе sort(List, Comparator)) перед вызовом этого метода. Если он не отсортирован, результаты не определены. Если список содержит несколько элементов, равных указанному объекту, нет гарантии, какой из них будет найден.

Этот метод работает за время log(n) для списка с «случайным доступом» (который обеспечивает почти постоянное время доступа к позиции). Если указанный список не реализует интерфейс RandomAccess и большой, этот метод выполнит поиск в двоичном формате на основе итератора, который выполняет O(n) обходов связей и O(log n) сравнений элементов.

public static void reverse(List<?> list)

Изменяет порядок элементов в указанном списке.

Этот метод работает за линейное время.

public static void shuffle(List<?> list)

Случайным образом перемешивает указанный список с использованием стандартного источника случайности. Все перестановки происходят с приблизительно равной вероятностью.

Оговорка "приблизительно" используется в предыдущем описании, потому что стандартный источник случайности представляет собой только приблизительно беспристрастный источник независимо выбранных битов. Если бы это был идеальный источник случайных битов, то алгоритм выбирал бы перестановки с идеальной равномерностью.

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

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

public static void shuffle(List<?> list, Random rnd)

Случайным образом переупорядочивает указанный список, используя указанный источник случайности. Все перестановки происходят с равной вероятностью, предполагая, что источник случайности справедлив.

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

Этот метод работает за линейное время. Если указанный список не реализует интерфейс RandomAccess и является большим, эта реализация копирует указанный список в массив перед перемешиванием и копирует перемешанный массив обратно в список. Это позволяет избежать квадратичного поведения, которое возникло бы при перемешивании списка «последовательного доступа» на месте.

public static void swap(List<?> list, int i, int j)

Меняет местами элементы в указанном списке по заданным позициям. (Если указанные позиции равны, вызов этого метода не изменяет список.)

public static <T> void fill(List<? super T> list, T obj)

Заменяет все элементы указанного списка заданным элементом.

Этот метод работает за линейное время.

public static <T> void copy(List<? super T> dest, List<? extends T> src)

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

Этот метод работает за линейное время.

public static <T extends Object & Comparable<? super T>> T min(Collection<? extends T> coll)

Возвращает минимальный элемент заданного набора, согласно *естественному порядку* его элементов. Все элементы в наборе должны реализовывать интерфейс Comparable. Кроме того, все элементы в наборе должны быть *взаимно сравнимы* (то есть e1.compareTo(e2) не должно выбрасывать ClassCastException для любых элементов e1 и e2 в наборе).

Этот метод проходит по всему набору, поэтому требует времени, пропорционального размеру набора.

public static <T> T min(Collection<? extends T> coll, Comparator<? super T> comp)

Возвращает минимальный элемент данного набора, согласно порядку, индуцированному заданным компаратором. Все элементы в наборе должны быть *взаимно сравнимы* указанным компаратором (то есть comp.compare(e1, e2) не должно выбрасывать ClassCastException для любых элементов e1 и e2 в наборе).

Этот метод проходит по всему набору, поэтому требует времени, пропорционального размеру набора.

public static <T extends Object & Comparable<? super T>> T max(Collection<? extends T> coll)

Возвращает максимальный элемент данного набора, согласно *естественному порядку* его элементов. Все элементы в наборе должны реализовывать интерфейс Comparable. Кроме того, все элементы в наборе должны быть *взаимно сравнимы* (то есть e1.compareTo(e2) не должно выбрасывать ClassCastException для любых элементов e1 и e2 в наборе).

Этот метод проходит по всему набору, поэтому требует времени, пропорционального размеру набора.

public static <T> T max(Collection<? extends T> coll, Comparator<? super T> comp)

Возвращает максимальный элемент данного набора, согласно порядку, индуцированному заданным компаратором. Все элементы в наборе должны быть *взаимно сравнимы* указанным компаратором (то есть comp.compare(e1, e2) не должно выбрасывать ClassCastException для любых элементов e1 и e2 в наборе).

Этот метод проходит по всему набору, поэтому требует времени, пропорционального размеру набора.

public static void rotate(List<?> list, int distance)

Поворачивает элементы в указанном списке на указанное расстояние. После вызова этого метода элемент с индексом i будет элементом, который ранее находился на индексе (i - distance) mod list.size(), для всех значений i между 0 и list.size()-1, включительно. (Этот метод не влияет на размер списка.)

Например, предположим, что list содержит [t, a, n, k, s]. После вызова Collections.rotate(list, 1) (или Collections.rotate(list, -4)), list будет содержать [s, t, a, n, k].

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

     Collections.rotate(list.subList(j, k+1), -1);
 

Для наглядности, предположим, что list содержит [a, b, c, d, e]. Чтобы переместить элемент с индексом 1 (b) вперёд на две позиции, выполните следующий вызов:

     Collections.rotate(l.subList(1, 4), -1);
 

Результирующий список будет [a, c, d, b, e].

Для перемещения более одного элемента вперёд увеличьте абсолютное значение расстояния поворота. Для перемещения элементов назад используйте положительное смещение.

Если указанный список небольшой или реализует интерфейс RandomAccess, эта реализация меняет первое местоположение элемента на то, где он должен быть, а затем повторяет обмен смещённого элемента на место, пока смещённый элемент не будет помещён на первое место. Если необходимо, процесс повторяется для второго и последующих элементов, пока поворот не будет завершён. Если указанный список большой и не реализует интерфейс RandomAccess, эта реализация разбивает список на два подсписка вокруг индекса -distance mod size. Затем метод reverse(List) вызывается для каждого подсписка, и, наконец, для всего списка. Более полное описание обоих алгоритмов см. в разделе 2.3 книги Джона Бентли «Программирование Pearls» (Addison-Wesley, 1986).

public static <T> boolean replaceAll(List<T> list, T oldVal, T newVal)

Заменяет все вхождения одного указанного значения в списке другим. Более формально, заменяет newVal каждый элемент e в list таким образом, чтобы (oldVal==null ? e==null : oldVal.equals(e)). (Этот метод не влияет на размер списка.)

public static int indexOfSubList(List<?> source, List<?> target)

Возвращает начальную позицию первого вхождения указанного целевого списка в указанном исходном списке или -1, если такого вхождения нет. Более формально, возвращает наименьший индекс i такой, что source.subList(i, i+target.size()).equals(target), или -1, если такого индекса нет. (Возвращает -1, если target.size() > source.size())

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

public static int lastIndexOfSubList(List<?> source, List<?> target)

Возвращает начальную позицию последнего вхождения указанного целевого списка в указанный исходный список, или -1, если такого вхождения нет. Более формально, возвращает наивысший индекс i такой, что source.subList(i, i+target.size()).equals(target), или -1, если такого индекса нет. (Возвращает -1, если target.size() > source.size())

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

public static <T> Collection<T> unmodifiableCollection(Collection<? extends T> c)

Возвращает неизменяемый вид указанного набора. Операции запроса к возвращаемому набору "читают через" к указанному набору, и попытки изменить возвращаемый набор, как прямо, так и через его итератор, приводят к UnsupportedOperationException.

Возвращаемый набор не передает операции hashCode и equals в подлежащий набор, но полагается на Object's equals и hashCode методы. Это необходимо для сохранения контрактов этих операций в том случае, если подлежащий набор является множеством или списком.

Возвращаемый набор будет сериализуемым, если указанный набор является сериализуемым.

public static <T> Set<T> unmodifiableSet(Set<? extends T> s)

Возвращает неизменяемый вид указанного множества. Операции запроса к возвращаемому множеству "читают через" к указанному множеству, и попытки изменить возвращаемое множество, как прямо, так и через его итератор, приводят к UnsupportedOperationException.

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

public static <T> SortedSet<T> unmodifiableSortedSet(SortedSet<T> s)

Возвращает неизменяемый вид указанного отсортированного множества. Операции запроса к возвращаемому отсортированному множеству "читают через" к указанному отсортированному множеству. Попытки изменить возвращаемое отсортированное множество, как напрямую, так и через его итератор, или через его subSet, headSet, или tailSet представления, приводят к UnsupportedOperationException.

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

public static <T> NavigableSet<T> unmodifiableNavigableSet(NavigableSet<T> s)

Возвращает неизменяемый вид указанного навигационного множества. Операции запроса к возвращаемому навигационному множеству "читают через" к указанному навигационному множеству. Попытки изменить возвращаемое навигационное множество, как напрямую, так и через его итератор, или через его subSet, headSet, или tailSet представления, приводят к UnsupportedOperationException.

Возвращаемое навигационное множество будет сериализуемым, если указанное навигационное множество является сериализуемым.

public static <T> List<T> unmodifiableList(List<? extends T> list)

Возвращает неизменяемый вид указанного списка. Операции запроса к возвращаемому списку «считывают» из указанного списка, и попытки изменить возвращаемый список, будь то прямо или через его итератор, приводят к UnsupportedOperationException.

Возвращаемый список будет сериализуемым, если указанный список сериализуем. Аналогично, возвращаемый список будет реализовывать RandomAccess, если указанный список это делает.

public static <K, V> Map<K,V> unmodifiableMap(Map<? extends K,? extends V> m)

Возвращает неизменяемый вид указанной карты. Операции запроса к возвращаемой карте «считывают» из указанной карты, и попытки изменить возвращаемую карту, будь то прямо или через ее коллекции, приводят к UnsupportedOperationException.

Возвращаемая карта будет сериализуемой, если указанная карта сериализуема.

public static <K, V> SortedMap<K,V> unmodifiableSortedMap(SortedMap<K,? extends V> m)

Возвращает неизменяемый вид указанной отсортированной карты. Операции запроса к возвращаемой отсортированной карте «считывают» из указанной отсортированной карты. Попытки изменить возвращаемую отсортированную карту, будь то напрямую, через ее коллекции или через ее subMap, headMap, или tailMap представления, приведут к UnsupportedOperationException.

Возвращаемая отсортированная карта будет сериализуемой, если указанная отсортированная карта сериализуема.

public static <K, V> NavigableMap<K,V> unmodifiableNavigableMap(NavigableMap<K,? extends V> m)

Возвращает неизменяемый вид указанной навигационной карты. Операции запроса к возвращаемой навигационной карте «считывают» из указанной навигационной карты. Попытки изменить возвращаемую навигационную карту, будь то напрямую, через ее коллекции или через ее subMap, headMap, или tailMap представления, приведут к UnsupportedOperationException.

Возвращаемая навигационная карта будет сериализуемой, если указанная навигационная карта сериализуема.

public static <T> Collection<T> synchronizedCollection(Collection<T> c)

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

Необходимо вручную синхронизировать на возвращенной коллекции при обходе с помощью Iterator, Spliterator или Stream:

  Collection c = Collections.synchronizedCollection(myCollection);
     ...
  synchronized (c) {
      Iterator i = c.iterator(); // Must be in the synchronized block
      while (i.hasNext())
         foo(i.next());
  }
 

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

Возвращаемая коллекция не передает операции hashCode и equals в базу коллекции, а опирается на методы equals и hashCode Object. Это необходимо для сохранения контрактов этих операций в случае, если базовая коллекция является набором или списком.

Возвращаемая коллекция будет сериализуемой, если указанная коллекция сериализуема.

public static <T> Set<T> synchronizedSet(Set<T> s)

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

Необходимо вручную синхронизировать на возвращенной коллекции при обходе с помощью Iterator, Spliterator или Stream:

  Set s = Collections.synchronizedSet(new HashSet());
      ...
  synchronized (s) {
      Iterator i = s.iterator(); // Must be in the synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

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

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

public static <T> SortedSet<T> synchronizedSortedSet(SortedSet<T> s)

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

Необходимо вручную синхронизировать на возвращенном отсортированном наборе при обходе или любом из его subSet, headSet, или tailSet представлений с помощью Iterator, Spliterator или Stream:

  SortedSet s = Collections.synchronizedSortedSet(new TreeSet());
      ...
  synchronized (s) {
      Iterator i = s.iterator(); // Must be in the synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

или:

  SortedSet s = Collections.synchronizedSortedSet(new TreeSet());
  SortedSet s2 = s.headSet(foo);
      ...
  synchronized (s) {  // Note: s, not s2!!!
      Iterator i = s2.iterator(); // Must be in the synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

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

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

public static <T> NavigableSet<T> synchronizedNavigableSet(NavigableSet<T> s)

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

Необходимо вручную синхронизировать на возвращенном навигационном наборе при обходе или любом из его subSet, headSet, или tailSet представлений с помощью Iterator, Spliterator или Stream:

  NavigableSet s = Collections.synchronizedNavigableSet(new TreeSet());
      ...
  synchronized (s) {
      Iterator i = s.iterator(); // Must be in the synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

или:

  NavigableSet s = Collections.synchronizedNavigableSet(new TreeSet());
  NavigableSet s2 = s.headSet(foo, true);
      ...
  synchronized (s) {  // Note: s, not s2!!!
      Iterator i = s2.iterator(); // Must be in the synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

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

Возвращаемый навигационный набор будет сериализуемым, если указанный навигационный набор сериализуем.

public static <T> List<T> synchronizedList(List<T> list)

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

Необходимо вручную синхронизировать на возвращенном списке при обходе с помощью Iterator, Spliterator или Stream:

  List list = Collections.synchronizedList(new ArrayList());
      ...
  synchronized (list) {
      Iterator i = list.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

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

Возвращаемый список будет сериализуемым, если указанный список сериализуем.

public static <K, V> Map<K,V> synchronizedMap(Map<K,V> m)

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

Необходимо, чтобы пользователь вручную синхронизировал возвращенную карту при обходе любого из её представлений коллекций через Iterator, Spliterator или Stream:

  Map m = Collections.synchronizedMap(new HashMap());
      ...
  Set s = m.keySet();  // Needn't be in synchronized block
      ...
  synchronized (m) {  // Synchronizing on m, not s!
      Iterator i = s.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

Несоблюдение этого совета может привести к непредсказуемому поведению.

Возвращаемая карта будет сериализуемой, если указанная карта сериализуема.

public static <K, V> SortedMap<K,V> synchronizedSortedMap(SortedMap<K,V> m)

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

Необходимо, чтобы пользователь вручную синхронизировал возвращенную отсортированную карту при обходе любого из её представлений коллекций, или представлений коллекций любого из её subMap, headMap или tailMap представлений, через Iterator, Spliterator или Stream:

  SortedMap m = Collections.synchronizedSortedMap(new TreeMap());
      ...
  Set s = m.keySet();  // Needn't be in synchronized block
      ...
  synchronized (m) {  // Synchronizing on m, not s!
      Iterator i = s.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

или:

  SortedMap m = Collections.synchronizedSortedMap(new TreeMap());
  SortedMap m2 = m.subMap(foo, bar);
      ...
  Set s2 = m2.keySet();  // Needn't be in synchronized block
      ...
  synchronized (m) {  // Synchronizing on m, not m2 or s2!
      Iterator i = s2.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

Несоблюдение этого совета может привести к непредсказуемому поведению.

Возвращаемая отсортированная карта будет сериализуемой, если указанная отсортированная карта сериализуема.

public static <K, V> NavigableMap<K,V> synchronizedNavigableMap(NavigableMap<K,V> m)

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

Необходимо, чтобы пользователь вручную синхронизировал возвращенную навигационную карту при обходе любого из её представлений коллекций, или представлений коллекций любого из её subMap, headMap или tailMap представлений, через Iterator, Spliterator или Stream:

  NavigableMap m = Collections.synchronizedNavigableMap(new TreeMap());
      ...
  Set s = m.keySet();  // Needn't be in synchronized block
      ...
  synchronized (m) {  // Synchronizing on m, not s!
      Iterator i = s.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

или:

  NavigableMap m = Collections.synchronizedNavigableMap(new TreeMap());
  NavigableMap m2 = m.subMap(foo, true, bar, false);
      ...
  Set s2 = m2.keySet();  // Needn't be in synchronized block
      ...
  synchronized (m) {  // Synchronizing on m, not m2 or s2!
      Iterator i = s.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

Несоблюдение этого совета может привести к непредсказуемому поведению.

Возвращаемая навигационная карта будет сериализуемой, если указанная навигационная карта сериализуема.

public static <E> Collection<E> checkedCollection(Collection<E> c, Class<E> type)

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

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

Другое использование динамически безопасных представлений — отладка. Предположим, что программа завершается с ClassCastException, указывая, что в параметризованную коллекцию был вставлен элемент неправильного типа. К сожалению, исключение может возникнуть в любое время после вставки ошибочного элемента, поэтому оно обычно даёт мало или совсем никакой информации о реальном источнике проблемы. Если проблема воспроизводима, можно быстро определить её источник, временно модифицировав программу для обертывания коллекции динамически безопасным представлением. Например, эта декларация:

 
     Collection<String> c = new HashSet<>();
 

может быть временно заменена на эту:

 
     Collection<String> c = Collections.checkedCollection(
         new HashSet<>(), String.class);
 

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

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

Возвращаемая коллекция будет сериализуема, если указанная коллекция сериализуема.

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

public static <E> Queue<E> checkedQueue(Queue<E> queue, Class<E> type)

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

Обсуждение использования динамически безопасных представлений можно найти в документации для метода checkedCollection.

Возвращаемая очередь будет сериализуемой, если указанная очередь сериализуема.

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

public static <E> Set<E> checkedSet(Set<E> s, Class<E> type)

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

Обсуждение использования динамически безопасных представлений можно найти в документации для метода checkedCollection.

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

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

public static <E> SortedSet<E> checkedSortedSet(SortedSet<E> s, Class<E> type)

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

Обсуждение использования динамически типизированных безопасных видов можно найти в документации для метода checkedCollection.

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

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

public static <E> NavigableSet<E> checkedNavigableSet(NavigableSet<E> s, Class<E> type)

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

Обсуждение использования динамически типизированных безопасных видов можно найти в документации для метода checkedCollection.

Возвращаемый навигационный набор будет сериализуемым, если указанный навигационный набор является сериализуемым.

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

public static <E> List<E> checkedList(List<E> list, Class<E> type)

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

Обсуждение использования динамически типизированных безопасных видов можно найти в документации для метода checkedCollection.

Возвращаемый список будет сериализуемым, если указанный список является сериализуемым.

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

public static <K, V> Map<K,V> checkedMap(Map<K,V> m, Class<K> keyType, Class<V> valueType)

Возвращает динамически типизированный безопасный вид указанной карты. Любая попытка вставить отображение, ключ или значение которого имеют неверный тип, приведет к немедленному ClassCastException. Аналогично, любая попытка изменить значение, в настоящее время связанное с ключом, приведет к немедленному ClassCastException, независимо от того, была ли попытка модификации произведена непосредственно через саму карту или через экземпляр Map.Entry, полученный из представления entry set карты.

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

Обсуждение использования динамически типизированных безопасных видов можно найти в документации для метода checkedCollection.

Возвращаемая карта будет сериализуемой, если указанная карта является сериализуемой.

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

public static <K, V> SortedMap<K,V> checkedSortedMap(SortedMap<K,V> m, Class<K> keyType, Class<V> valueType)

Возвращает динамически типизированный безопасный вид указанной упорядоченной карты. Любая попытка вставить отображение, ключ или значение которого имеют неверный тип, приведет к немедленному ClassCastException. Аналогично, любая попытка изменить значение, в настоящее время связанное с ключом, приведет к немедленному ClassCastException, независимо от того, была ли попытка модификации произведена непосредственно через саму карту или через экземпляр Map.Entry, полученный из представления entry set карты.

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

Обсуждение использования динамически типизированных безопасных видов можно найти в документации для метода checkedCollection.

Возвращаемая карта будет сериализуемой, если указанная карта является сериализуемой.

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

public static <K, V> NavigableMap<K,V> checkedNavigableMap(NavigableMap<K,V> m, Class<K> keyType, Class<V> valueType)

Возвращает динамически типизированный безопасный просмотр указанного навигационного отображения. Любая попытка вставить сопоставление, у которого ключ или значение имеют неправильный тип, приведет к немедленному ClassCastException. Аналогично, любая попытка изменить значение, в настоящее время связанное с ключом, приведет к немедленному ClassCastException, независимо от того, предпринимается ли изменение непосредственно через само отображение или через экземпляр Map.Entry, полученный из просмотра entry set отображения.

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

Обсуждение использования динамически типизированных безопасных представлений можно найти в документации для метода checkedCollection.

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

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

public static <T> Iterator<T> emptyIterator()

Возвращает итератор без элементов. Точнее,

• hasNext всегда возвращает false.
• next всегда выбрасывает NoSuchElementException.
• remove всегда выбрасывает IllegalStateException.

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

public static <T> ListIterator<T> emptyListIterator()

Возвращает список итератор без элементов. Точнее,

• hasNext и hasPrevious всегда возвращают false.
• next и previous всегда выбрасывают NoSuchElementException.
• remove и set всегда выбрасывают IllegalStateException.
• add всегда выбрасывает UnsupportedOperationException.
• nextIndex всегда возвращает 0.
• previousIndex всегда возвращает -1.

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

public static <T> Enumeration<T> emptyEnumeration()

Возвращает перечисление без элементов. Точнее,

• hasMoreElements всегда возвращает false.
• nextElement всегда выбрасывает NoSuchElementException.

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

public static final <T> Set<T> emptySet()

Возвращает пустое множество (неизменяемое). Это множество сериализуемо. В отличие от одноимённого поля, этот метод параметризован.

Этот пример демонстрирует безопасный способ получения пустого множества:

     Set<String> s = Collections.emptySet();
 

public static <E> SortedSet<E> emptySortedSet()

Возвращает пустое упорядоченное множество (неизменяемое). Это множество сериализуемо.

Этот пример демонстрирует безопасный способ получения пустого упорядоченного множества:

 
     SortedSet<String> s = Collections.emptySortedSet();
 

public static <E> NavigableSet<E> emptyNavigableSet()

Возвращает пустое навигационное множество (неизменяемое). Это множество сериализуемо.

Этот пример демонстрирует безопасный способ получения пустого навигационного множества:

 
     NavigableSet<String> s = Collections.emptyNavigableSet();
 

public static final <T> List<T> emptyList()

Возвращает пустой список (неизменяемый). Этот список сериализуем.

Этот пример демонстрирует безопасный способ получения пустого списка:

     List<String> s = Collections.emptyList();
 

public static final <K, V> Map<K,V> emptyMap()

Возвращает пустое отображение (неизменяемое). Это отображение сериализуемо.

Этот пример демонстрирует безопасный способ получения пустого отображения:

     Map<String, Date> s = Collections.emptyMap();
 

public static final <K, V> SortedMap<K,V> emptySortedMap()

Возвращает пустое упорядоченное отображение (неизменяемое). Это отображение сериализуемо.

Этот пример демонстрирует безопасный способ получения пустого отображения:

 
     SortedMap<String, Date> s = Collections.emptySortedMap();
 

public static final <K, V> NavigableMap<K,V> emptyNavigableMap()

Возвращает пустое навигационное отображение (неизменяемое). Это отображение сериализуемо.

Этот пример демонстрирует безопасный способ получения пустого отображения:

 
     NavigableMap<String, Date> s = Collections.emptyNavigableMap();
 

public static <T> Set<T> singleton(T o)

Возвращает неизменяемое множество, содержащее только указанный объект. Возвращаемое множество сериализуемо.

public static <T> List<T> singletonList(T o)

Возвращает неизменяемый список, содержащий только указанный объект. Возвращаемый список сериализуем.

public static <K, V> Map<K,V> singletonMap(K key, V value)

Возвращает неизменяемую карту, отображающую только указанный ключ на указанное значение. Возвращаемая карта сериализуема.

public static <T> List<T> nCopies(int n, T o)

Возвращает неизменяемый список, состоящий из n копий указанного объекта. Новый выделенный объект данных невелик (он содержит единственную ссылку на объект данных). Этот метод полезен в сочетании с методом List.addAll для увеличения списков. Возвращаемый список сериализуем.

public static <T> Comparator<T> reverseOrder()

Возвращает компаратор, который накладывает обратный порядок естественного упорядочения на коллекцию объектов, которые реализуют интерфейс Comparable. (Естественное упорядочение — это порядок, накладываемый собственным методом compareTo объектов). Это позволяет использовать простой подход для сортировки (или поддержания) коллекций (или массивов) объектов, которые реализуют интерфейс Comparable в обратном естественном порядке. Например, предположим, что a — это массив строк. Тогда:

          Arrays.sort(a, Collections.reverseOrder());
 

сортирует массив в обратном лексикографическом (алфавитном) порядке.

Возвращаемый компаратор сериализуем.

public static <T> Comparator<T> reverseOrder(Comparator<T> cmp)

Возвращает компаратор, который накладывает обратный порядок указанного компаратора. Если указанный компаратор null, этот метод эквивалентен reverseOrder() (иначе говоря, он возвращает компаратор, который накладывает обратный порядок естественного упорядочения на коллекцию объектов, которые реализуют интерфейс Comparable).

Возвращаемый компаратор сериализуем (предполагая, что указанный компаратор также сериализуем или null).

public static <T> Enumeration<T> enumeration(Collection<T> c)

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

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

public static <T> ArrayList<T> list(Enumeration<T> e)

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

public static int frequency(Collection<?> c, Object o)

Возвращает количество элементов в указанной коллекции, равных указанному объекту. Более формально, возвращает количество элементов e в коллекции таком, что Objects.equals(o, e).

public static boolean disjoint(Collection<?> c1, Collection<?> c2)

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

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

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

Обратите внимание, что разрешается передать одну и ту же коллекцию в обоих параметрах, в этом случае метод вернёт true тогда и только тогда, когда коллекция пуста.

@SafeVarargs public static <T> boolean addAll(Collection<? super T> c, T... elements)

Добавляет все указанные элементы в указанную коллекцию. Элементы, которые необходимо добавить, могут быть указаны по отдельности или в виде массива. Поведение этого вспомогательного метода аналогично поведению cc.addAll(Collections.unmodifiableList(Arrays.asList(elements))).

Когда элементы указываются по отдельности, этот метод предоставляет удобный способ добавить несколько элементов в существующую коллекцию:

     Collections.addAll(flavors, "Peaches 'n Plutonium", "Rocky Racoon");
 

public static <E> Set<E> newSetFromMap(Map<E,Boolean> map)

Возвращает множество, поддерживаемое указанной картой. Полученное множество отображает ту же упорядоченность, конкурентность и характеристики производительности, что и базовая карта. По сути, этот фабричный метод предоставляет реализацию Set, соответствующую любой реализации Map. Нет необходимости использовать этот метод с реализацией Map, которая уже имеет соответствующую реализацию Set (например, HashMap или TreeMap).

Каждый вызов метода на множестве, возвращенном этим методом, приводит к точно одному вызову метода на базовой карте или ее keySet представлении, за одним исключением. Метод addAll реализован как последовательность вызовов put на базовой карте.

Указанная карта должна быть пустой в момент вызова этого метода и не должна напрямую обращаться к ней после возврата этого метода. Эти условия гарантируются, если карта создается пустой, передается непосредственно в этот метод, и на карту не сохраняется ссылка, как показано в следующем фрагменте кода:

    Set<Object> weakHashSet = Collections.newSetFromMap(
        new WeakHashMap<Object, Boolean>());
 

public static <T> Queue<T> asLifoQueue(Deque<T> deque)

Возвращает представление Deque в виде очереди Last-in-first-out (Lifo) Queue. Метод add сопоставлен с push, remove сопоставлен с pop и так далее. Это представление может быть полезно, когда вам нужен метод, требующий Queue, но вам нужна упорядоченность Lifo.

Каждый вызов метода на очереди, возвращенной этим методом, приводит к точно одному вызову метода на базовой очереди, за одним исключением. Метод addAll реализован как последовательность вызовов addFirst на базовой очереди.