Java - メソッド引数で NotNull アノテーションを使用する

参照型のメソッド引数に @NotNull を付けると、呼び出し側が値を渡すことを期待していると示せます。このアノテーションが伝えるのは契約であり、それだけで null を拒否したり検証を実行したりするわけではありません。ここでは宣言例を示し、追加の強制には何が必要かを説明します。

@NotNull アノテーションとは？

@NotNull は、値が null ではないことを期待する旨を示すために、Java のライブラリで使われるアノテーションです。API の契約をソースコードやドキュメントで確認しやすくし、そのアノテーションに対応したツールにも意図を伝えられます。提供するライブラリによってパッケージや動作は異なるため、すべての @NotNull が同じ実装だと考えず、プロジェクトで採用しているものを使ってください。

アノテーションを宣言しても Java の型システムは変わらず、変数に null を格納できなくなるわけではありません。また、メソッドが null ではない値を返すことや、null を渡すと例外が発生することも保証しません。実行時に強制するには、注釈された値を検査または検証する別の仕組みを設定する必要があります。その仕組みと動作は、この宣言だけを示す例の範囲外です。

主な利点は、メソッドの作成者と呼び出し側の間で意図を明確に伝えられることです。null ではないことを示す契約があれば、想定される入力を読み取りやすくなり、対応する静的解析やフレームワークのツールを利用できる場合もあります。役立つドキュメントですが、アプリケーションで強制が必要な場合に入力を確認する処理の代わりにはなりません。

メソッド引数で @NotNull を使用する

String などの参照型パラメーターの直前にアノテーションを置きます。次は宣言だけを示す例です。インポートとライブラリは、プロジェクトで使っているものを選んでください。

public void createUser(@NotNull String username) { ... }

ここで username はメソッド引数で、@NotNull は呼び出し側が null ではない文字列を渡すことを期待する、と示しています。String は参照型なので、別途チェックするか、設定済みの仕組みで拒否しない限り、Java では null を受け取れます。int などのプリミティブ型には null を渡せないため、この契約を示す例にはなりません。

プロジェクトで強制が必要なら、選んだアノテーションに対応する仕組みを設定して実行してください。アノテーションをインポートしたりパラメーターに記述したりするだけでは、検証は行われません。上の宣言には、依存関係、プロバイダー、呼び出し経路、実行時の結果は含まれていません。これらの選択肢はプロジェクトによって異なるため、ここでは示していません。

この契約を使うと、意図を確認しやすく、保守もしやすくなります。呼び出し側は実際のユーザー名を渡すようにし、アプリケーションで必要ならメソッド側でも入力を検査できます。同じ単純名でも異なるライブラリに由来し、ツールの対応状況も異なる場合があるため、コードベース内でアノテーションのパッケージを統一してください。