Класс IdentityHashMap<K,V>

java.lang.Object

java.util.AbstractMap<K,V>

java.util.IdentityHashMap<K,V>

Параметры типа:: K - тип ключей, хранящихся в этой карте; V - тип сопоставленных значений

Все реализуемые интерфейсы:: 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)) равномерно распределяет элементы по корзинам.

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

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

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

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

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

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

Этот класс входит в состав Java Collections Framework.

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

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

Начиная с:

1.4

См. также:

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

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

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

Вложенные классы/интерфейсы, объявленные в интерфейсе 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`.

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

toString

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

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

Методы, объявленные в интерфейсе 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, а другой — обычной картой.

Указан в:

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

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

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

Возвращает:

хеш-код этой карты

См. также:

clone

public Object clone()

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

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

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

Возвращает:

поверхностную копию этой карты

См. также:

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 для множеств, возвращаемых этим методом.

Указан в:

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

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

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

Возвращает:

представление ключей этой карты в виде множества, основанного на идентичности объектов

См. также:

values

public Collection<V> values()

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

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

Указан в:: values в интерфейсе Map<K,V>
Переопределяет:: values в классе AbstractMap<K,V>
Возвращает:: представление значений этой карты в виде коллекции

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(). Чтобы обеспечить такую семантику equals, метод hashCode возвращает System.identityHashCode(e.getKey()) ^ System.identityHashCode(e.getValue()). (Хотя ключи и значения сравниваются по ссылкам, сами объекты Map.Entry — нет.)

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

Указан в:: entrySet в интерфейсе Map<K,V>
Возвращает:: представление содержащихся в этой карте соответствий идентификаторов в виде множества

remove

public boolean remove(Object key, Object value)

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

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

Указан в:: remove в интерфейсе Map<K,V>
Параметры:: key — ключ, с которым связано указанное значение; value — значение, которое предположительно связано с указанным ключом
Возвращает:: true, если значение было удалено

replace

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

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

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

Указан в:: replace в интерфейсе Map<K,V>
Параметры:: key — ключ, с которым связано указанное значение; oldValue — значение, которое предположительно связано с указанным ключом; newValue — значение, которое нужно связать с указанным ключом
Возвращает:: true, если значение было заменено

© 1993, 2025, 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/25/docs/api/java.base/java/util/IdentityHashMap.html