HashMapに独自クラスのキーを登録し、同じ値を持つ別のインスタンスで取得したい。この設計で必要になるのが、equalsとhashCodeの整合性です。equalsで同じ値だと判定できても、それだけではハッシュを使うコレクションのキーとして正しく扱えるとは限りません。
この記事ではJava SE 21を基準に、二つのメソッドの役割、Objectが定める契約、HashMapでの検索の考え方を整理します。通常クラスの実装例から、可変キー、record、ConcurrentHashMapの注意点まで、値が同じ別インスタンスをキーにしても取得できる設計を考えます。
JavaのequalsとhashCodeの違い
equalsは等価性、hashCodeはハッシュ値を返す
equals(Object)は、相手のオブジェクトを自分と等しいとみなすかをbooleanで返します。どの値が一致すれば等しいのかは、そのクラスが表す意味に合わせて決めます。たとえば商品キーなら、商品コードが同じときに等しい、と定義できます。
hashCode()は、オブジェクトのハッシュ値をintで返します。HashMapやHashSetなどが、検索対象の候補を絞るために利用します。オブジェクトごとに必ず異なる番号を付けるメソッドでも、等しさそのものを判定するメソッドでもありません。
| メソッド | 戻り値 | 役割 |
|---|---|---|
| equals(Object) | boolean | 相手と等しいかを判定する |
| hashCode() | int | ハッシュを使う検索などに利用する値を返す |
参照型の==とObject標準のequalsを区別する
参照型の==は、同じオブジェクトを参照しているかを比較します。両方がnullの場合もtrueです。フィールドに同じ値が入っているかを自動で比較するものではありません。
Objectから継承したままのequalsも、同じオブジェクトかどうかを判定します。一方、Stringなど、equalsをオーバーライドしたクラスでは、そのクラスが定める等価性に従います。Object.equalsのAPI契約は、Object標準の実装と、オーバーライドする実装が守る条件を分けて示しています。
public final class EqualityExample {
public static void main(String[] args) {
String first = new String("mikan");
String second = new String("mikan");
boolean sameInstance = first == second;
boolean sameValue = first.equals(second);
}
}この例では二つのStringを別々に生成しているため、sameInstanceはfalseです。Stringのequalsは文字列の内容を比較するため、sameValueはtrueになります。独自クラスでも値に基づく比較が必要なら、その等価性をequalsに実装します。
Objectが定めるequalsとhashCodeの契約
equalsの反射性・対称性・推移性・一貫性とnull比較
equalsは、単に都合のよい比較を書けばよいメソッドではありません。Objectのequals契約に従い、次の条件を満たす必要があります。表のx、y、zはnullではない参照です。
| 条件 | 意味 |
|---|---|
| 反射性 | x.equals(x)はtrue |
| 対称性 | x.equals(y)とy.equals(x)の結果が一致する |
| 推移性 | x.equals(y)とy.equals(z)がtrueなら、x.equals(z)もtrue |
| 一貫性 | 比較に使う情報が変わらなければ、繰り返し比較しても結果は変わらない |
| nullとの比較 | x.equals(null)はfalse |
nullとの比較でfalseを返すのは、nullではないオブジェクトからequalsを呼ぶ場合です。nullの参照に対してequalsを呼べばNullPointerExceptionになります。また、一貫性は「生成後に何を変更しても比較結果が一定」という意味ではありません。条件になるのは、等価性の判定に使う情報が変更されていないことです。
equalsで等しいならhashCodeも同じにする
二つのオブジェクトがequalsで等しいなら、そのhashCodeも同じ値でなければなりません。これが、equalsをオーバーライドするときにhashCodeも対で考える理由です。
a.equals(b)がtrueなら、a.hashCode() == b.hashCode()もtrueにします。equalsで区別しない情報によってハッシュ値が変わる実装は、この契約を壊します。
たとえば、商品コードだけで等価性を決めるなら、表示名が違うだけでハッシュ値が変わる設計にはできません。通常は、equalsで比較するフィールドに基づいてhashCodeも計算すると、対応関係を確認しやすくなります。
Object.hashCodeのAPI契約では、equalsの比較に使う情報が変わらない限り、同じアプリケーション実行中の繰り返し呼び出しで同じ値を返すことも定めています。別の実行でも同じ値になることまでは要求していないため、ハッシュ値を永続的な識別子として使わないようにします。
同じハッシュ値でも等しいとは限らない
逆方向の条件はありません。hashCodeが同じでも、equalsがfalseになることは許されます。このように異なるキーが同じハッシュ値を持つことを、ハッシュ衝突と呼びます。
したがって、二つのhashCodeが一致しただけで「同じキー」と判断することはできません。ハッシュ値は候補を絞るための情報であり、キーの等価性とは分けて扱います。異なるオブジェクトへ必ず異なる値を返す必要がないことも、ObjectのhashCode契約に明記されています。
HashMapがキーを検索するときの考え方
ハッシュ値で候補を絞り、キーの同一性・等価性で照合する
HashMapのキー検索は、概念的には次の流れで捉えられます。ここではnullではないキーを考えます。
- 検索するキーのハッシュ値を使い、探す候補を絞る。
- 候補のキーについて、同じインスタンスか、equalsで等しいかを照合する。
- 一致するキーがあれば、そのキーに対応する値を返す。
hashCodeの戻り値そのものが内部配列の添字になるわけではありません。また、getを呼ぶたびに、登録済みのすべてのキーへ順番にequalsを呼ぶと考えるのも適切ではありません。ハッシュによる絞り込みを前提とするため、等しいキーのハッシュ値をそろえる必要があります。
HashMapのAPI説明は、ハッシュ値が適切に分散することを前提に、getやputの基本操作が定数時間で行われると説明しています。同じハッシュ値へ偏る設計では、その前提を生かせません。具体的な比較回数や内部構造を、キー設計の保証として当てにしないようにします。
別インスタンスでも等しいキーなら登録済みの値を取得できる
キーに必要なのは、登録時と検索時に必ず同じインスタンスを渡すことではありません。equalsとhashCodeの契約を満たしていれば、等しい別インスタンスでも対応する値を取得できます。Stringを使うと、その関係を短く表せます。
import java.util.HashMap;
import java.util.Map;
public final class StringKeyExample {
public static void main(String[] args) {
Map<String, Integer> stock = new HashMap<>();
String storedKey = new String("mikan");
String lookupKey = new String("mikan");
stock.put(storedKey, 10);
Integer quantity = stock.get(lookupKey);
}
}storedKeyとlookupKeyは別のインスタンスですが、文字列として等しく、ハッシュ値も一致するため、quantityには10が入ります。独自クラスをキーにするときも、このような取得が成立する等価性を設計します。
ハッシュ衝突と同じキーへの値の上書きを区別する
異なるキーのハッシュ値が衝突しても、それだけで一方の値が上書きされるわけではありません。equalsで等しくないキーは、別の対応関係として保持できます。
一方、すでに存在するキーと等しいキーでputすると、そのキーに対応する値が置き換わります。これは衝突による不具合ではなく、Map.putが定める動作です。「ハッシュ値が同じ」と「等しいキーである」を分けて考えてください。
equalsだけをオーバーライドする誤りと正しい実装
equalsだけでは等しいキーのハッシュ値がそろわない
独自クラスでequalsだけを実装し、hashCodeをObjectから継承したままにすると、値に基づく等価性とハッシュ値が整合する保証がありません。次は、その問題を示す実装例です。
import java.util.HashMap;
import java.util.Map;
import java.util.Objects;
public final class EqualsOnlyExample {
static final class ProductKey {
private final String code;
ProductKey(String code) {
this.code = Objects.requireNonNull(code);
}
@Override
public boolean equals(Object other) {
if (this == other) {
return true;
}
if (!(other instanceof ProductKey that)) {
return false;
}
return code.equals(that.code);
}
// hashCodeのオーバーライドが欠けている
}
public static void main(String[] args) {
ProductKey first = new ProductKey("M001");
ProductKey second = new ProductKey("M001");
Map<ProductKey, String> names = new HashMap<>();
names.put(first, "みかん");
boolean equal = first.equals(second);
String found = names.get(second);
}
}equalはtrueですが、等しいsecondからの取得を、この実装では保証できません。Object由来のハッシュ値が、独自に定めた商品コードの等価性へ対応していないためです。
ただし、異なるインスタンスのObject由来のハッシュ値が必ず異なるわけではありません。そのため「このコードでは必ず取得に失敗する」とは判断しません。問題は、たまたま取得できる場合があるかどうかではなく、等しいオブジェクトのハッシュ値をそろえる契約を実装していないことです。
finalクラスで等価性に使うフィールドを決める
正しい実装を書く前に、何を同じキーとみなすかを決めます。ここでは「商品コードが同じなら同じキー」とし、表示名や在庫数はキーに含めません。商品コードは不変なStringとして保持し、フィールドをfinalにします。
クラス自体もfinalにすると、サブクラスが等価性の条件を追加する問題を避けられます。親クラスがコードだけで比較し、子クラスがコードと別の属性で比較すると、比較の向きによって結果が変わり、対称性を壊す設計になり得ます。継承が不要な値のキーでは、finalクラスにすると等価性の範囲を明確にできます。
equals(Object)とhashCode()を対で実装する
次は、equalsとhashCodeを対にした完結例です。ProductKeyExample.javaにまとめられる構成で、等価性に使うcodeを両方のメソッドで利用します。
import java.util.HashMap;
import java.util.Map;
import java.util.Objects;
public final class ProductKeyExample {
static final class ProductKey {
private final String code;
ProductKey(String code) {
this.code = Objects.requireNonNull(code, "code");
}
@Override
public boolean equals(Object other) {
if (this == other) {
return true;
}
if (!(other instanceof ProductKey that)) {
return false;
}
return code.equals(that.code);
}
@Override
public int hashCode() {
return code.hashCode();
}
}
public static void main(String[] args) {
ProductKey first = new ProductKey("M001");
ProductKey second = new ProductKey("M001");
Map<ProductKey, String> names = new HashMap<>();
names.put(first, "みかん");
String found = names.get(second);
String previous = names.put(second, "温州みかん");
int count = names.size();
String current = names.get(first);
}
}equalsでは、同じインスタンスならtrueを返し、nullや異なる型ならfalseを返します。その後、商品コードの一致を判定します。hashCodeも同じcodeに基づくため、等しいProductKey同士でハッシュ値が一致します。
この例のfoundとpreviousは「みかん」、countは1、currentは「温州みかん」になります。二回目のputは等しいキーへの値の置き換えであり、対応関係をもう一つ追加する操作にはなりません。
メソッドの引数はequals(Object other)にする点も重要です。equals(ProductKey other)と書くと、Objectのequalsをオーバーライドせず、別のメソッドをオーバーロードすることになります。@Overrideを付ければ、この取り違えをコンパイル時に検出できます。
契約とHashMapでの取得・上書きを確認する観点
実装を確認するときは、equalsの単発の比較だけで終わらせず、契約とMapでの利用を合わせて見ます。
| 観点 | 確認する内容 |
|---|---|
| 基本比較 | 自分自身、null、異なる型との比較が契約どおりか |
| 等価性の性質 | 対称性・推移性・一貫性を満たすか |
| ハッシュ値の整合性 | 等しい別インスタンスのhashCodeが一致するか |
| 等価性の範囲 | 比較対象フィールドが異なると、設計どおりに等しくないと判定するか |
| 取得 | 等しい別インスタンスから登録済みの値を取得できるか |
| 置き換え | 等しいキーへのputで件数が増えず、対応する値が置き換わるか |
| 衝突 | 同じハッシュ値でも、等しくないキーを区別できるか |
異なるキーのhashCodeがすべて異なることを、テストの必須条件にしてはいけません。衝突は契約上許されます。一方、すべて同じ定数を返す実装は、等しいキーのハッシュ値をそろえる条件を満たしても、検索候補を分散できません。契約を守ることと、適切に分散させることの両方を考えます。
HashMapへ格納したキーの状態を変えてはいけない理由
等価性に使う状態が変わると検索の前提が崩れる
登録時のキーと検索時のキーで、等価性やハッシュ値の前提が変わると、Mapを正しく利用できなくなります。MapのAPI契約では、キーとして格納されている間にequalsの比較へ影響する状態を変更した場合、Mapの動作は規定されていません。
たとえば、商品コードを変更できるクラスで、そのコードをequalsとhashCodeに使っている場合です。登録後にコードを変えると、現在のキーから計算されるハッシュ値が登録時と変わり、検索で想定する候補を見つけられなくなることがあります。
同じインスタンスをgetへ渡しても、格納中のキー変更が安全になるわけではありません。変更後に必ず取得できる、必ずnullになる、removeで必ず復旧できる、といった動作へ依存しないでください。
注意すべき対象は、キーのすべての状態ではなく、等価性の判定に使う状態です。ただし、どの変更が影響するかを追い続ける設計は複雑になるため、キーには不変な値を使うと管理しやすくなります。
不変なキーを選び、キーを変える場合は削除してから再登録する
基本は、Stringや、先ほどのProductKeyのように等価性に使う状態が変わらないキーを選ぶことです。参照型のフィールドをfinalにするだけでは参照先の変更を防げないため、保持する値自体の不変性も確認します。
キーを変更する必要があるなら、変更前のキーで対応関係を削除し、その後に新しいキーで再登録します。不変なキーなら、元のキーを書き換えず、新しいキーを生成して置き換えます。次は、単一スレッドで操作する例です。
import java.util.HashMap;
import java.util.Map;
public final class ReplaceKeyExample {
public static void main(String[] args) {
Map<String, String> names = new HashMap<>();
names.put("M001", "みかん");
String oldKey = "M001";
String newKey = "M002";
if (names.containsKey(newKey)) {
throw new IllegalStateException("new key already exists");
}
if (names.containsKey(oldKey)) {
String value = names.remove(oldKey);
names.put(newKey, value);
}
}
}この例は、新しいキーがすでに存在する場合に上書きしない方針です。また、HashMapはnull値を保持できるため、removeの戻り値がnullかどうかだけで元のキーの有無を判定していません。削除と登録は複数の操作なので、並行アクセスがある場合は、処理全体の整合性を別途設計します。
recordとConcurrentHashMapでもキーの契約を確認する
recordの等価性と可変componentの注意点
recordでは、全componentに基づくequalsとhashCodeが暗黙に用意されます。同じrecord型で、対応する全componentが等しければ、等しいキーとして扱えます。複数の値をまとめたキーを表す候補になります。
import java.util.HashMap;
import java.util.Map;
import java.util.Objects;
public final class RecordKeyExample {
record ProductKey(String shopCode, String productCode) {
ProductKey {
Objects.requireNonNull(shopCode, "shopCode");
Objects.requireNonNull(productCode, "productCode");
}
}
public static void main(String[] args) {
Map<ProductKey, String> names = new HashMap<>();
names.put(new ProductKey("S01", "M001"), "みかん");
String found = names.get(new ProductKey("S01", "M001"));
}
}この例は二つの不変なStringをcomponentとして持ち、両方の値が等しい別インスタンスで取得できます。一方、商品コードだけで等しいとしたいのに表示名までcomponentへ含めると、標準の等価性はその意図と合いません。recordの全componentに基づく比較が、キーの意味に合うかを確認します。
また、recordは浅い不変性を持つ型です。Listなどの可変オブジェクトをcomponentにすると、その内容の変更でequalsやhashCodeの結果が変わる場合があります。配列のcomponentも、自動的に要素単位の深い比較へ変わるわけではありません。recordであることだけを理由に、安全なキーだとは判断できません。
RecordのAPI契約では、暗黙のequalsとhashCodeの性質を説明しています。hashCodeの具体的な計算アルゴリズムは規定されていないため、Objects.hash(...)と同じ計算式になることを前提にしないでください。recordの宣言方法や参照先の不変性については、次の記事で詳しく整理しています。

ConcurrentHashMapの並行アクセス対応とキーの安定性を分ける
ConcurrentHashMapは並行アクセスに対応していますが、キーのequalsとhashCodeの不整合を補正するものではありません。等しいキーには同じハッシュ値が必要であり、格納中に等価性へ影響する状態を変えないという注意点も残ります。
Mapへの並行した操作を安全に行えることと、キーが安定した等価性を持つことは別の条件です。可変キーをそのままConcurrentHashMapへ移しても、キー設計の問題は解消しません。共有Mapの選択と原子的な更新については、次の記事で説明しています。

まとめ
equalsは等価性を判定し、hashCodeはハッシュを使う検索などのための値を返します。equalsで等しいオブジェクトは、必ず同じhashCodeを返す必要があります。一方、ハッシュ値の一致だけでは等しいとは限らず、衝突と同じキーへの値の上書きは別のものです。
独自クラスをHashMapのキーにするなら、何を同じキーとみなすかを決め、equals(Object)とhashCode()を対で実装します。等しい別インスタンスでの取得と、同じキーへのputによる値の置き換えまで確認すると、利用時の意図を確かめられます。
格納中は、等価性に使う状態を変更しないことも必要です。不変なキーを選び、キーを変える場合は変更前に削除してから再登録します。recordの自動生成やConcurrentHashMapの並行アクセス対応を使う場合も、等価性の範囲とキーの安定性を確認してください。


コメント