モジュール java.base

パッケージ java.util.concurrent

インタフェースConcurrentMap<K,V>

型パラメータ:

K - このマップで保持されるキーの型

V - マップされる値の型

すべてのスーパー・インタフェース:

Map<K,V>

既知のすべてのサブインタフェース:

ConcurrentNavigableMap<K,V>

既知のすべての実装クラス:

ConcurrentHashMap, ConcurrentSkipListMap

public interface ConcurrentMap<K,V>
extends Map<K,V>

スレッドの安全性と原子性の保証を提供するMapです。

指定された保証を維持するために、Mapから継承したputIfAbsent(K, V)を含むメソッドのデフォルトの実装は、このインタフェースの実装でオーバーライドする必要があります。 同様に、メソッドMap.keySet()、Map.values()、およびMap.entrySet()によって返されるコレクションの実装は、必要に応じてアトミック性の保証を保持するために、removeIfなどのメソッドをオーバーライドする必要があります。

メモリー整合性効果: ほかの並行処理コレクションと同様、オブジェクトをキーまたは値としてConcurrentMapに配置する前のスレッド内のアクションは、別のスレッド内のそのオブジェクトへのアクセスまたはConcurrentMapからの削除に続くアクションの前に発生します。

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

導入されたバージョン:

1.5

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

インタフェース java.util.Mapで宣言されたネストされたクラス/インタフェース

Map.Entry<K,V>

メソッドのサマリー

修飾子と型	メソッド	説明
default V	compute(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)	指定されたキーと現在マップされている値に対するマッピングの計算を試みます(現在のマッピングが存在しない場合はnull)。
default V	computeIfAbsent(K key, Function<? super K,? extends V> mappingFunction)	指定されたキーがまだ値に関連付けられていない(またはnullにマップされている)場合、指定されたマッピング関数を使用してその値の計算を試行し、nullでない場合はそれをこのマップに入力します。
default V	computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)	指定されたキーの値が存在していてnull以外の場合、キーと現在マップされている値から新しいマッピングの計算を試みます。
default void	forEach(BiConsumer<? super K,? super V> action)	このマップのすべてのエントリの処理が完了するかアクションから例外がスローされるまで、各エントリに対して指定されたアクションを実行します。
default V	getOrDefault(Object key, V defaultValue)	指定されたキーがマップされている値を返します。このマップにそのキーのマッピングが含まれていない場合はdefaultValueを返します。
default V	merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)	指定されたキーがまだ値と関連付けられていないかnullと関連付けられている場合、指定されたnull以外の値に関連付けます。
V	putIfAbsent(K key, V value)	指定されたキーがまだ値と関連付けられていない場合は、指定された値に関連付けます。
boolean	remove(Object key, Object value)	指定された値にキーが現在マッピングされている場合にのみ、そのキーのエントリを削除します。
V	replace(K key, V value)	キーが値に現在マッピングされている場合にのみ、そのキーのエントリを置換します。
boolean	replace(K key, V oldValue, V newValue)	指定された値にキーが現在マッピングされている場合にのみ、そのキーのエントリを置換します。
default void	replaceAll(BiFunction<? super K,? super V,? extends V> function)	すべてのエントリが処理されるか、または関数が例外をスローするまで、各エントリの値を、そのエントリで指定された関数を呼び出した結果で置換します。

インタフェース java.util.Mapで宣言されたメソッド

clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

メソッドの詳細

getOrDefault

default V getOrDefault(Object key,
                       V defaultValue)

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

定義:

インタフェースMap<K,V>内のgetOrDefault

実装上のノート:

この実装では、ConcurrentMapにnull値が含まれることはなく、get()からnullが返された場合はキーが存在しないことを示すとみなされます。 null値をサポートする実装は、このデフォルト実装をオーバーライドする必要があります。

パラメータ:

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

defaultValue - キーのデフォルト・マッピング

戻り値:

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

例外:

ClassCastException - このキーがこのマップに適さない型の場合(オプション)

NullPointerException - 指定されたキーがnullであり、このマップがnullキーを許可しない場合(オプション)

導入されたバージョン:

1.8

forEach

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

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

定義:

インタフェースMap<K,V>内のforEach

実装要件:

このmapでは、デフォルト実装は次と同等です。

 
 for (Map.Entry<K,V> entry : map.entrySet()) {
   action.accept(entry.getKey(), entry.getValue());
 }

実装上のノート:

デフォルト実装では、getKey()またはgetValue()によってスローされたIllegalStateExceptionはエントリが削除され、処理できないことを示すとみなされます。 オペレーションは後続のエントリで続行されます。

パラメータ:

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

例外:

NullPointerException - 指定されたアクションがnullである場合

導入されたバージョン:

1.8

putIfAbsent

V putIfAbsent(K key,
              V value)

指定されたキーがまだ値と関連付けられていない場合は、指定された値に関連付けます。 これは、このmapの場合と同じです:

 
 if (!map.containsKey(key))
   return map.put(key, value);
 else
   return map.get(key);

ただし、アクションが原子的に実行される点が異なります。

定義:

インタフェースMap<K,V>内のputIfAbsent

実装上のノート:

この実装は、Mapで指定された不適切なデフォルトを意図的に再抽象化します。

パラメータ:

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

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

戻り値:

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

例外:

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

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

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

IllegalArgumentException - 指定されたキーまたは値のあるプロパティが原因で、このマップにそれらを格納できない場合

remove

boolean remove(Object key,
               Object value)

指定された値にキーが現在マッピングされている場合にのみ、そのキーのエントリを削除します。 これは、このmapの場合と同じです:

 
 if (map.containsKey(key)
     && Objects.equals(map.get(key), value)) {
   map.remove(key);
   return true;
 } else {
   return false;
 }

ただし、アクションが原子的に実行される点が異なります。

定義:

インタフェースMap<K,V>内のremove

実装上のノート:

この実装は、Mapで指定された不適切なデフォルトを意図的に再抽象化します。

パラメータ:

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

value - 指定されたキーに関連付けられていると予想される値

戻り値:

値が削除された場合はtrue

例外:

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

ClassCastException - キーまたは値がこのマップに適さない型の場合(オプション)

NullPointerException - 指定されたキーまたは値がnullであり、かつこのマップがnullのキーまたは値を許可しない場合(オプション)

replace

boolean replace(K key,
                V oldValue,
                V newValue)

指定された値にキーが現在マッピングされている場合にのみ、そのキーのエントリを置換します。 これは、このmapの場合と同じです:

 
 if (map.containsKey(key)
     && Objects.equals(map.get(key), oldValue)) {
   map.put(key, newValue);
   return true;
 } else {
   return false;
 }

ただし、アクションが原子的に実行される点が異なります。

定義:

インタフェースMap<K,V>内のreplace

実装上のノート:

この実装は、Mapで指定された不適切なデフォルトを意図的に再抽象化します。

パラメータ:

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

oldValue - 指定されたキーに関連付けられていると予想される値

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

戻り値:

値が置換された場合はtrue

例外:

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

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

NullPointerException - 指定されたキーまたは値がnullであり、このマップがnullのキーまたは値を許可しない場合

IllegalArgumentException - 指定されたキーまたは値のあるプロパティが原因で、それをこのマップに格納できない場合

replace

V replace(K key,
          V value)

キーが値に現在マッピングされている場合にのみ、そのキーのエントリを置換します。 これは、このmapの場合と同じです:

 
 if (map.containsKey(key))
   return map.put(key, value);
 else
   return null;

ただし、アクションが原子的に実行される点が異なります。

定義:

インタフェースMap<K,V>内のreplace

実装上のノート:

この実装は、Mapで指定された不適切なデフォルトを意図的に再抽象化します。

パラメータ:

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

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

戻り値:

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

例外:

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

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

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

IllegalArgumentException - 指定されたキーまたは値のあるプロパティが原因で、このマップにそれらを格納できない場合

replaceAll

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

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

定義:

インタフェースMap<K,V>内のreplaceAll

実装要件:

このmapでは、デフォルト実装は次と同等です。

 
 for (Map.Entry<K,V> entry : map.entrySet()) {
   K k;
   V v;
   do {
     k = entry.getKey();
     v = entry.getValue();
   } while (!map.replace(k, v, function.apply(k, v)));
 }

デフォルト実装は、複数のスレッドが更新を試行するときに、これらのステップを再試行する可能性があります。これには、特定のキーに関してこの関数が繰り返し呼び出される可能性も含まれます。

この実装では、ConcurrentMapにnull値が含まれることはなく、get()からnullが返された場合はキーが存在しないことを示すとみなされます。 null値をサポートする実装は、このデフォルト実装をオーバーライドする必要があります。

パラメータ:

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

例外:

UnsupportedOperationException - setオペレーションがこのマップのエントリ・セット・イテレータでサポートされない場合。

NullPointerException - 関数または置換値がnullで、このマップがnullキーまたは値を許可しない場合(オプション)

ClassCastException - 置換値の型がこのマップに不適切な場合(オプション)

IllegalArgumentException - 置換値のなんらかのプロパティが、置換値がこのマップに格納されることを妨げる場合(オプション)

導入されたバージョン:

1.8

computeIfAbsent

default V computeIfAbsent(K key,
                          Function<? super K,? extends V> mappingFunction)

指定されたキーがまだ値に関連付けられていない(またはnullにマップされている)場合、指定されたマッピング関数を使用してその値の計算を試行し、nullでない場合はそれをこのマップに入力します。

マッピング関数がnullを返した場合、マッピングは記録されません。 マッピング関数自体が(unchecked)例外をスローすると、例外は再スローされ、マッピングは記録されません。 もっとも一般的な用途は、次のように初期のマップされた値またはメモ化された結果として機能する新しいオブジェクトを構築することです。

 
 map.computeIfAbsent(key, k -> new Value(f(k)));
 

または、1つのキーで複数の値をサポートする複数値マップMap<K,Collection<V>>を実装することです。

 
 map.computeIfAbsent(key, k -> new HashSet<V>()).add(v);
 

マッピング関数は、計算中にこのマップを変更すべきではありません。

定義:

インタフェースMap<K,V>内のcomputeIfAbsent

実装要件:

デフォルトの実装は、このmapの次のステップと同じです:

 
 V oldValue, newValue;
 return ((oldValue = map.get(key)) == null
         && (newValue = mappingFunction.apply(key)) != null
         && (oldValue = map.putIfAbsent(key, newValue)) == null)
   ? newValue
   : oldValue;

この実装では、ConcurrentMapにnull値が含まれることはなく、get()からnullが返された場合はキーが存在しないことを示すとみなされます。 null値をサポートする実装は、このデフォルト実装をオーバーライドする必要があります。

パラメータ:

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

mappingFunction - 値をコンピュートするマッピング関数

戻り値:

指定されたキーに関連付けられている現在の(既存の、または計算された)値。計算された値がnullである場合はnull

例外:

UnsupportedOperationException - put操作がこのマップでサポートされない場合(オプション)

ClassCastException - 指定されたキーまたは値のクラスが、それらがこのマップに格納されるのを妨げる場合(オプション)

NullPointerException - 指定されたキーがnullであり、このマップがnullキーをサポートしない場合、またはmappingFunctionがnullである場合

IllegalArgumentException - 指定されたキーまたは値のなんらかのプロパティが、それらがこのマップに格納されるのを妨げる場合(オプション)

導入されたバージョン:

1.8

computeIfPresent

default V computeIfPresent(K key,
                           BiFunction<? super K,? super V,? extends V> remappingFunction)

指定されたキーの値が存在していてnull以外の場合、キーと現在マップされている値から新しいマッピングの計算を試みます。

リマッピング関数がnullを返した場合、マッピングは削除されます。 再マップ関数自体が(unchecked)例外をスローすると、例外が再スローされ、現在のマッピングは変更されません。

再マップ関数は、計算中にこのマップを変更すべきではありません。

定義:

インタフェースMap<K,V>内のcomputeIfPresent

実装要件:

デフォルトの実装は、このmapに対して以下のステップを実行するのと同じです:

 
 for (V oldValue; (oldValue = map.get(key)) != null; ) {
   V newValue = remappingFunction.apply(key, oldValue);
   if ((newValue == null)
       ? map.remove(key, oldValue)
       : map.replace(key, oldValue, newValue))
     return newValue;
 }
 return null;

複数のスレッドが更新を試みると、マップ操作と再マッピング関数は複数回呼び出されることがあります。

この実装では、ConcurrentMapにnull値が含まれることはなく、get()からnullが返された場合はキーが存在しないことを示すとみなされます。 null値をサポートする実装は、このデフォルト実装をオーバーライドする必要があります。

パラメータ:

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

remappingFunction - 値をコンピュートするための再マップ関数

戻り値:

指定されたキーに関連付けられる新しい値。存在しない場合はnull

例外:

UnsupportedOperationException - put操作がこのマップでサポートされない場合(オプション)

ClassCastException - 指定されたキーまたは値のクラスが、それらがこのマップに格納されるのを妨げる場合(オプション)

NullPointerException - 指定されたキーがnullであり、このマップがnullキーをサポートしない場合、またはremappingFunctionがnullである場合

IllegalArgumentException - 指定されたキーまたは値のなんらかのプロパティが、それらがこのマップに格納されるのを妨げる場合(オプション)

導入されたバージョン:

1.8

compute

default V compute(K key,
                  BiFunction<? super K,? super V,? extends V> remappingFunction)

指定されたキーと現在マップされている値に対するマッピングの計算を試みます(現在のマッピングが存在しない場合はnull)。 たとえば、次のように、値のマッピングにString msgを作成または追加します。

 
 map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))

(このような目的で使用するmerge()メソッドは、多くの場合、より単純です。)

再マッピング関数がnullを返した場合、マッピングは削除されます。(最初に欠席した場合は不在のままです)。 再マップ関数自体が(unchecked)例外をスローすると、例外が再スローされ、現在のマッピングは変更されません。

再マップ関数は、計算中にこのマップを変更すべきではありません。

定義:

インタフェースMap<K,V>内のcompute

実装要件:

デフォルトの実装は、このmapに対して以下のステップを実行するのと同じです:

 
 for (;;) {
   V oldValue = map.get(key);
   V newValue = remappingFunction.apply(key, oldValue);
   if (newValue != null) {
     if ((oldValue != null)
       ? map.replace(key, oldValue, newValue)
       : map.putIfAbsent(key, newValue) == null)
       return newValue;
   } else if (oldValue == null || map.remove(key, oldValue)) {
     return null;
   }
 }

複数のスレッドが更新を試みると、マップ操作と再マッピング関数は複数回呼び出されることがあります。

この実装では、ConcurrentMapにnull値が含まれることはなく、get()からnullが返された場合はキーが存在しないことを示すとみなされます。 null値をサポートする実装は、このデフォルト実装をオーバーライドする必要があります。

パラメータ:

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

remappingFunction - 値をコンピュートするための再マップ関数

戻り値:

指定されたキーに関連付けられる新しい値。存在しない場合はnull

例外:

UnsupportedOperationException - put操作がこのマップでサポートされない場合(オプション)

ClassCastException - 指定されたキーまたは値のクラスが、それらがこのマップに格納されるのを妨げる場合(オプション)

NullPointerException - 指定されたキーがnullであり、このマップがnullキーをサポートしない場合、またはremappingFunctionがnullである場合

IllegalArgumentException - 指定されたキーまたは値のなんらかのプロパティが、それらがこのマップに格納されるのを妨げる場合(オプション)

導入されたバージョン:

1.8

merge

default V merge(K key,
                V value,
                BiFunction<? super V,? super V,? extends V> remappingFunction)

指定されたキーがまだ値と関連付けられていないかnullと関連付けられている場合、指定されたnull以外の値に関連付けます。 それ以外の場合は、指定された再マッピング関数の結果で関連する値を置換し、結果がnullの場合は削除します。 このメソッドは、1つのキーに対する複数のマップされた値を結合するときに使用できます。 たとえば、次のように、値のマッピングにString msgを作成または追加します。

 
 map.merge(key, msg, String::concat)
 

リマッピング関数がnullを返した場合、マッピングは削除されます。 再マップ関数自体が(unchecked)例外をスローすると、例外が再スローされ、現在のマッピングは変更されません。

再マップ関数は、計算中にこのマップを変更すべきではありません。

定義:

インタフェースMap<K,V>内のmerge

実装要件:

デフォルトの実装は、このmapに対して以下のステップを実行するのと同じです:

 
 for (;;) {
   V oldValue = map.get(key);
   if (oldValue != null) {
     V newValue = remappingFunction.apply(oldValue, value);
     if (newValue != null) {
       if (map.replace(key, oldValue, newValue))
         return newValue;
     } else if (map.remove(key, oldValue)) {
       return null;
     }
   } else if (map.putIfAbsent(key, value) == null) {
     return value;
   }
 }

複数のスレッドが更新を試みると、マップ操作と再マッピング関数は複数回呼び出されることがあります。

この実装では、ConcurrentMapにnull値が含まれることはなく、get()からnullが返された場合はキーが存在しないことを示すとみなされます。 null値をサポートする実装は、このデフォルト実装をオーバーライドする必要があります。

パラメータ:

key - 結果値が関連付けられるキー

value - キーに関連付けられた既存の値にマージされるnull以外の値。既存の値がない場合、またはキーにnull値が関連付けられている場合は、キーに関連付けられるnull以外の値

remappingFunction - 存在する場合に値を再計算するための再マッピング関数

戻り値:

指定されたキーに関連付けられた新しい値。キーに値が関連付けられなかった場合はnull

例外:

UnsupportedOperationException - put操作がこのマップでサポートされない場合(オプション)

ClassCastException - 指定されたキーまたは値のクラスが、それらがこのマップに格納されるのを妨げる場合(オプション)

NullPointerException - 指定されたキーがnullであり、このマップがnullキーをサポートしない場合、あるいは値またはremappingFunctionがnullである場合

IllegalArgumentException - 指定されたキーまたは値のなんらかのプロパティが、それらがこのマップに格納されるのを妨げる場合(オプション)

導入されたバージョン:

1.8