アノテーションインターフェース Contract

引数に応じてメソッドの動作のいくつかの側面を指定します。高度なデータフロー分析用のツールで使用できます。このアノテーションは、コードがどのように機能するかを説明するだけであり、コード生成によって機能を追加するものではないことに注意してください。

org.jetbrains.annotations.Contract に触発されて、このバリアントは、同じセマンティクスに従いながら追加の依存関係を必要としないようにするために、org.springframework.lang パッケージに導入されました。

メソッド契約の構文は次のとおりです。

  contract ::= (clause ';')* clause
  clause ::= args '->' effect
  args ::= ((arg ',')* arg )?
  arg ::= value-constraint
  value-constraint ::= '_' | 'null' | '!null' | 'false' | 'true'
  effect ::= value-constraint | 'fail' | 'this' | 'new' | 'param<N>'

制約は次のことを示します。

• _ - 任意の値
• null - null 値
• !null - 静的に null でないことが証明された値
• true - 真のブール値
• false - false のブール値

追加の戻り値は次のことを示します。

• fail - 引数が引数制約を満たす場合、メソッドは例外をスローします。
• new - メソッドは、メソッド実行前にヒープ内に存在する他のオブジェクトとは異なる、null 以外の新しいオブジェクトを返します。メソッドも純粋である場合、新しいオブジェクトはどのフィールド / 配列にも格納されず、メソッドの戻り値が使用されない場合は失われることが保証されます。
• this - メソッドは修飾子の値を返す (静的メソッドには適用されません)
• param1, param2,... - メソッドは最初の（2 番目、...）パラメーター値を返します

例:

• @Contract("_, null -> null") - 2 番目の引数が null の場合、メソッドは null を返します。
• @Contract("_, null -> null; _, !null -> !null") - メソッドは、2 番目の引数が null の場合は null を返し、それ以外の場合は null 以外の値を返します。
• @Contract("true -> fail") - true が渡されると例外をスローする典型的な assertFalse メソッド。
• @Contract("_ -> this") - メソッドは常にその修飾子 (例: StringBuilder.append(String)SE ) を返します。
• @Contract("null -> fail; _ -> param1") - メソッドは、最初の引数が null の場合に例外をスローし、それ以外の場合は最初の引数 (例: Objects.requireNonNull) を返します。
• @Contract("!null, _ -> param1; null, !null -> param2; null, null -> fail") - メソッドは最初の null 以外の引数を返します。両方の引数が null の場合は例外をスローします (例: Objects.requireNonNullElse)。