JavaTM 2
Platform
Std. Ed. v1.4.0

java.util
インタフェース Map

既知のサブインタフェースの一覧:
SortedMap
既知の実装クラスの一覧:
AbstractMap, Attributes, HashMap, Hashtable, IdentityHashMap, RenderingHints, TreeMap, WeakHashMap

public interface Map

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

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

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

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

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

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

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

導入されたバージョン:
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==null ? k==null : key.equals(k)) となるキーk のマッピングが含まれている場合にだけ true を返します。マップはこのようなマッピングを 1 つだけ含むことができます。

パラメータ:
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
例外:
ClassCastException - 値がマップに適さない型の場合 (任意のオプション)
NullPointerException - 値が null のときに、マップが null 値を許可しない場合 (任意のオプション)

get

public 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

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

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

remove

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

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

パラメータ:
key - マッピングがマップから削除されるキー
戻り値:
指定されたキーと関連付けられていた以前の値。キーのマッピングがなかった場合は null
例外:
ClassCastException - キーがマップに適さない型の場合 (任意のオプション)
NullPointerException - キーが null のときに、マップが null キーを許可しない場合 (任意のオプション)
UnsupportedOperationException - マップが remove メソッドをサポートしていない場合

putAll

public void putAll(Map t)
指定されたマップのすべてのマッピングをこのマップにコピーします (任意のオペレーション)。指定されたマップのキー k から値 v までの各マッピングに関して、この呼び出しの効果は、マップで put(k, v) を呼び出した場合と同じです。指定されたマップがこのオペレーションの処理中に変更された場合、そのオペレーションの動作は指定外となります。

パラメータ:
t - マップに格納されるマッピング
例外:
UnsupportedOperationException - マップが putAll メソッドをサポートしていない場合
ClassCastException - 指定されたマップ内のキーまたは値のクラスが原因で、マップに格納できない場合
IllegalArgumentException - 指定されたマップ内のキーまたは値の特性が原因で、マップに格納できない場合
NullPointerException - 指定されたマップが null であるか、またはこのマップが null キー や null 値を許可せず、指定されたマップに null キーや null 値が含まれない場合

clear

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

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

keySet

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

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

values

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

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

entrySet

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

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

equals

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

オーバーライド:
クラス Object 内の equals
パラメータ:
o - マップと等しいかどうかを比較するオブジェクト
戻り値:
指定されたオブジェクトがマップと等しい場合は true

hashCode

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

オーバーライド:
クラス Object 内の hashCode
戻り値:
マップのハッシュコード値
関連項目:
Map.Entry.hashCode(), Object.hashCode(), Object.equals(Object), equals(Object)

JavaTM 2
Platform
Std. Ed. v1.4.0

バグの報告と機能のリクエスト
これ以外の API リファレンスおよび開発者用ドキュメントについては、 Java 2 SDK SE 開発者用ドキュメントを参照してください。 開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、 およびコード実例が含まれています。

Java、Java 2D、および JDBC は米国ならびにその他の国における米国 Sun Microsystems, Inc. の商標もしくは登録商標です。
Copyright 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.