java.util
インタフェース Map

既知のサブインタフェースの一覧:

SortedMap

既知の実装クラスの一覧:

AbstractMap, Attributes, HashMap, Hashtable, IdentityHashMap, LinkedHashMap, Properties, Provider, TreeMap, WeakHashMap

public interface Map

キーを値にマッピングするオブジェクトです。マップには、同一のキーを複数登録することはできません。各キーは 1 つの値にしかマッピングできません。

このインタフェースは、インタフェースというよりむしろ完全に抽象クラスであった Dictionary クラスに代わるものです。

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

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

汎用マップの実装クラスはすべて、次の 2 つの標準的なコンストラクタを提供するようにしてください。2 つの標準的なコンストラクタとは、void (引数なし) コンストラクタと、Map 型の引数を 1 つとるコンストラクタです。前者は空のマップを作成し、後者は同じキーと値のマッピングを引数として持つ新しいマップを作成します。インタフェースはコンストラクタを持つことができないため、これは強制的なものではありませんが、SDK の汎用マップの実装はすべてこれに従っています。

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

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

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

導入されたバージョン:

1.2

関連項目:

HashMap, TreeMap, Hashtable, SortedMap, Collection, Set

入れ子のクラスの概要

static interface

Map.Entry マップのエントリ (キーと値のペア) です。

メソッドの概要

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

メソッドの詳細

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

Object get(Object key)

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

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

パラメータ:

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

戻り値:

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

例外:

ClassCastException - キーがこのマップに適さない型の場合 (省略可能)

NullPointerException - キーが null のときに、このマップが null キーを許可しない場合 (省略可能)

関連項目:

containsKey(Object)

put

Object put(Object key,
           Object value)

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

パラメータ:

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

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

戻り値:

指定されたキーと関連付けられていた以前の値。キーのマッピングがなかった場合は null。null の戻り値は、実装が null 値をサポートしている場合、指定されたキーに対して null が以前関連付けられていたことを示すこともある

例外:

UnsupportedOperationException - put オペレーションがマップによってサポートされていない場合

ClassCastException - 指定されたキーまたは値のクラスが原因で、マップに格納できない場合

IllegalArgumentException - このキーまたは値の特性が原因で、このマップに格納できない場合

NullPointerException - マップが null キーや null 値を許可しないときに、指定されたキーまたは値が null の場合

remove

Object remove(Object key)

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

マップが、以前にキーをマップしている値。このキーに対するマッピングがマップにない場合は null。null の戻り値は、実装が null 値をサポートしている場合、指定されたキーと null を以前関連付けていたマップを示す場合もあります。一度呼び出しが返れば、マップは指定されたキーのマッピングを含みません。

パラメータ:

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

戻り値:

指定されたキーと関連付けられていた以前の値。キーのマッピングがなかった場合は null

例外:

ClassCastException - キーがこのマップに適さない型の場合 (省略可能)

NullPointerException - キーが null のときに、このマップが null キーを許可しない場合 (省略可能)

UnsupportedOperationException - このマップが remove メソッドをサポートしていない場合

putAll

void putAll(Map t)

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

パラメータ:

t - マップに格納されるマッピング

例外:

UnsupportedOperationException - このマップが putAll メソッドをサポートしていない場合

ClassCastException - 指定されたマップ内のキーまたは値のクラスが原因で、マップに格納できない場合

IllegalArgumentException - 指定されたマップ内のキーまたは値の特性が原因で、このマップに格納できない場合

NullPointerException - 指定されたマップが null である場合、またはこのマップが null のキーまたは値を許可せず、指定されたマップに null のキーまたは値が含まれている場合

clear

void clear()

マップからマッピングをすべて削除します (任意のオペレーション)。

例外:

UnsupportedOperationException - clear がマップによってサポートされていない場合

keySet

Set keySet()

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

戻り値:

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

values

Collection values()

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

戻り値:

マップ内に保持されている値のコレクションビュー

entrySet

Set entrySet()

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

戻り値:

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

equals

boolean equals(Object o)

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

オーバーライド:

クラス Object 内の equals

パラメータ:

o - マップと等しいかどうかを比較するオブジェクト

戻り値:

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

関連項目:

Object.hashCode(), Hashtable

hashCode

int hashCode()

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

オーバーライド:

クラス Object 内の hashCode

戻り値:

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

関連項目:

Map.Entry.hashCode(), Object.hashCode(), Object.equals(Object), equals(Object)