モジュール java.base

パッケージ java.util

クラスIdentityHashMap<K,V>

java.lang.Object

java.util.AbstractMap<K,V>

java.util.IdentityHashMap<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)の場合にかぎり2つのキーk1とk2が同等であるとみなされます。 通常は、HashMapのようなMap実装では、(k1==null ? k2==null : k1.equals(k2))の場合にかぎり2つのキーk1とk2が同等であるとみなされます。

このクラスは、汎用のMap実装ではありません。 このクラスがMapインタフェースを実装していると、オブジェクトの比較時にequalsメソッドの使用を要求するMapの一般的な規約に意図的に違反をします。 このクラスは、参照の同一性のセマンティックスが要求された場合にのみ使用されるように設計されています。

このクラスの通常の使用では、直列化またはディープ・コピーなど、トポロジを保持するオブジェクト・グラフ変換を行います。 このような変換を実行するために、プログラムは、すでに処理されたすべてのオブジェクト参照を追跡する「ノード表」を保持する必要があります。 別個のオブジェクトが等しい場合でも、ノード表はそのオブジェクトを同等視してはいけません。 このクラスのもうひとつの使用法は、プロキシ・オブジェクトを維持することです。 たとえば、デバッグ機能は、デバッグされたプログラムで各オブジェクトのプロキシ・オブジェクトを維持できます。

このクラスは、マップに関連するオプションのオペレーションをすべてサポートし、null値およびnullキーを使用できます。 このクラスはマップの順序を保証しません。特に、その順序を常に一定に保つことを保証しません。

このクラスは、システム・アイデンティティ・ハッシュ関数(System.identityHashCode(Object))が複数のバケットに要素を適切に分散させると仮定して、基本オペレーション(getおよびput)に一定時間のパフォーマンスを提供します。

このクラスにはチューニング・パラメータがひとつあります。チューニング・パラメータはセマンティックスではなく、パフォーマンスに影響を与えます。すなわち、予想最大サイズです。 このパラメータは、マップが保持されると予想されるキー値マッピングの最大数です。 このパラメータを使用して、ハッシュ表を初期構成するバケットの数を算出します。 予想された最大サイズとバケット数との正確な関係は指定されていません。

マップのサイズ(キーと値のマッピング数)が期待される最大サイズをかなりの大きさで超過する場合、バケットの数は増加します。 バケットの数の増加(ハッシュのやり直し)は非常に費用がかかるため、大きさが十分な期待される最大サイズでアイデンティティ・ハッシュを作成すると費用を抑えられます。 一方、コレクション・ビューの繰返しは、ハッシュ表のバケット数に比例した時間を要求します。そのため繰返しのパフォーマンスまたはメモリー使用に特に懸念がある場合は、予想最大サイズをあまり大きくしないようにします。

この実装はsynchronizedされません。 複数のスレッドが並行してアイデンティティ・ハッシュ・マップにアクセスし、それらのスレッドの少なくとも1つが構造的にマップを変更する場合は、外部でその同期をとる必要があります。 構造的な変更とは、1つ以上のマッピングを追加または削除するオペレーションのことです。すでにインスタンスに格納されているキーに関連付けられた値を変更することは構造的な変更ではありません。 これは通常、マップを自然にカプセル化する一部のオブジェクトでsynchronizedすることによって達成されます。 そのようなオブジェクトが存在しない場合は、Collections.synchronizedMapメソッドを使用してマップを「ラップ」することをお薦めします。 マップが誤ってsynchronizedなしでアクセスされるのを防ぐために、作成時に行うことをお薦めします。

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

このクラスのすべてのコレクション・ビュー・メソッドによって返されるコレクションのiteratorメソッドによって返されるイテレータは、フェイルファストです。イテレータの作成後に、イテレータ自体のremoveメソッド以外の方法でマップが構造的に変更されると、イテレータはConcurrentModificationExceptionをスローします。 このように、並行して変更が行われると、イテレータは、将来の予測できない時点において予測できない動作が発生する危険を回避するために、ただちにかつ手際よく例外をスローします。

通常、非同期の並行変更がある場合、確かな保証を行うことは不可能なので、イテレータのフェイルファストの動作を保証することはできません。 フェイルファスト・イテレータは、ベスト・エフォート・ベースでConcurrentModificationExceptionをスローします。 したがって、正確を期すためにこの例外に依存するプログラムを書くことは誤りです。フェイルファストのイテレータはバグを検出するためにのみ使用すべきです。

実装にあたっての注意: SedgewickとKnuthのテキストの例で説明したように、フェイルファスト・イテレータは、単純な線形プローブのハッシュ表です。 その配列は、キーと値の保持を交互に行います。 個別の配列を使って行うよりも、大きな表についてより適切な局所性があります。 多くのJRE実装とオペレーション・ミックスでは、このクラスは、(線形プローブではなくチェーンに使用する) HashMapよりも高性能のパフォーマンスをもたらします。

このクラスは、Java Collections Frameworkのメンバーです。

導入されたバージョン:

1.4

関連項目:

System.identityHashCode(Object), Object.hashCode(), Collection, Map, HashMap, TreeMap, 直列化された形式

ネストされたクラスのサマリー

クラス 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)	指定されたオブジェクトがこのマップと等しいかどうかを比較します。
void	forEach(BiConsumer<? super K,? super V> action)	このマップのすべてのエントリの処理が完了するかアクションから例外がスローされるまで、各エントリに対して指定されたアクションを実行します。
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)	キーに対するマッピングがあれば、そのキーをマップから削除します。
void	replaceAll(BiFunction<? super K,? super V,? extends V> function)	すべてのエントリが処理されるか、または関数が例外をスローするまで、各エントリの値を、そのエントリで指定された関数を呼び出した結果で置換します。
int	size()	このアイデンティティ・ハッシュ・マップ内のキーと値のマッピングの数を返します。
Collection<V>	values()	このマップに含まれる値のCollectionビューを返します。

クラス java.util.AbstractMapから継承されたメソッド

toString

インタフェース java.util.Mapから継承されたメソッド

compute, computeIfAbsent, computeIfPresent, entry, getOrDefault, merge, of, of, of, of, of, of, of, of, of, of, of, ofEntries, putIfAbsent, remove, replace, replace

クラス java.lang.Objectから継承されたメソッド

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

コンストラクタの詳細

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を返します。

つまり、このメソッドは、(key == k)となるキーkから値vへのマッピングがこのマップに含まれている場合はvを返し、それ以外の場合はnullを返します。 (このようなマッピングは1つのみ存在できます。)

戻り値nullは、マップがキーのマッピングを保持していないことを示すとはかぎりません。つまり、マップが明示的にキーをnullにマップすることもあります。 containsKeyオペレーションを使うと、これらの2つの場合を区別できます。

定義:

get、インタフェース: Map<K,V>

オーバーライド:

get、クラス: AbstractMap<K,V>

パラメータ:

key - 関連付けられた値が返されるキー

戻り値:

指定されたキーがマップされている値。このマップにそのキーのマッピングが含まれていない場合はnull

関連項目:

put(Object, Object)

containsKey

public boolean containsKey(Object key)

指定されたオブジェクト参照が、このアイデンティティ・ハッシュ・マップのキーかどうかを判定します。

定義:

containsKey、インタフェース: Map<K,V>

オーバーライド:

containsKey、クラス: AbstractMap<K,V>

パラメータ:

key - 使用可能なキー

戻り値:

指定されたオブジェクト参照がマップのキーである場合は、true

関連項目:

containsValue(Object)

containsValue

public boolean containsValue(Object value)

指定されたオブジェクト参照が、このアイデンティティ・ハッシュ・マップの値かどうかを判定します。

定義:

containsValue、インタフェース: Map<K,V>

オーバーライド:

containsValue、クラス: AbstractMap<K,V>

パラメータ:

value - このマップにあるかどうかが判定される値

戻り値:

このマップが1つまたは複数のキーと指定されたオブジェクト参照をマッピングしている場合はtrue

関連項目:

containsKey(Object)

put

public V put(K key,
             V value)

指定された値と指定されたキーをこのアイデンティティ・ハッシュ・マップに関連付けます。 マップが以前にこのキーのマッピングを保持していた場合、古い値が置き換えられます。

定義:

put、インタフェース: Map<K,V>

オーバーライド:

put、クラス: AbstractMap<K,V>

パラメータ:

key - 指定された値が関連付けられるキー

value - 指定されたキーに関連付けられる値

戻り値:

keyに以前に関連付けられていた値。keyのマッピングが存在しなかった場合はnull。 (戻り値nullは、マップが以前にnullとkeyを関連付けていたことを示す場合もある)

関連項目:

Object.equals(Object), get(Object), containsKey(Object)

putAll

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

指定されたマップからすべてのマッピングをマップにコピーします。 これにより、マップが指定されたマップ内に現在あるキーのすべてに対して持っていたマッピングが置き換えられます。

定義:

putAll、インタフェース: Map<K,V>

オーバーライド:

putAll、クラス: AbstractMap<K,V>

パラメータ:

m - このマップに格納されるマッピング

例外:

NullPointerException - 指定されたマップがnullの場合

remove

public V remove(Object key)

キーに対するマッピングがあれば、そのキーをマップから削除します。

定義:

remove、インタフェース: Map<K,V>

オーバーライド:

remove、クラス: AbstractMap<K,V>

パラメータ:

key - マッピングがマップから削除されるキー

戻り値:

keyに以前に関連付けられていた値。keyのマッピングが存在しなかった場合はnull。 (戻り値nullは、マップが以前にnullとkeyを関連付けていたことを示す場合もある)

clear

public void clear()

すべてのマッピングをマップから削除します。 この呼出しが戻ると、マップは空になります。

定義:

clear、インタフェース: Map<K,V>

オーバーライド:

clear、クラス: AbstractMap<K,V>

equals

public boolean equals(Object o)

指定されたオブジェクトがこのマップと等しいかどうかを比較します。 指定されたオブジェクトがマップでもあり、2つのマップが同じオブジェクト参照マッピングを表す場合は、trueを返します。 つまり、this.entrySet().equals(m.entrySet())にかぎり、このマップは別のマップmと等しくなります。

このマップが通常のマップと比較される場合、このマップの参照同一性ベースのセマンティックスによって、Object.equals規約のシンメトリと移行の要件に違反することができます。 ただし、Object.equals規約は、複数のIdentityHashMapインスタンス間に保持することが保証されています。

定義:

equals、インタフェース: Map<K,V>

オーバーライド:

equals、クラス: AbstractMap<K,V>

パラメータ:

o - このマップと等しいかどうかが比較されるオブジェクト

戻り値:

指定されたオブジェクトがこのマップと等しい場合はtrue

関連項目:

Object.equals(Object)

hashCode

public int hashCode()

マップのハッシュ・コード値を返します。 マップのハッシュ・コードは、そのマップのentrySet()ビュー内の各エントリのハッシュ・コードの合計になるように定義されます。 これにより、Object.hashCode()の一般規約によって要求されるように、任意の2つのIdentityHashMapインスタンスm1とm2でm1.equals(m2)であれば、m1.hashCode()==m2.hashCode()となることが保証されます。

比較されている2つのオブジェクトがそれぞれIdentityHashMapインスタンスと通常のマップである場合は、このマップのentrySetメソッドによって返されたセット内にあるMap.Entryインスタンスの参照同一性ベースのセマンティックスによって、前の段落で説明されていたObject.hashCodeの規約上の要件に違反することができます。

定義:

hashCode、インタフェース: Map<K,V>

オーバーライド:

hashCode、クラス: AbstractMap<K,V>

戻り値:

マップのハッシュ・コード値

関連項目:

Object.equals(Object), equals(Object)

clone

public Object clone()

アイデンティティ・ハッシュ・マップのシャロー・コピーを返します。キーと値は、それ自体は複製されません。

オーバーライド:

clone、クラス: AbstractMap<K,V>

戻り値:

このマップのシャロー・コピー

関連項目:

Cloneable

keySet

public Set<K> keySet()

マップに格納されているキーのアイデンティティ・ベースのセット・ビューを返します。 セットはマップと連動しているので、マップに対する変更はセットに反映され、また、セットに対する変更はマップに反映されます。 セットの反復処理中にマップが変更された場合は、反復処理の結果は定義されません。 セットは要素の削除をサポートします。Iterator.remove、Set.remove、removeAll、retainAll、clearの各メソッドを使って対応するマッピングをマップから削除します。 addまたはaddAllメソッドはサポートしていません。

このメソッドが返したオブジェクトが、Setインタフェースを実装している間、オブジェクトは、Setの一般規約には従いません。 オブジェクトの元になるマップのように、このメソッドが返したセットは、オブジェクトの同一性でなく、参照の同一性として、要素の同一性を定義します。 このことは、オブジェクトのcontains、remove、containsAll、equals、およびhashCodeメソッドの動作に影響を与えます。

指定されたオブジェクトが、返されたセットとまったく同じオブジェクト参照を含むセットである場合にかぎり、返されたセットのequalsメソッドはtrueを返します。 このメソッドによって返されたセットが通常のセットと比較される場合、Object.equals規約のシンメトリと移行の要件に違反する場合があります。 ただし、Object.equals規約は、このメソッドによって返されたセット間に保持することが保証されています。

返されたセットのhashCodeメソッドは、要素のハッシュ・コードの合計ではなく、セット内の要素のアイデンティティ・ハッシュコードの合計を返します。 これは、このメソッドが返した複数のセットに、Object.hashCodeメソッドの一般規約を適用するために、equalsメソッドのセマンティックスの変更によって要求されます。

定義:

keySet、インタフェース: Map<K,V>

オーバーライド:

keySet、クラス: AbstractMap<K,V>

戻り値:

マップに含まれているキーのアイデンティティ・ベースのセット・ビュー

関連項目:

Object.equals(Object), System.identityHashCode(Object)

values

public Collection<V> values()

このマップに含まれる値のCollectionビューを返します。 コレクションはマップと連動しているので、マップに対する変更はコレクションに反映され、またコレクションに対する変更はマップに反映されます。 コレクションの反復処理中にマップが変更された場合は、反復処理の結果は定義されません。 コレクションは要素の削除をサポートします。Iterator.remove、Collection.remove、removeAll、retainAll、clearの各メソッドを使って対応するマッピングをマップから削除します。 addまたはaddAllメソッドはサポートしていません。

このメソッドが返したオブジェクトが、Collectionインタフェースを実装している間、オブジェクトは、Collectionの一般規約には従いません。 オブジェクトの元になるマップのように、このメソッドが返すコレクションは、オブジェクトの同一性でなく、参照の同一性として、要素の同一性を定義します。 このことは、オブジェクトの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オブジェクトは、オブジェクトの同一性でなく、参照の同一性として、キーと値の同一性を定義します。 これは、Map.EntryオブジェクトのequalsおよびhashCodeメソッドの動作に影響を与えます。 参照同一性ベースのMap.Entry eは、oがMap.Entryおよびe.getKey()==o.getKey()&& e.getValue()==o.getValue()である場合にかぎりoオブジェクトに等しくなります。 こうした等しいセマンティックスに対応するために、hashCodeメソッドは、System.identityHashCode(e.getKey())^System.identityHashCode(e.getValue())を返します。

セットのエントリを通常のマップ・エントリと比較した場合、または、このメソッドが返したセットを通常のマップ・エントリ(通常のマップにこのメソッドを呼び出すことで返されている)のセットと比較した場合に、このメソッドによって返されたセット内の、Map.Entryインスタンスの参照同一性ベースのセマンティックスによって、Object.equals(Object)規約のシンメトリと移行の要件に違反できます。 ただし、Object.equals規約は、複数のアイデンティティ・ベースのマップ・エントリ、およびこのようなエントリの複数のセット間に保持することが保証されています。

定義:

entrySet、インタフェース: Map<K,V>

定義:

entrySet、クラス: AbstractMap<K,V>

戻り値:

このマップ内に含まれているアイデンティティ・マッピングのセット・ビュー

forEach

public void forEach(BiConsumer<? super K,? super V> action)

インタフェースからコピーされた説明: Map

このマップのすべてのエントリの処理が完了するかアクションから例外がスローされるまで、各エントリに対して指定されたアクションを実行します。 実装クラスで指定されない場合は、エントリ・セットの反復の順序でアクションが実行されます(反復順序が指定されている場合)。 アクションによってスローされた例外は、呼出し側に中継されます。

定義:

forEach、インタフェース: Map<K,V>

パラメータ:

action - 各エントリに対して実行されるアクション

replaceAll

public void replaceAll(BiFunction<? super K,? super V,? extends V> function)

インタフェースからコピーされた説明: Map

すべてのエントリが処理されるか、または関数が例外をスローするまで、各エントリの値を、そのエントリで指定された関数を呼び出した結果で置換します。 関数によってスローされた例外は、呼出し側に中継されます。

定義:

replaceAll、インタフェース: Map<K,V>

パラメータ:

function - 各エントリに適用する関数