java.util
インタフェース Map

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

SortedMap

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

AbstractMap, HashMap, Hashtable, RenderingHints, WeakHashMap, Attributes

public interface Map

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

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

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

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

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

導入されたバージョン:

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

public int size()

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

戻り値:

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

isEmpty

public boolean isEmpty()

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

戻り値:

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

containsKey

public boolean containsKey(Object key)

マップが指定のキーのマッピングを保持する場合に true を返します。

パラメータ:

key - マップにあるかどうかが判定されるキー

戻り値:

マップが指定のキーのマッピングを保持する場合は true

例外:

ClassCastException - キーがマップに適さない型の場合

NullPointerException - キーが null のときに、マップが null キーを許可しない場合

containsValue

public boolean containsValue(Object value)

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

パラメータ:

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

戻り値:

マップが 1 つまたは複数のキーと指定された値をマッピングしている場合は true

get

public Object get(Object key)

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

パラメータ:

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

戻り値:

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

例外:

ClassCastException - キーがマップに適さない型の場合

NullPointerException - キーが null のときに、マップが null キーを許可しない場合

関連項目:

containsKey(Object)

put

public Object put(Object key,
                  Object value)

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

パラメータ:

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

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

戻り値:

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

例外:

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

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

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

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

remove

public Object remove(Object key)

このキーにマッピングがある場合に、そのマッピングをマップから削除します (任意のオペレーション)。

パラメータ:

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

戻り値:

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

例外:

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

putAll

public void putAll(Map t)

指定されたマップのすべてのマッピングをこのマップにコピーします (任意のオペレーション)。指定されたマップに現在あるすべてのキーに対してこのマップが持っていたすべてのマッピングは、コピーされるマッピングにより置き換えられます。

パラメータ:

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

例外:

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

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

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

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

clear

public void clear()

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

例外:

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

keySet

public Set keySet()

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

戻り値:

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

values

public Collection values()

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

戻り値:

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

entrySet

public Set entrySet()

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

戻り値:

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

equals

public boolean equals(Object o)

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

オーバーライド:

クラス Object 内の equals

パラメータ:

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

戻り値:

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

hashCode

public 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)