public class MultivaluedHashMap<K,V>
extends AbstractMultivaluedMap<K,V>
implements SerializableSE

MultivaluedMap インターフェースのハッシュテーブルベースの実装。この実装は、すべてのオプションのマップ操作を提供します。このクラスは、マップの順序については保証しません。特に、順序が長期にわたって一定であることを保証するものではありません。実装は null キーを許可します。デフォルトでは、実装は null 値も許可しますが、無視します。この動作は、保護された addNull(...) および addFirstNull(...) メソッドをオーバーライドすることによってカスタマイズできます。

この実装は、ハッシュ関数がバケット間で要素を適切に分散すると仮定して、基本操作（get および put）に一定時間のパフォーマンスを提供します。コレクションビューの反復には、マップインスタンスの「キャパシティ」（バケットの数）とそのサイズ（キーと値のマッピングの数）を足した時間に比例する時間が必要です。反復のパフォーマンスが重要な場合は、初期容量を高く設定しすぎない（または負荷係数を低くしすぎない）ことが非常に重要です。

MultivaluedHashMap のインスタンスには、そのパフォーマンスに影響を与える 2 つのパラメーターがあります。 初期容量と負荷係数です。 容量はハッシュテーブル内のバケットの数であり、初期容量はハッシュテーブルが作成されたときの容量です。 負荷係数は、ハッシュテーブルの容量が自動的に増加する前に、ハッシュテーブルがどの程度いっぱいになるかを示す尺度です。ハッシュテーブルのエントリ数が負荷係数と現在の容量の積を超えると、ハッシュテーブルが再ハッシュされる（つまり、内部データ構造が再構築される）ため、ハッシュテーブルのバケット数は約 2 倍になります。

一般的なルールとして、デフォルトの負荷係数（.75）は、時間とスペースのコスト間の適切なトレードオフを提供します。値を大きくすると、スペースのオーバーヘッドは減少しますが、ルックアップコストは増加します（get および put を含む HashMap クラスのほとんどの操作で反映されます）。マップ内の予想されるエントリ数とその負荷係数は、その初期容量を設定するときに考慮に入れて、再ハッシュ操作の数を最小限に抑える必要があります。初期容量がエントリの最大数を負荷係数で割った値より大きい場合、再ハッシュ操作は発生しません。

多くのマッピングを MultivaluedHashMap インスタンスに格納する場合、十分に大きな容量でマッピングを作成すると、テーブルを拡張するために必要に応じて自動再ハッシュを実行するよりも効率的にマッピングを格納できます。

この実装は同期が保証されていないことに注意してください。複数のスレッドが同時にハッシュマップにアクセスし、少なくとも 1 つのスレッドがマップを構造的に変更する場合、外部で同期する必要があります。（構造的変更とは、1 つ以上のマッピングを追加または削除する操作です。インスタンスにすでに含まれているキーに関連付けられた値を変更するだけでは、構造的変更は行われません）これは通常、マップを自然にカプセル化するオブジェクトで同期することによって行われます。

このクラスのすべての「コレクションビューメソッド」によって返されるイテレータはフェイルファストです。イテレータが作成された後、マップが構造的にいつでも変更された場合、イテレータ自身の remove メソッド以外の方法で、イテレータは ConcurrentModificationExceptionSE をスローします。同時変更に直面した場合、イテレーターは、将来の未確定の時点で恣意的な非決定論的な動作のリスクを冒すのではなく、迅速かつ完全に失敗します。

イテレータのフェイルファスト動作は、一般的に言えば、非同期の同時変更が存在する場合にハードな保証を行うことが不可能であるため、保証できないことに注意してください。フェイルファストイテレータは、ベストエフォートベースで ConcurrentModificationException をスローします。この例外に依存して正確であるプログラムを作成するのは誤りです。反復子のフェイルファスト動作は、バグを検出するためだけに使用する必要があります。