jsr 308の解説： - oracle...用できるjavaソース・ファイ...

ORACLE.COM/JAVAMAGAZINE ///////////////////////////// MARCH/APRIL 2014

JAVA TECH

46

COMMUNITY

JAVA IN ACTION

ABOUT US

blog

//java architect /

アノテーションとは、プログラムの構成要素に付加で

きる構文上のメタデータの一種であり、Java には Java SE 5で導入されました。アノテーションはコンパイル時に処理でき、コードの動作には直接影響を及ぼしません。しかし、多くのユースケースがあります。たとえば、コンパイル時に開発者向けの情報メッセージを生成し、エラーを検出できるほか、このメッセージで警告を出力しないように指定することもできます。また、アノテーションを付加されたコードの変更に使用できる Javaソース・ファイルやリソースを生成することもできます。このファイル生成機能は、アプリケーションでの管理が必要な設定リソースを削減するために便利です。 Java SE 8 には、JSR 308

（Annotations on Java Types）が組み込まれています。 JSR 308 は既存のアノテーション・フレームワークに基づき、

型アノテーションを Java 言語に組み込むものです。これにより、Java SE 8 では、これまで Java の宣言部にしか記述できなかったアノテーションを型にも適用できるようになりました。すなわち、型が指定される任意の場所（クラス・インスタンスの作成部、型のキャスト部、インタフェースの実装部、throws 句の指定部など）にアノテーションを適用できます。その結果、開発者はより多くの場所でアノテーションを活用できるようになります。型に対するアノテーションが有効な状況は多数ありますが、より強い型付けを行う場合には特に効果的で、コード内のエラーを削減できます。アノテーションが付加されたコードを検証するコンパイラ・チェッカーを記述して、コンパイル時に特定の要件を満たさないコードについて警告を生成できるため、ルールを徹底できます。Java SE 8 にはデフォル

トの型チェック・フレームワークはありませんが、型チェック用のカスタムのアノテーションやプロセッサを作成できます。また、ダウンロード可能な型チェック・フレームワークも多数あります。これらのフレームワークをJavaコンパイラのプラグインとして使用して、アノテーションを付加された型が適切であるかチェックできます。型チェック・フレームワークは、型アノテーションの定義と、コンパイラでアノテーションの処理に使用される1つ以上のプラガブル・モジュールから構成されます。本記事では、アノテーションの概要を簡単に説明した後、

Java の型にアノテーションを適用する方法、型アノテーションの記述方法、コンパイル時の型チェック用プラグインの利用方法について説明します。本記事を最後まで読めば、型アノテーションを使用して、Javaソース・コードでより強力な型付けを行えるようになります。

組込みアノテーションの概要アノテーションは名称の前に@文字が付加されるため、コード内で容易に識別できます。アノテーションは、コードの動作に直接の影響を及ぼすものではありませんが、処理時に、アノテーション・プロセッサによっ

JSR 308の解説： Javaの型アノテーション型アノテーションの利点とユースケース例

JOSH JUNEAU

情報が必要かアノテーションは、コードの動作に直接の影響は及ぼしませんが、処理時に、アノテーション・プロセッサによってファイルの生成や情報メッセージの表示などを行うことができます。

Java 8 Is Here

Josh Juneau：アプリケーション開発者、システム・アナリスト、DBA。開発ではおもにJava、PL/SQL、Jython/Pythonを利用。Jython Monthly ニュースレター、Jython Podcast、Jython Web サイトを管理している。『Java EE 7 Recipes: A Problem-Solution Approach』（Apress、2013年）、『Introducing Java EE 7: A Look at What's New』（Apress、2013年）の著者。

http://blogs.oracle.com/java


http://www.twitter.com/java

https://www.facebook.com/ilovejava

http://www.oracle.com/technetwork/java/index.html

http://java.net

mailto:[email protected]?subject=

https://jcp.org/en/jsr/detail?id=308

http://jython.org

http://jython.org


JAVA TECH

47

COMMUNITY

JAVA IN ACTION

ABOUT US

blog

//java architect /

てファイルの生成や情報メッセージの表示を行うことができます。もっとも単純な方法では、Javaソース・コード内で、コンパイラによる「チェック」が必要な要素にアノテーションを付加することで、そのコードが指定のルールに従っているかを確認できます。 Java には、アノテーションの基本セットが組み込まれています。以下の Javaアノテーションが標準提供されます。

� @Deprecated：付加された要素は今後使用すべきではないことを示す。一般的には、このアノテーションが付加された要素の機能をカプセル化した別の要素が作成されており、付加された要素は今後サポートされない。コンパイル時にこのアノテーションを付加された要素が検出された場合は警告が生成される。

� @Override：付加されたメソッドが、スーパークラス内に定義された別のメソッドをオーバーライドすることを示す。付加されたメソッドがスーパークラス内のメソッドを実際にはオーバーライドしていない場合、コンパイル時に警告が生成される。

� @SuppressWarnings：コンパイル時に、付加された要素で警告が生成される場合でもその警告を出力しないように指定する。

� @SafeVarargs：付加された要素では、安全でない可能性のある操作が可変引数（varargs）を通じて実行されることはないことを示す。コ

ンパイル時に、未チェックの可変引数に対する警告が表示されなくなる。

� @FunctionalInterface：付加された要素が関数型インタフェースであることを示す。リスト1に、これらの組込みアノテーションの使用例を示します。

型アノテーションのユースケースアノテーションは、より強い型付けを行うため、任意の Java の型宣言または式に付加できます。以降では、型アノテーションが有用な状況を、ユースケースを挙げて説明します。新しいオブジェクトの生成：型アノテーションにより、オブジェクト・コンストラクタに付加されたアノテーションと実際のオブジェクトが適合しているかを静的に検証できます。次のように使用します。

ジェネリクスと配列：ジェネリクスと配列は型アノテーションの使用に適しています。型アノテーションを付加することで、オブジェクトに期待されるデータを制限できるからです。型アノテーションのコンパイラ・チェック機能を利用して、ジェネリクスや配列の要素に正しいデータ型が格納されているかを確認できます。また、アノテーションは開発者に対する視覚的な注意喚起としても有効であり、以下のように変数や配列の意図を示すことができます。

型のキャスト：型のキャストにアノテーションを付加することで、キャスト時にアノテーションで示された型を維持できます。また、以下のように、意図しないキャストの使用方法について警告する修飾子としても使用できます。

または

継承：クラスで正しい型やオブジェクトが継承または実装されるようにすることで、アプリケーション・コード内のエラーを大幅に削減できます。リスト2に、ある実装句の型アノテーションの例を示します。例外：例外に対してアノテーションを付加して、特定の条件に従っているかを確認できます。次のように使用します。

レシーバ：メソッドのレシーバ・パラメータにアノテーションを付加することもできます。そのためには、パラメータ・リスト内で明示的に記述します。リスト3に、メソッドのレシーバ・パラメータに対する型アノテーションの使用例を示します。

型アノテーションの適用型アノテーションは、さまざまな方法で型に対して適用できます。一般的に、型アノテーションは適用する型の直前に配置します。ただし、配列の場合は、型の関連部分の前に配置する必要があります。たとえば、以下の宣言では、配列は読取り専用である必要があります。

配列や配列の型にアノテーションを付加する場合は、配列内の目的の要素に適用されるように、正しい位置にアノテーションを配置することが重要です。例をいくつか紹介します。

Forecast currentForecast = new @Interned Forecast();

@NonEmpty Forecast []

@Readonly Object x; … (@Readonly Date) x …

Object myObject = (@NotNull Object) obj

catch (@Critical Exception e) { ... }

Forecast @Readonly [] fiveDay = new Forecast @Readonly [5];

すべてのリストのテキストをダウンロード

@Overridepublic void start(Stage primaryStage) { ...}

@Deprecatedpublic void buttonAction(ActionEvent event){ ...}

リスト1 リスト2 リスト3








https://java.net/projects/java-magazine/downloads/directory/MarchApril2014


JAVA TECH

48

COMMUNITY

JAVA IN ACTION

ABOUT US

blog

//java architect / � int 型に対するアノテーション：

� int[] 配列型に対するアノテーション：

� int[][] 配列型に対するアノテーション：

� int[][] の要素となる型である int[]型に対するアノテーション：

入手可能な型アノテーションの利用強い型チェックを実施するためには、特定の条件を型に適用するための適切な一連のアノテーションが必要です。現在、多数の型チェック用アノ

テーションが提供されており、こうしたアノテーションを提供するフレームワークにChecker Framework があります。 Java SE 8 には型固有のアノテーションは定義されていませんが、Checker Framework などのライブラリにより、型に適用して特定の条件を検証できるアノテーションが提供されています。たとえば、Checker Framework に含まれる@NonNullアノテーションを型に適用した場合は、コンパイル時に null でないことを検証できます。同様にChecker Framework に含まれる@Internedアノテーションは、ある変数がオブジェクトの正準表現を参照することを示します。以下に、Checker Frameworkで提供されているその他のアノテーションの例を示します。

� @GuardedBy：指定したロックを保持している場合に限り、この型の値にアクセスできることを示す

� @Untainted：汚染されていない信頼できる値のみを含む型であることを示す

� @Tainted：汚染されている信頼できない値のみを含む可能性のある型であることを示す。@Untaintedのスーパータイプ

� @Regex：文字列に対する有効な正規表現であることを示すChecker Framework に含まれるアノテーションを利用するためには、このフレームワークのダウンロード後、CLASSPATH にアノテーションのソース・ファイルを追加するか、Mavenを使用している場合はChecker Framework を依存関係として追加する必要があります。 NetBeans などの IDEを使用してい

る場合は、Add Dependencyダイアログ・ボックスを使用して、Checker Framework を依存関係として容易に追加できます。例として、Mavenプロジェクトに依存関係を追加する方法を図 1に示します。アプリケーションに依存関係を追加

した後、アノテーションをクラスにインポートすることで、任意の型に対してアノテーションを使用できるようになります（リスト4）。既存のアノテーション実装のいずれでも対応できない要件がある場合は、独自のニーズに合うカスタム・アノテーションを作成することもできます。

カスタム・アノテーションの定義アノテーションはインタフェースの一種であり、アノテーション型の定義はインタフェースの定義とよく似ています。異なる点は、アノテーション型の定義では interface キーワードの前に@文字を付加することです。アノテーションの定義にもアノテーションを使用します。このアノテーションは、型の定義に関する情報を指定します。アノテーションを定義する際には、以下のアノテーションを使用できます。

� @Retention：アノテーションの保管方法を指定する。使用できるオプションは、CLASS（デフォルト値、実行時にアクセス不可）、RUNTIME（実行時にアクセス可能）、SOURCE

@ReadOnly int [] nums;

int @ReadOnly [] nums;

int @ReadOnly [][] nums;

int [] @ReadOnly [] nums;

図1


import checkers.interning.quals.Interned;import checkers.nullness.quals.NonNull;...@ZipCode@NonNullString zipCode;

リスト4








http://types.cs.washington.edu/checker-framework/



JAVA TECH

49

COMMUNITY

JAVA IN ACTION

ABOUT US

blog

//java architect /

（クラスのコンパイル後にアノテーションを破棄）。

� @Documented：このアノテーションを Javadoc の対象とする。

� @Target：アノテーションの適用が可能なコンテキストを指定する。value（java.lang.annotation.ElementType[] 型）という1つの要素が含まれる。

� @Inherited：このアノテーションが付加されたクラスのサブクラスに、このアノテーションが継承されることを示す。標準の宣言部のアノテーションと型アノテーションの定義は非常によく似ています。おもな違いは、@Targetの記述にあります。@Target は、そのアノテーションを適用可能な要素の種類を表します。宣言部のアノテーションはフィールドを対象にするのに対して、型アノテーションは型を対象にします。宣言部のアノテーションには以下のメタアノテーションを記述できます。

型アノテーションには以下のメタアノテーションを記述する必要があります。

型パラメータを対象にする型アノテーションには、以下のメタアノテーションを記述する必要があります。

型アノテーションは、複数のコンテキストに適用できます。その場合は、1つのリストで複数の ElementTypeを指定できます。リスト内に同じElementType が重複している場合は、コンパイル時にエラーとなります。リスト5は、@NonNullという型アノテーションの定義です。このコードでは、@NonNull の定義に 2つの対象が含まれており、型と型パラメータのいずれかにこのアノテーションが適用されることを意味しています。標準の宣言部のアノテーションと同様に、型アノテーションにもパラメータを記述して、さらにデフォルト値を指定することもできます。型アノテーションのパラメータを指定するためには、アノテーション・インタフェース内にパラメータの宣言を追加します。リスト6に、パラメータが 1つある型アノテーションの例を示します。このパラメータは、zipという名前で識別される文字列フィールドです。1つのアノテーションをフィールド

と型に対して同時に適用することも可能です。たとえば、ある変数の宣言に@Fooアノテーションを適用した場合、@Target にフィールドと型の両方の要素を指定していれば、このアノテーションを型の宣言に対しても同時に適用できます。この場合、たとえば宣言は以下のようになり、型であるStringと変数であるmyStringの両方にアノテーションが適用されます。

型アノテーションの処理型アノテーションのコードを記述したら、コンパイラ・プラグインを使用して、各アノテーションに応じた処理を行う必要があります。前述のとおり、アノテーションがアプリケーション・コードの動作に影響を及ぼすことはありません。プロセッサによってコードが解析され、アノテーションの検出時に特定のタスクが実行されます。カスタム・アノテーションを記述する場合は、アノテーションを処理するためのカスタムのコンパイラ・プラグインを記述する必要もあります。JSR 269（Pluggable Annotation Processing API）により、カスタム・アノテーション・プロセッサの開発がサポートされます。アノテーション・プロセッサの開発については、本記事では取り上げませんが、Pluggable Annotation Processing API を使用して簡単に開発できます。また、Checker Frameworkプロセッサなど、ダウンロード可能なアノテーション・プロセッサもあります。型修飾コンパイラ・プラグインの利用：Checker Framework は、過去の Java

リリースを使用しているアプリケーションでも利用可能なライブラリです。すぐに利用できる多数の型アノテーションが、アノテーション・プロセッサ（コードのコンパイル時に指定可能）とともに提供されています。Java SE 8でのアノテーションのサポートによって、Checker Framework などのサード・パーティ製のライブラリを利用できるようになります。そのため、事前に作成された型アノテーションを、新しいコードにも既存のコードにも容易に組み込むことができます。すでに、Checker Framework の型アノテーションを利用するために、このフレームワークをプロジェクトに組み込む方法について説明しました。しかし、カスタム・アノテーション・プロセッサを併用しない場合、アノテーションは処理されないため、単に情報を提供するためだけの記述となってしまいます。 Checker Frameworkでは、このフレームワークで利用できる個々の型アノテーションに対応したカスタム・プロセッサが多数提供されています。

@Target(ElementType.FIELD)

@Target(ElementType.TYPE_USE)

@Target (ElementType.TYPE_PARAMETER) @Foo String myString;


@Documented@Retention(RetentionPolicy.RUNTIME)@Target({ElementType.TYPE_USE, ElementType.TYPE_PARAMETER})@TypeQualifierpublic @interface NonNull {}

リスト5 リスト6








https://jcp.org/en/jsr/detail?id=269



JAVA TECH

50

COMMUNITY

JAVA IN ACTION

ABOUT US

blog

//java architect /

フレームワークをマシンにインストールした後は、フレームワークに同梱されたカスタムの javacコンパイラを使用して、アノテーションを含むアプリケーションをコンパイルできます。 Checker Framework を利用するためには、.zipファイルをダウンロードして、マシンに展開します。必要に応じて、Checker Framework のバイナリを実行しやすくするために、実行パスを更新するか、エイリアスを作成します。インストール後、リスト7のようなコマンドを実行して、フレームワークを検証できます。どのアノテーションが利用できるのかを把握することは重要であるため、Checker Frameworkを使用する場合は最初にフレームワークのドキュメントに目を通し、この情報を確認してください。Checker Frameworkでは、型アノテーションのことを修飾子（qualifier）と呼んでいます。利用できる修飾子を確認した後は、既存のアプリケーションの型に適用した場合に役立ちそうな修飾子を調査します。新しいアプリケーションを作成する場合は、型に応じてメリットのある修飾子を適用します。コードをチェックするた

めには、コンパイラで使用される型チェック用のプロセッサを指定する必要があります。そのためには、カスタムの javac を、‒processorフラグとプロセッサの完全修飾名を指定して通常どおり実行します。たとえば、@NonNull アノテーションを使用する場合は、コードのコンパイル時に nullnessプロセッサを指定する必要があります。Checker Framework をインストールした場合は、フレームワークとともに配布されているカスタムの javac を使用し、checkers.nullness.NullnessChecker

プロセッサを指定してアノテーションを処理します。リスト8は、@NonNullアノテーションを利用したサンプル・クラスです。このクラスをコンパイルするためには、リスト9のコマンドを使用します。リスト8のクラスをコンパイルした場合、警告は表示されません。一方、このアノテーション付きの変数宣言にnull を代入した場合は、nullnessチェッカーにより警告が表示されます。変更後のクラスをリスト10に、コンパイラにより生成される警告をリスト11に示します。カスタムの javac バイナリではなく標準 JDKインストールを使用して

checkers.jar を実行することもできます。この jarファイルでは、標準コンパイラではなくCheckerコンパイラが利用されます。リスト12に、カスタムの javac を使用せず、checkers.jar を呼び出す例を示します。Checker Frameworkでは、CLASSPATH にカスタムの javacコマンドを追加する手順やエイリアスを作成する手順、フレームワークをコンパイル・プロセスに容易に統合する他の方法について説明されています。詳細は、このフレームワークのドキュメントを参照してください。複数のプロセッサを併用したコンパイル：コンパイル時に複数のプロセッサを指定したい場合はどうでしょうか。Checker Framework によるコンパイルでは、自動検出を通じて複数のプロセッサを使用できます。自動検出を有効にするには、META-INF/services/javax.annotation.processing.Processorという設定ファイルをCLASSPATH 内に配置する必要があります。このファイルには、使

用するCheckerプラグインの名前を、1行に 1つずつ記述する必要があります。自動検出を使用した場合は、‒processorフラグを指定していなくても、設定ファイルに記述したCheckerプラグインが javacコンパイラによって常に実行されます。自動検出を無効にする場合は、javac の実行時に ‒proc:noneコマンドライン・オプションを指定します。このオプションによってすべてのアノテーション処理が無効化されます。Mavenプラグインの利用：Checker Frameworkを任意のMavenプロジェクトに追加できるプラグインがあります。このプラグインを利用するためには、プロジェクト・オブジェクト・モデル（POM）を編集し、Checker Frameworkリポジトリの指定、プロジェクトへの依存関係の追加、プロジェクトのビルド・ライフサイクルへのプラグイン指定を行います。リスト13、リスト14、リスト15に、各タスクを実行するための例を示します。 Mavenプラグインを利用すれば、

java -jar binary/checkers.jar -versionjavac 1.8.0-jsr308-1.7.1

リスト7 リスト8 リスト9 リスト10 リスト11 リスト12


ルールの徹底もっとも単純な方法では、Javaソース・コード内で、コンパイラによる「チェック」が必要な要素にアノテーションを付加することで、そのコードが指定のルールに従っているかを確認できます。











JAVA TECH

51

COMMUNITY

JAVA IN ACTION

ABOUT US

blog

//java architect /

Checker Framework を IDE 内部でも使用できるように、簡単にプロジェクトにバインドできます。たとえば、NetBeans Mavenプロジェクトでプラグインを構成した場合、NetBeans内でプロジェクトがビルドされるたびにChecker Framework によりアノテーションが処理されます。

型アノテーションを含むコードの配布特定の型アノテーションを利用するためには、CLASSPATH 内にその宣言を追加する必要があります。同じことが、型アノテーションを含むアプリケーションを配布する場合にも当てはまります。型アノテーションを含むソース・コードをコンパイルまたは実行するためには、少なくともアノテーション宣言クラスをCLASSPATH内に配置する必要があります。カスタム・アノテーションを記述した場合は、そのアノテーションの宣言がアプリケーションのソース・コードにすでに含まれている可能性があります。含まれていない場合は、カスタム・アノテーションの宣言を含むJARファイルをコード配布パッケージ内に含める必要があります。Checker Framework には、checkers-quals.jarというJARファイルがあります。このファイルには、配布用の修飾子（アノテーション）の宣言が含まれています。アプリケーション内で Checker Frameworkアノテーションを使用している場合は、この JARファイルを配布パッケージ内に追加してください。

まとめJava SE 8 では型アノテーションが新たにサポートされます。型アノテーションによって、強い型チェック・システムを実現し、コード内のエラーやバグを削減できます。型アノテーションを使用するアプリケーションは、下位互換性も維持されます。アノテーションはアプリケーションの実行時の操作に影響を及ぼさないからです。開発者はカスタムの型アノテーションを作成することも、サード・パーティ製ソリューションのアノテーションを利用することもできます。よく知られている型チェック・フレームワークの 1つが Checker Frameworkであり、Java SE 8 以前のリリースで使用できます。エラーの起こりにくいアプリケーションを構築するために、Checker Framework のドキュメントをぜひご覧ください。</article>


<repositories> <repository> <id>checker-framework-repo</id> <url>http://types.cs.washington.edu/m2-repo</url> </repository></repositories><pluginRepositories> <pluginRepository> <id>checker-framework-repo</id> <url>http://types.cs.washington.edu/m2-repo</url> </pluginRepository></pluginRepositories>

リスト13 リスト14 リスト15

LEARN MORE• Java Tutorialsのアノテーションに関するレッスン• Checker Framework

Java 8 Is Here

MORE ON TOPIC:








http://docs.oracle.com/javase/tutorial/java/annotations/index.html

http://docs.oracle.com/javase/tutorial/java/annotations/index.html

jsr 308の解説： - oracle...用できるjavaソース・ファイ...

Documents