Map (Java Platform SE 6)

Map インタフェースが提供する 3 つのコレクションビューにより、マップの内容を、キーのセット、値のコレクション、あるいはキーと値のマッピングのセットとして表示できるようになります。マップの「順序」は、マップのコレクションビューの反復子が要素を返すときの順序として定義されます。TreeMap クラスなど一部のマップの実装では、順序について保証しますが、HashMap クラスなどの実装では順序は保証されません。

注:可変オブジェクトをマップキーとして使用する場合は細心の注意が必要です。オブジェクトがマップ内のキーであるときに、equals の比較に影響を与える方法でオブジェクトの値が変更された場合、マップの動作は保証されません。この禁止事項の特殊な例として、マップがそれ自身をキーとして持つことができないことが挙げられます。マップがそれ自身を値として持つことは許可されますが、その場合は細心の注意が必要です。そのようなマップでは equals メソッドおよび hashCode メソッドの動作は保証されません。

汎用マップの実装クラスはすべて、次の 2 つの標準的なコンストラクタを提供するようにしてください。2 つの標準的なコンストラクタとは、void (引数なし) コンストラクタと、Map 型の引数を 1 つとるコンストラクタです。前者は空のマップを作成し、後者は同じキーと値のマッピングを引数として持つ新しいマップを作成します。その結果、ユーザーは、後者のコンストラクタを使用して任意のマップをコピーすることにより、必要なクラスと等価なマップを作成できます。

これは強制的なものではありませんが (インタフェースがコンストラクタを持つことができないため)、JDK での汎用マップの実装はすべてこれに従っています。このマップがオペレーションをサポートしていない場合、このインタフェース (処理されるマップを修正するメソッド) に含まれている「破壊的な」メソッドは、UnsupportedOperationException をスローするように指定されています。このとき、呼び出しがマップに影響を及ぼさない場合、これらのメソッドは UnsupportedOperationException をスローすることがありますが、必須ではありません。たとえば、マッピングを「重ね合わせる」マップが空の場合に、変更不可能なマップで putAll(Map) メソッドを呼び出すと、例外をスローすることがありますが、必須ではありません。

マップの実装には、格納できるキーと値に制限があるものもあります。たとえば、null キーと null 値を禁止する実装や、null キーの型に制限がある実装もあります。不適当なキーまたは値を挿入しようとすると、通常 NullPointerException または ClassCastException のようなチェックされない例外がスローされます。不適当なキーや値があるかどうかを照会しようとすると、例外をスローする場合や、ただ false を返す場合もあります。前の動作を禁止する実装もあれば、後の動作を禁止する実装もあります。多くの場合は、マップに不適格な要素を挿入しない不適格なキーまたは値を処理しようとすると、実装の裁量で、例外がスローされる場合や、処理が有効になる場合があります。このインタフェースに関するそうした例外は、「任意」の仕様としてマークされます。

このインタフェースは、Java Collections Framework のメンバーです。

Collections Framework インタフェース内の多数のメソッドは、equals メソッドとの関連で定義されます。たとえば、containsKey(Object key) メソッドの仕様は、「このマップコレクションに (key==null ?k==null : key.equals(k)) を満たすキー k が含まれる場合にのみ、true を返す」というものです。."この仕様は、「null 以外の引数 key を使用して Map.containsKey を呼び出すと、キー k で key.equals(k) が呼び出される」と理解すべきではありません。実装は、最初に 2 つのキーのハッシュコードを比較するなど、equals 呼び出しを回避するための最適化を自由に実装できます。(Object.hashCode() 仕様では、等価ではないハッシュコードを保持する 2 つのオブジェクトは等価ではないことが保証されます)。通常、さまざまな Collections Framework インタフェースの実装で、実装者が適切と判断するなら、基盤となる Object メソッドの指定された動作を自由に利用できます。

導入されたバージョン:: 1.2
関連項目:: HashMap, TreeMap, Hashtable, SortedMap, Collection, Set

入れ子のクラスの概要
`static interface`	`Map.Entry<K,V>` マップのエントリ (キーと値のペア) です。

メソッドの概要
`void`	`clear()` マップからマッピングをすべて削除します (任意のオペレーション)。
`boolean`	`containsKey(Object key)` マップが指定のキーのマッピングを保持する場合に `true` を返します。
`boolean`	`containsValue(Object value)` マップが 1 つまたは複数のキーと指定された値をマッピングしている場合に `true` を返します。
`Set<Map.Entry<K,V>>`	`entrySet()` このマップに含まれるマップの `Set` ビューを返します。
`boolean`	`equals(Object o)` 指定されたオブジェクトがこのマップと等しいかどうかを比較します。
`V`	`get(Object key)` 指定されたキーがマップされている値を返します。
`int`	`hashCode()` マップのハッシュコード値を返します。
`boolean`	`isEmpty()` マップがキーと値のマッピングを保持しない場合に `true` を返します。
`Set<K>`	`keySet()` このマップに含まれるキーの `Set` ビューを返します。
`V`	`put(K key, V value)` 指定された値と指定されたキーをこのマップに関連付けます (任意のオペレーション)。
`void`	`putAll(Map<? extends K,? extends V> m)` 指定されたマップのすべてのマッピングをこのマップにコピーします (任意のオペレーション)。
`V`	`remove(Object key)` キーのマッピングがある場合に、そのマッピングをこのマップから削除します (任意のオペレーション)。
`int`	`size()` マップ内のキー値マッピングの数を返します。
`Collection<V>`	`values()` このマップに含まれる値の `Collection` ビューを返します。

メソッドの詳細

size

int size()

マップ内のキー値マッピングの数を返します。マップに Integer.MAX_VALUE より多くの要素がある場合は、Integer.MAX_VALUE を返します。

戻り値:: マップ内のキーと値のマッピングの数

isEmpty

boolean isEmpty()

マップがキーと値のマッピングを保持しない場合に true を返します。

戻り値:: マップがキーと値のマッピングを保持しない場合は true

containsKey

boolean containsKey(Object key)

マップが指定のキーのマッピングを保持する場合に true を返します。つまり、このマップに、(key==null ? k==null : key.equals(k)) となるキー k が含まれている場合にだけ true を返します。このようなマッピングが 1 つだけあります。

パラメータ:: key - マップにあるかどうかが判定されるキー
戻り値:: マップが指定されたキーのマッピングを保持する場合は true
例外:: ClassCastException - キーがマップに適さない型の場合 (省略可能); NullPointerException - 指定されたキーが null であり、このマップが null キーを許可しない場合 (省略可能)

containsValue

boolean containsValue(Object value)

マップが 1 つまたは複数のキーと指定された値をマッピングしている場合に true を返します。つまり、マップに、(value==null ? v==null : value.equals(v)) となる値 v へのマッピングが 1 つ以上ある場合にだけ true を返します。Map インタフェースのほとんどの実装で、このオペレーションにかかる時間はマップのサイズに正比例します。

パラメータ:: value - マップにあるかどうかを判定される値
戻り値:: マップが 1 つまたは複数のキーと指定された値をマッピングしている場合は true
例外:: ClassCastException - 値がマップに適さない型の場合 (省略可能); NullPointerException - 指定された値が null であり、このマップが null 値を許可しない場合 (省略可能)

get

V get(Object key)

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

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

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

パラメータ:: key - 関連付けられた値が返されるキー
戻り値:: 指定されたキーがマップされている値。そのキーのマッピングがこのマップに含まれていない場合は null
例外:: ClassCastException - キーがマップに適さない型の場合 (省略可能); NullPointerException - 指定されたキーが null であり、このマップが null キーを許可しない場合 (省略可能)

put

V put(K key,
      V value)

指定された値と指定されたキーをこのマップに関連付けます (任意のオペレーション)。マップにすでにこのキーに対するマッピングがある場合、古い値は指定された値に置き換えられます。m.containsKey(k) が true を返す場合に限り、マップ m は、キー k のマッピングを含むと言えます。

パラメータ:: key - 指定された値が関連付けられるキー; value - 指定されたキーに関連付けられる値
戻り値:: key に以前に関連付けられていた値。key のマッピングが存在しなかった場合は null。(null の戻り値は、実装が null 値をサポートしている場合、key と null を以前関連付けていたマップを示す場合もある)
例外:: UnsupportedOperationException - put オペレーションがこのマップでサポートされない場合; ClassCastException - 指定されたキーまたは値のクラスが原因で、このマップにそれらを格納できない場合; NullPointerException - 指定されたキーまたは値が null であり、このマップが null のキーまたは値を許可しない場合; IllegalArgumentException - 指定されたキーまたは値のあるプロパティーが原因で、このマップにそれらを格納できない場合

remove

V remove(Object key)

キーのマッピングがある場合に、そのマッピングをこのマップから削除します (任意のオペレーション)。つまり、マップに k==null ? k==null :key.equals(k)) という条件で、キー k から値 v までマッピングがマップに含まれる場合、このマッピングは削除されます。マップはこのようなマッピングを 1 つだけ含みます。

このマップが以前にこのキーを関連付けていた値を返します。キーに対するマッピングがマップになかった場合は null を返します。

このマップが null 値を許可する場合、戻り値の null は、マップがキーのマッピングを保持していなかったことを示すとはかぎりません。つまり、マップが明示的にキーを null にマップしていた可能性もあります。

一度呼び出しが返れば、マップは指定されたキーのマッピングを含みません。

パラメータ:: key - マッピングがマップから削除されるキー
戻り値:: key に以前に関連付けられていた値。key のマッピングが存在しなかった場合は null。
例外:: UnsupportedOperationException - remove オペレーションがこのマップでサポートされない場合; ClassCastException - キーがマップに適さない型の場合 (省略可能); NullPointerException - 指定されたキーが null であり、このマップが null キーを許可しない場合 (省略可能)

putAll

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

指定されたマップのすべてのマッピングをこのマップにコピーします (任意のオペレーション)。指定されたマップのキー k から値 v までの各マッピングに関して、この呼び出しの効果は、マップで put(k, v) を呼び出した場合と同じです。オペレーションの進行中に、指定されたマップが変更された場合の、このオペレーションの動作は定義されていません。

パラメータ:: m - マップに格納されるマッピング
例外:: UnsupportedOperationException - putAll オペレーションがこのマップでサポートされない場合; ClassCastException - 指定されたマップ内のキーまたは値のクラスが原因で、マップに格納できない場合; NullPointerException - 指定されたマップが null である場合、またはこのマップが null のキーまたは値を許可せず、指定されたマップに null のキーまたは値が含まれている場合; IllegalArgumentException - 指定されたマップ内のあるキーまたは値のあるプロパティーが原因で、マップに格納できない場合

clear

void clear()

マップからマッピングをすべて削除します (任意のオペレーション)。この呼び出しが戻ると、マップは空になります。

例外:: UnsupportedOperationException - clear オペレーションがこのマップでサポートされない場合

keySet

Set<K> keySet()

このマップに含まれるキーの Set ビューを返します。セットはマップと連動しているので、マップに対する変更はセットに反映され、また、セットに対する変更はマップに反映されます。セットの反復処理中にマップが変更された場合、反復処理の結果は定義されません (反復子自身の remove オペレーションを除く)。セットは要素の削除をサポートしており、対応するマッピングをマップから削除できます。削除は、Iterator.remove、Set.remove、removeAll、retainAll、および retainAll オペレーションを通して行います。Set は、add オペレーションや addAll オペレーションはサポートしていません。

戻り値:: マップに含まれているキーのセットビュー

values

Collection<V> values()

このマップに含まれる値の Collection ビューを返します。コレクションはマップと連動しているので、マップに対する変更はコレクションに反映され、またコレクションに対する変更はマップに反映されます。コレクションの反復処理中にマップが変更された場合、反復処理の結果は定義されません (反復子自身の remove オペレーションを除く)。コレクションは要素の削除をサポートしており、対応するマッピングをマップから削除できます。削除は、Iterator.remove、Collection.remove、removeAll、retainAll、および clear オペレーションを通して行います。コレクションは、add オペレーションや addAll オペレーションはサポートしていません。

戻り値:: マップ内に含まれている値のコレクションビュー

entrySet

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

このマップに含まれるマップの Set ビューを返します。セットはマップと連動しているので、マップに対する変更はセットに反映され、また、セットに対する変更はマップに反映されます。セットに対する反復の処理中にマップが変更された場合は、反復処理の結果は定義されません (反復子自身の remove オペレーション、または反復子により返されるマップエントリに対する setValue オペレーションを除く)。セットは、要素の削除をサポートしており、対応するマッピングをマップから削除できます。セットは要素の削除をサポートしており、対応するマッピングをマップから削除できます。削除は、Iterator.remove、Set.remove、removeAll、retainAll、および clear の各オペレーションを通して行います。Set は、add オペレーションや addAll オペレーションはサポートしていません。

戻り値:: マップ内に保持されているマッピングのセットビュー

equals

boolean equals(Object o)

指定されたオブジェクトがこのマップと等しいかどうかを比較します。指定されたオブジェクトがマップであり、2 つのマップが同じマッピングを表す場合に true を返します。つまり、m1.entrySet().equals(m2.entrySet()) である場合、2 つのマップ m1 と m2 は同じマッピングを表します。これにより、Map インタフェースの実装が異なる場合でも、equals メソッドが正しく動作することが保証されます。

オーバーライド:: クラス Object 内の equals

パラメータ:: o - このマップと等しいかどうかを比較するオブジェクト
戻り値:: 指定されたオブジェクトがマップと等しい場合は true
関連項目:: Object.hashCode(), Hashtable

hashCode

int hashCode()

マップのハッシュコード値を返します。マップのハッシュコードは、マップの entrySet() ビューにある各エントリのハッシュコードの合計です。これにより、Object.hashCode() の一般規約で要求されるとおりに、任意の 2 つのセット m1 と m2 について、m1.equals(m2) の場合 m1.hashCode()==m2.hashCode() になります。