Класс IdentityHashMap<K,V>

java.lang.Object

java.util.AbstractMap<K,V>

java.util.IdentityHashMap<K,V>

Type Parameters:: K - тип ключей, поддерживаемых этой картой; V - тип сопоставленных значений

All Implemented Interfaces:: Serializable, Cloneable, Map<K,V>

public class IdentityHashMap<K,V> extends AbstractMap<K,V> implements Map<K,V>, Serializable, Cloneable

Этот класс реализует интерфейс Map с помощью хэш-таблицы, используя сравнение ссылок вместо сравнения объектов при сравнении ключей (и значений). Другими словами, в IdentityHashMap, два ключа k1 и k2 считаются равными тогда и только тогда, когда (k1==k2). (В обычных реализациях Map (например, HashMap) два ключа k1 и k2 считаются равными тогда и только тогда, когда (k1==null ? k2==null : k1.equals(k2)).)

Этот класс — не общая реализация Map! Хотя этот класс реализует интерфейс Map, он намеренно нарушает общий контракт Map's, который требует использования метода equals при сравнении объектов. Этот класс предназначен только для редких случаев, когда требуется семантика равенства ссылок.

Коллекции представлений этой карты также имеют семантику равенства ссылок для своих элементов. См. методы keySet, values и entrySet для получения дополнительной информации.

Типичное использование этого класса — преобразования графов объектов, сохраняющие топологию, такие как сериализация или глубокое копирование. Для выполнения такого преобразования программа должна поддерживать «таблицу узлов», которая отслеживает все объекты-ссылки, которые уже были обработаны. Таблица узлов не должна приравнивать различные объекты, даже если они случайным образом оказываются равными. Еще одно типичное использование этого класса — поддержание объектов-прокси. Например, средство отладки может захотеть поддерживать объект-прокси для каждого объекта в отлаживаемой программе.

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

Этот класс обеспечивает постоянное время выполнения для основных операций (get и put), предполагая, что функция хэширования системы идентификации (System.identityHashCode(Object)) правильно распределяет элементы по корзинам.

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

Если размер карты (количество пар ключ-значение) существенно превышает ожидаемый максимальный размер, количество корзин увеличивается. Увеличение количества корзин («перехеширование») может быть довольно дорогостоящим, поэтому имеет смысл создавать карты с идентификацией с достаточно большим ожидаемым максимальным размером. С другой стороны, итерация по представлениям коллекций требует времени, пропорционального числу корзин в хэш-таблице, поэтому не имеет смысла устанавливать ожидаемый максимальный размер слишком высоким, если вы особенно обеспокоены производительностью итераций или использованием памяти.

Обратите внимание, что эта реализация не синхронизирована. Если несколько потоков одновременно обращаются к карте с идентификацией и хотя бы один из потоков изменяет карту структурно, она должна быть синхронизирована внешним образом. (Структурное изменение — любая операция, добавляющая или удаляющая одну или несколько пар; простое изменение значения, связанного с ключом, уже содержащимся в экземпляре, не является структурным изменением.) Обычно это достигается синхронизацией на каком-либо объекте, естественным образом encapsulating карту. Если такого объекта нет, карта должна быть «обернута» с помощью метода Collections.synchronizedMap. Лучше всего это сделать во время создания, чтобы предотвратить случайный несинхронизированный доступ к карте:

   Map m = Collections.synchronizedMap(new IdentityHashMap(...));

Итераторы, возвращаемые методом iterator для коллекций, возвращаемых всеми методами «представления коллекций» этого класса, являются быстродействующими: если карта изменяется структурно в любое время после создания итератора, каким-либо способом, кроме метода самого итератора remove, итератор сгенерирует исключение ConcurrentModificationException. Таким образом, при одновременном изменении итератор быстро и чисто завершает работу, а не рискует произвольным неопределённым поведением в неопределенное время в будущем.

Обратите внимание, что поведение fail-fast итератора не может быть гарантировано, так как в принципе невозможно дать какие-либо твердые гарантии при одновременном несинхронизированном изменении. Итераторы fail-fast генерируют исключение ConcurrentModificationException по принципу наилучшего результата. Поэтому неправильно писать программу, которая полагается на это исключение для правильности: итераторы fail-fast следует использовать только для обнаружения ошибок.

Этот класс является членом Java Collections Framework.

Implementation Note:

Это простая хэш-таблица с линейным зондированием, как описано, например, в текстах Сэджвика и Кнута. Массив содержит чередующиеся ключи и значения, с ключами на чётных индексах и значениями на нечётных индексах. (Это расположение имеет лучшие локальные свойства для больших таблиц, чем использование отдельных массивов.) Для многих реализаций Java и сочетаний операций этот класс обеспечит лучшую производительность, чем HashMap, который использует цепление вместо линейного зондирования.

Since:

1.4

See Also:

END_OF_DOCUMENT_MARKER

Краткое описание вложенных классов

Вложенные классы/интерфейсы, объявленные в классе java.util.AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

Вложенные классы/интерфейсы, объявленные в интерфейсе java.util.Map

Map.Entry<K,V>

Краткое описание конструкторов

Конструктор	Описание
`IdentityHashMap()`	Создаёт новый, пустой идентичный хеш-мап с ожидаемым максимальным размером по умолчанию (21).
`IdentityHashMap(int expectedMaxSize)`	Создаёт новый, пустой мап с указанным ожидаемым максимальным размером.
`IdentityHashMap(Map<? extends K,? extends V> m)`	Создаёт новый идентичный хеш-мап, содержащий сопоставления ключей и значений из указанного мапа.

Краткое описание методов

Модификатор и тип	Метод	Описание
`void`	`clear()`	Удаляет все сопоставления из этого мапа.
`Object`	`clone()`	Возвращает неглубокую копию этого идентичного хеш-мапа: сами ключи и значения не клонируются.
`boolean`	`containsKey(Object key)`	Проверяет, является ли указанная ссылка на объект ключом в этом идентичном хеш-мапе.
`boolean`	`containsValue(Object value)`	Проверяет, является ли указанная ссылка на объект значением в этом идентичном хеш-мапе.
`Set<Map.Entry<K,V>>`	`entrySet()`	Возвращает представление `Set` сопоставлений, содержащихся в этом мапе.
`boolean`	`equals(Object o)`	Сравнивает указанный объект с этим мапом на равенство.
`V`	`get(Object key)`	Возвращает значение, которому сопоставлен указанный ключ, или `null` если в этом мапе нет сопоставления для ключа.
`int`	`hashCode()`	Возвращает значение хэш-кода для этого мапа.
`boolean`	`isEmpty()`	Возвращает `true` если в этом идентичном хеш-мапе нет сопоставлений ключ-значение.
`Set<K>`	`keySet()`	Возвращает представление множества, основанное на идентичности, ключей, содержащихся в этом мапе.
`V`	`put(K key, V value)`	Связывает указанное значение с указанным ключом в этом идентичном хеш-мапе.
`void`	`putAll(Map<? extends K,? extends V> m)`	Копирует все сопоставления из указанного мапа в этот мап.
`V`	`remove(Object key)`	Удаляет сопоставление для этого ключа из этого мапа, если оно присутствует.
`boolean`	`remove(Object key, Object value)`	Удаляет запись для указанного ключа только в том случае, если она в настоящее время сопоставлена с указанным значением.
`boolean`	`replace(K key, V oldValue, V newValue)`	Заменяет запись для указанного ключа только в том случае, если она в настоящее время сопоставлена с указанным значением.
`int`	`size()`	Возвращает количество пар ключ-значение в этом идентичном хеш-мапе.
`Collection<V>`	`values()`	Возвращает представление `Collection` значений, содержащихся в этом мапе.

Методы, объявленные в классе java.util.AbstractMap

toString

Методы, объявленные в классе java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Методы, объявленные в интерфейсе java.util.Map

compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, replace, replaceAll

Подробное описание конструкторов

IdentityHashMap

public IdentityHashMap()

Создаёт новую пустую карту по ссылкам с ожидаемым максимальным размером по умолчанию (21).

IdentityHashMap

public IdentityHashMap(int expectedMaxSize)

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

Параметры:: expectedMaxSize - ожидаемый максимальный размер карты
Исключения:: IllegalArgumentException - если expectedMaxSize отрицательное

IdentityHashMap

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

Создаёт новую карту по ссылкам, содержащую пары ключ-значение из указанной карты.

Параметры:: m - карта, чьи пары ключ-значение должны быть помещены в эту карту
Исключения:: NullPointerException - если указанная карта равна null

Подробное описание методов

size

public int size()

Возвращает количество пар ключ-значение в этой карте по ссылкам.

Определено в:: size в интерфейсе Map<K,V>
Переопределяет:: size в классе AbstractMap<K,V>
Возвращает:: количество пар ключ-значение в этой карте

isEmpty

public boolean isEmpty()

Возвращает true если эта карта по ссылкам не содержит пар ключ-значение.

Определено в:: isEmpty в интерфейсе Map<K,V>
Переопределяет:: isEmpty в классе AbstractMap<K,V>
Возвращает:: true если эта карта по ссылкам не содержит пар ключ-значение

get

public V get(Object key)

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

Более формально, если эта карта содержит сопоставление от ключа k до значения v, такое что (key == k), то этот метод возвращает v; в противном случае он возвращает null. (Может быть не более одного такого сопоставления.)

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

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

get в интерфейсе Map<K,V>

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

get в классе AbstractMap<K,V>

Параметры:

key - ключ, связанное значение которого требуется вернуть

Возвращает:

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

См. также:

containsKey

public boolean containsKey(Object key)

Проверяет, является ли указанный объект ссылкой на ключ в этой карте по ссылкам. Возвращает true тогда и только тогда, когда эта карта содержит сопоставление с ключом k таким, что (key == k).

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

containsKey в интерфейсе Map<K,V>

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

containsKey в классе AbstractMap<K,V>

Параметры:

key - возможный ключ

Возвращает:

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

См. также:

containsValue

public boolean containsValue(Object value)

Проверяет, является ли указанный объект ссылкой на значение в этой карте по ссылкам. Возвращает true тогда и только тогда, когда эта карта содержит сопоставление со значением v таким, что (value == v).

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

containsValue в интерфейсе Map<K,V>

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

containsValue в классе AbstractMap<K,V>

Параметры:

value - значение, присутствие которого в этой карте требуется проверить

Возвращает:

true если эта карта сопоставляет один или несколько ключей со значением указанного объекта

См. также:

put

public V put(K key, V value)

Связывает указанное значение с указанным ключом в этой карте по ссылкам. Если в этой карте уже contains существует сопоставление для ключа, старое значение заменяется, в противном случае в карту вставляется новое сопоставление.

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

put в интерфейсе Map<K,V>

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

put в классе AbstractMap<K,V>

Параметры:

key - ключ, с которым должно быть связано указанное значение

value - значение, которое должно быть связано с указанным ключом

Возвращает:

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

См. также:

putAll

public void putAll(Map<? extends K,? extends V> m)

Копирует все сопоставления из указанной карты в эту карту. Для каждого сопоставления в указанной карте, если в этой карте уже contains существует сопоставление для ключа, его значение заменяется значением из указанной карты; в противном случае в эту карту вставляется новое сопоставление.

Определено в:: putAll в интерфейсе Map<K,V>
Переопределяет:: putAll в классе AbstractMap<K,V>
Параметры:: m - сопоставления, которые должны быть сохранены в этой карте
Исключения:: NullPointerException - если указанная карта равна null

remove

public V remove(Object key)

Удаляет сопоставление для этого ключа из этой карты, если оно существует. Сопоставление удаляется тогда и только тогда, когда сопоставление имеет ключ k такой, что (key == k).

Определено в:: remove в интерфейсе Map<K,V>
Переопределяет:: remove в классе AbstractMap<K,V>
Параметры:: key - ключ, сопоставление которого должно быть удалено из карты
Возвращает:: предыдущее значение, связанное с key, или null если для key не было сопоставления. (Возвращаемое значение null также может указывать, что карта ранее связывала null со значением key).

clear

public void clear()

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

Определено в:: clear в интерфейсе Map<K,V>
Переопределяет:: clear в классе AbstractMap<K,V>

equals

public boolean equals(Object o)

Сравнивает указанный объект с этой картой на равенство. Возвращает true если данный объект также является картой, и две карты представляют одинаковые сопоставления по ссылкам. Более формально, эта карта равна другой карте m тогда и только тогда, когда this.entrySet().equals(m.entrySet()). См. метод entrySet для спецификации равенства элементов этой карты.

Из-за основанной на равенстве по ссылке семантики этой карты возможно, что требования симметрии и транзитивности контракта Object.equals могут быть нарушены, если эта карта сравнивается с обычной картой. Однако, контракт Object.equals гарантированно выполняется между экземплярами IdentityHashMap.

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

equals в интерфейсе Map<K,V>

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

equals в классе AbstractMap<K,V>

Параметры:

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

Возвращает:

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

См. также:

hashCode

public int hashCode()

Возвращает значение хэш-кода для этой карты. Хэш-код карты определяется как сумма хэш-кодов каждой записи этой карты. См. метод entrySet для спецификации хэш-кода записей этой карты.

Данная спецификация гарантирует, что m1.equals(m2) подразумевает, что m1.hashCode()==m2.hashCode() для любых двух IdentityHashMap экземпляров m1 и m2, как требуется общим соглашением Object.hashCode().

Из-за основанной на равенстве ссылок семантики экземпляров Map.Entry в множестве, возвращаемом методом entrySet этой карты, возможно, что договорённое требование Object.hashCode упомянутое в предыдущем абзаце, будет нарушено, если один из двух сравниваемых объектов является экземпляром IdentityHashMap и другой – обычной картой.

Specified by:

hashCode в интерфейсе Map<K,V>

Overrides:

hashCode в классе AbstractMap<K,V>

Returns:

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

See Also:

clone

public Object clone()

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

Overrides:

clone в классе AbstractMap<K,V>

Returns:

неглубокая копия этой карты

See Also:

keySet

public Set<K> keySet()

Возвращает представление множества ключей, содержащихся в этой карте, основанное на идентичности. Множество подкрепляется картой, поэтому изменения в карте отражаются в множестве, и наоборот. Если карта изменяется во время итерации по множеству, результаты итерации не определены. Множество поддерживает удаление элементов, которое удаляет соответствующее отображение из карты, посредством методов Iterator.remove, Set.remove, removeAll, retainAll, и clear. Оно не поддерживает методы add или addAll.

Хотя возвращаемый этим методом объект реализует интерфейс Set, он не подчиняется общему соглашению Set's. Как и её подкрепляющая карта, множество, возвращаемое этим методом, определяет равенство элементов как равенство ссылок, а не равенство объектов. Это влияет на поведение методов contains, remove, containsAll, equals, и hashCode

Метод equals возвращаемого множества возвращает true только в том случае, если указанный объект является множеством, содержащим ровно те же ссылки на объекты, что и возвращаемое множество. Требования симметрии и транзитивности контракта Object.equals могут быть нарушены, если возвращаемое этим методом множество сравнивается с обычным множеством. Тем не менее, контракт Object.equals гарантированно соблюдается для множеств, возвращаемых этим методом.

Метод hashCode возвращаемого множества возвращает сумму хэш-кодов по ссылке элементов в множестве, а не сумму их хэш-кодов. Это предписано изменением семантики метода equals, чтобы обеспечить соблюдение общего соглашения метода Object.hashCode для множеств, возвращаемых этим методом.

Specified by:

keySet в интерфейсе Map<K,V>

Overrides:

keySet в классе AbstractMap<K,V>

Returns:

представление множества ключей, содержащихся в этой карте, основанное на идентичности

See Also:

values

public Collection<V> values()

Возвращает представление Collection значений, содержащихся в этой карте. Коллекция подкрепляется картой, поэтому изменения в карте отражаются в коллекции, и наоборот. Если карта изменяется во время итерации по коллекции, результаты итерации не определены. Коллекция поддерживает удаление элементов, которое удаляет соответствующее отображение из карты, посредством методов Iterator.remove, Collection.remove, removeAll, retainAll и clear . Она не поддерживает методы add или addAll.

Хотя возвращаемый этим методом объект реализует интерфейс Collection, он не подчиняется общему соглашению Collection's. Как и её подкрепляющая карта, коллекция, возвращаемая этим методом, определяет равенство элементов как равенство ссылок, а не равенство объектов. Это влияет на поведение методов contains, remove и containsAll

Specified by:: values в интерфейсе Map<K,V>
Overrides:: values в классе AbstractMap<K,V>
Returns:: представление коллекции значений, содержащихся в этой карте

entrySet

public Set<Map.Entry<K,V>> entrySet()

Возвращает представление Set отображений, содержащихся в этой карте. Каждый элемент в возвращаемом множестве представляет собой основанное на равенстве ссылок Map.Entry. Множество подкрепляется картой, поэтому изменения в карте отражаются в множестве, и наоборот. Если карта изменяется во время итерации по множеству, результаты итерации не определены. Множество поддерживает удаление элементов, которое удаляет соответствующее отображение из карты, посредством методов Iterator.remove, Set.remove, removeAll, retainAll и clear. Оно не поддерживает методы add или addAll.

Как и подкрепляющая карта, объекты Map.Entry в множестве, возвращаемом этим методом, определяют равенство ключей и значений как равенство ссылок, а не равенство объектов. Это влияет на поведение методов equals и hashCode этих объектов Map.Entry. Основанное на равенстве ссылок Map.Entry e равно объекту o тогда и только тогда, когда o является Map.Entry и e.getKey()==o.getKey() && e.getValue()==o.getValue(). Чтобы учесть эти семантики равенства, метод hashCode возвращает System.identityHashCode(e.getKey()) ^ System.identityHashCode(e.getValue()). (Хотя ключи и значения сравниваются с использованием равенства ссылок, сами объекты Map.Entry не являются таковыми.)

Из-за семантики равенства ссылок экземпляров Map.Entry в множестве, возвращаемом этим методом, возможно, что требования симметрии и транзитивности контракта Object.equals(Object) могут быть нарушены, если любая из записей в множестве сравнивается с обычной записью карты или если множество, возвращаемое этим методом, сравнивается с множеством обычных записей карты (например, возвращаемым этим методом для обычной карты). Однако контракт Object.equals гарантированно выполняется среди записей идентифицируемой карты и среди множеств таких записей.

Specified by:: entrySet в интерфейсе Map<K,V>
Returns:: множество представлений идентифицируемых отображений, содержащихся в этой карте

remove

public boolean remove(Object key, Object value)

Удаляет запись для указанного ключа только в том случае, если она в настоящее время отображается на указанное значение.

Более формально, если эта карта содержит отображение от ключа k к значению v, такое что (key == k) и (value == v), то этот метод удаляет отображение для этого ключа и возвращает true; в противном случае возвращает false.

Specified by:: remove в интерфейсе Map<K,V>
Parameters:: key - ключ, с которым связано указанное значение; value - значение, ожидаемое для данного ключа
Returns:: true если значение было удалено

replace

public boolean replace(K key, V oldValue, V newValue)

Заменяет запись для указанного ключа только в том случае, если она в настоящее время отображается на указанное значение.

Более формально, если эта карта содержит отображение от ключа k к значению v, такое что (key == k) и (oldValue == v), то этот метод связывает k со newValue и возвращает true; в противном случае возвращает false.

Specified by:: replace в интерфейсе Map<K,V>
Parameters:: key - ключ, с которым связано указанное значение; oldValue - ожидаемое значение для указанного ключа; newValue - значение, которое должно быть связано с указанным ключом
Returns:: true если значение было заменено

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/IdentityHashMap.html