独自アノテーションを作って使いこなそう！

前回の記事では、Javaの組み込みアノテーションについて学んだね。
Javaのアノテーションを使いこなそう | ToolDocs
今回はさらに踏み込んで、自分だけのアノテーション（独自アノテーション）を作る方法と、それをどうやって使うのかを一緒に見ていこう！「え、そんなことできるの？」って思った人もいるかもしれないけど、これが意外と簡単で、しかもコードをすごくきれいに、そして便利にする強力なツールなんだ。

なんで独自アノテーションを作るの？

「わざわざ独自アノテーションを作る意味あるの？」って思うかもしれないよね。大きく分けて、次の2つの理由があるんだ。

メタデータの追加: コードに「追加情報」を付け加えたいときに使うよ。例えば、「このメソッドはログインが必要だよ」とか、「このフィールドはデータベースに保存する値だよ」みたいにね。こういう情報をコードそのものに直接埋め込むことで、後からその情報をプログラムで読み取って特別な処理をさせることができるようになるんだ。
コードの整理と簡潔化: 繰り返し出てくる定型的なコードをアノテーションにまとめることで、コードがすっきりして読みやすくなるんだ。

独自アノテーションの作り方

独自アノテーションを作るのは、実はインターフェースを作るのとすごく似ているんだ。キーワード@interfaceを使うだけ。

Java

public @interface MyAnnotation {
    // ここに要素を定義する
}

たったこれだけ！これだけでもう独自アノテーションの完成だよ。でも、これだけだと何も情報を持てないから、次に「要素」を追加する方法を見ていこう。

要素（メンバ）の定義

アノテーションは、中に値を持たせることができるんだ。これを「要素」とか「メンバ」って呼ぶよ。要素は、メソッドの定義に似ているけど、引数は持てないんだ。

Java

public @interface MyAnnotation {
    String value(); // 文字列型の要素
    int count() default 1; // 整数型の要素、デフォルト値も設定できる
    String[] tags(); // 配列型の要素
}

それぞれの要素には、型と名前を指定するよ。defaultキーワードを使うと、アノテーションを使うときにその要素の指定を省略した場合のデフォルト値を設定できるんだ。これはすごく便利だよね！

アノテーションの「アノテーション」：メタアノテーション

独自アノテーションを作る上で、とっても重要なのがメタアノテーションって呼ばれるもの。これは「アノテーションを定義するためのアノテーション」のことなんだ。ちょっとややこしいけど、これらを使うことで、作ったアノテーションが「どこに」「いつまで」使えるのかを決めることができるんだ。

主なメタアノテーションは次の4つだよ。

1.@Target: どこにアノテーションを付けられるかを指定するよ。

Java

@Target({ElementType.TYPE, ElementType.METHOD}) // クラスとメソッドに付けられるアノテーション 
public @interface MyAnnotation {  String value(); }

2.@Retention: いつまでアノテーションの情報が保持されるかを指定するよ。

Java

@Retention(RetentionPolicy.RUNTIME) // 実行時まで情報が残る 
public @interface MyAnnotation {                                                  String value(); 
}

3.@Documented: このアノテーションがJavadocに含められるべきかどうかを指定するよ。

Java

@Documented public @interface MyAnnotation {  String value(); }

4.@Inherited: このアノテーションが、アノテーションが付けられたクラスのサブクラスに継承されるかどうかを指定するよ。

Java

@Inherited public @interface MyAnnotation {  String value(); }

これらを組み合わせることで、どんなアノテーションを作りたいのかを細かく設定できるんだ。

独自アノテーションの使い方

独自アノテーションを作ったら、あとは組み込みアノテーションと同じように、コードに@を付けて使うだけだよ。

Java

// MyAnnotation.java
import java.lang.annotation.*;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface CustomLog {
    String message() default "No message";
    int level() default 1;
}

Java

// MyClass.java
public class MyClass {

    @CustomLog(message = "ユーザーログイン処理", level = 2)
    public void loginUser(String username) {
        System.out.println(username + "がログインしました。");
    }

    @CustomLog(message = "データ保存処理") // levelはデフォルト値が使われる
    public void saveData() {
        System.out.println("データを保存しました。");
    }

    @CustomLog // messageもlevelもデフォルト値が使われる
    public void doSomething() {
        System.out.println("何か処理をしました。");
    }
}

ね、簡単でしょ？これで、loginUserメソッドには「ユーザーログイン処理」というメッセージとレベル2のログ情報が付与されたことになるんだ。

独自アノテーションの情報を取得する（リフレクション）

独自アノテーションの真価が発揮されるのは、そのアノテーションが持つ情報を実行時に読み取って、それに応じた処理を行うときなんだ。これにはリフレクションというJavaの機能を使うよ。リフレクションを使うと、プログラムが自分自身の構造（クラス、メソッド、フィールドなど）を調べたり、実行時にそれらを操作したりすることができるんだ。

ちょっとだけ複雑になるけど、頑張ってついてきてね！

Java

import java.lang.reflect.Method;

public class AnnotationProcessor {

    public static void main(String[] args) {
        MyClass myObject = new MyClass();

        // MyClassのすべてのメソッドを取得
        Method[] methods = myObject.getClass().getDeclaredMethods();

        for (Method method : methods) {
            // 各メソッドにCustomLogアノテーションが付いているかチェック
            if (method.isAnnotationPresent(CustomLog.class)) {
                // CustomLogアノテーションを取得
                CustomLog customLog = method.getAnnotation(CustomLog.class);

                // アノテーションの情報を取得して表示
                System.out.println("--- メソッド: " + method.getName() + " ---");
                System.out.println("  ログメッセージ: " + customLog.message());
                System.out.println("  ログレベル: " + customLog.level());

                // ここで取得した情報を使って、特別な処理を行うことができる
                // 例: ログレベルに応じてログを出力する、特定の処理を実行する、など
                if (customLog.level() > 1) {
                    System.out.println("  高レベルのログ処理が必要です。");
                }
            }
        }
    }
}

上記のコードを実行すると、MyClassの各メソッドに付けられた@CustomLogアノテーションの情報がコンソールに出力されるはずだよ。

--- メソッド: loginUser ---
  ログメッセージ: ユーザーログイン処理
  ログレベル: 2
  高レベルのログ処理が必要です。
--- メソッド: saveData ---
  ログメッセージ: データ保存処理
  ログレベル: 1
--- メソッド: doSomething ---
  ログメッセージ: No message
  ログレベル: 1

このように、リフレクションを使うことで、アノテーションが付与されたコードの特性を動的に判断し、それに基づいた柔軟な処理を実装できるんだ。これが、フレームワークなどでアノテーションが多用される理由の一つなんだよ。

どんなときに独自アノテーションが役立つ？

独自アノテーションは、次のような場面で特に力を発揮するよ。

テストコード: テストメソッドに特定の情報を付与して、テストランナーがその情報を元にテストの実行順序を決めたり、特別なセットアップをしたりする場合。
Webフレームワーク: 特定のURLに対応するメソッドをアノテーションで指定したり、リクエストパラメータを自動的にオブジェクトにマッピングしたりする場合。
ログ出力: メソッドの実行前後に自動的にログを出力するような共通処理を、アノテーションを付けるだけで実現したい場合。
設定ファイル代わり: 小規模な設定情報をコード内に直接埋め込みたい場合。

独自アノテーションを使いこなせるようになると、より洗練された、拡張性の高いコードを書けるようになるよ！