注釈

Language の目次

ほかの API の場合は、プログラムと並行して保守される「付属ファイル」が必要となります。たとえば JavaBeans には Bean と並行して保守される BeanInfo クラスが必要で、Enterprise JavaBeans (EJB) の場合は「配備記述子」が必要です。これらの付属ファイル内の情報がプログラム自体の注釈として保守されれば、扱いが簡単でエラーが発生しにくくなります。

Java プラットホームには、個々の目的に応じてさまざまな注釈の機構があります。たとえば transient 修飾子は、フィールドが直列化サブシステムによって無視されるべきであることを示す注釈であり、@deprecated javadoc タグは特定のメソッドを使用すべきでないことを示す注釈です。リリース 5.0 では、汎用の注釈 (「メタデータ」とも呼ばれる) 機能があります。 この機能では、ユーザーが独自の注釈型を定義して使用できます。この機能は、注釈型の宣言構文、宣言の注釈構文、注釈を読み取る API、注釈のクラスファイル表現、および注釈処理ツールで構成されます。

注釈はプログラムのセマンティクスに直接影響しませんが、ツールやライブラリがプログラムを扱う方法に影響します。 そのため、実行中のプログラムのセマンティクスに影響する場合があります。注釈はソースファイル、クラスファイル、または実行時にリフレクションとして読み取ることができます。

注釈は javadoc タグを補完します。通常、マークアップの目的がドキュメントの変更または生成である場合は javadoc タグを使用し、そうでない場合は注釈を使用します。

通常のアプリケーションプログラマは注釈型を定義する必要はまったくありませんが、定義することは難しくありません。注釈型の宣言は、通常のインタフェースの宣言に似ています。単価記号 (@) が interface キーワードの先頭に付きます。それぞれのメソッド宣言では、注釈型の要素を定義します。メソッド宣言には、パラメータや throws 節を含めることはできません。戻り値の型は、プリミティブ、String、Class、列挙、注釈、およびそれらの型の配列に限られます。メソッドには「デフォルト値」を設定できます。注釈型の宣言の例を示します。

/**
 * Describes the Request-For-Enhancement(RFE) that led
 * to the presence of the annotated API element.
 */
public @interface RequestForEnhancement {
    int    id();
    String synopsis();
    String engineer() default "[unassigned]"; 
    String date()    default "[unimplemented]"; 
}

注釈型を定義したら、宣言を注釈することができます。注釈は特殊な修飾子で、ほかの修飾子 (public、static、final など) が使用できる場所であれば使用できます。 ただし、注釈はほかの修飾子に先行するという規則があります。規則により、注釈は他の修飾子の前に置きます。注釈は、単価記号 (@) に続く注釈型と、要素 - 値ペアを括弧で囲んだリストで構成されます。値はコンパイル時に定数でなければなりません。上記で宣言した注釈型に対応する注釈を使用したメソッド宣言の例を示します。

@RequestForEnhancement(
    id       = 2868724,
    synopsis = "Enable time-travel",
    engineer = "Mr. Peabody",
    date     = "4/1/3007"
)
public static void travelThroughTime(Date destination) { ... }

/**
 * Indicates that the specification of the annotated API element
 * is preliminary and subject to change.
 */
public @interface Preliminary { }

@Preliminary public class TimeTravel { ... }

/**
 * Associates a copyright notice with the annotated API element.
 */
public @interface Copyright {
    String value();
}

@Copyright("2002 Yoyodyne Propulsion Systems")
public class OscillationOverthruster { ... }

import java.lang.annotation.*;

/**
 * Indicates that the annotated method is a test method.
 * This annotation should be used only on parameterless static methods.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Test { }

次のサンプルプログラムでは、一部のメソッドが前述のインタフェースで注釈されています。

public class Foo {
    @Test public static void m1() { }
    public static void m2() { }
    @Test public static void m3() {
        throw new RuntimeException("Boom");
    }
    public static void m4() { }
    @Test public static void m5() { }
    public static void m6() { }
    @Test public static void m7() {
        throw new RuntimeException("Crash");
    }
    public static void m8() { }
}

import java.lang.reflect.*;

public class RunTests {
   public static void main(String[] args) throws Exception {
      int passed = 0, failed = 0;
      for (Method m : Class.forName(args[0]).getMethods()) {
         if (m.isAnnotationPresent(Test.class)) {
            try {
               m.invoke(null);
               passed++;
            } catch (Throwable ex) {
               System.out.printf("Test %s failed: %s %n", m, ex.getCause());
               failed++;
            }
         }
      }
      System.out.printf("Passed: %d, Failed %d%n", passed, failed);
   }
}

$ java RunTests Foo
Test public static void Foo.m3() failed: java.lang.RuntimeException: Boom 
Test public static void Foo.m7() failed: java.lang.RuntimeException: Crash 
Passed: 2, Failed 2

Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved.

Java Software