Inheritedアノテーションの動作を確認してみる

これは、なにをしたくて書いたもの？

メタアノテーションのひとつに、@Inheritedがあります。

Inherited (Java SE 21 & JDK 21)

アノテーションが継承されるというのですが、これがどういう意味なのか確認したことがなかったので見てみることにしました。

@Inheritedアノテーション

@InheritedアノテーションのJavadocの説明を見てみます。

Inherited (Java SE 21 & JDK 21)

アノテーションが継承されるようです。

注釈インタフェースが自動的に継承されることを示します。

@Inheritedアノテーションが付与されたとあるアノテーションがあり、それを親クラスに付与されている場合はサブクラスに付与されて
いなくても親クラスに付与されているか確認するようです。

継承されたメタ注釈が注釈インタフェース宣言に存在し、ユーザーがクラス宣言で注釈インタフェースに問合せを行い、クラス宣言にこのインタフェースの注釈がない場合、クラス・スーパークラスには注釈インタフェースの問合せが自動的に行われます。 このプロセスは、このインタフェースの注釈が見つかるか、クラス階層の最上位(Object)に達するまで繰り返されます。 このインタフェースの注釈を持つスーパークラスがない場合、問合せでは、該当するクラスにそのような注釈がないことが示されます。

効果があるのはクラスのみだそうです。

このメタ注釈付きインタフェースは、注釈付きインタフェースを使用してクラス以外の注釈を付ける場合は効果がありません。

インターフェースに付与しても無効なようです。

また、このメタ注釈の機能はスーパー・クラスから注釈を継承させるだけであり、実装されたインタフェースに対する注釈は無効であることにも留意してください。

確認してみましょう。

環境

今回の環境はこちら。

$ java --version
openjdk 21.0.5 2024-10-15
OpenJDK Runtime Environment (build 21.0.5+11-Ubuntu-1ubuntu124.04)
OpenJDK 64-Bit Server VM (build 21.0.5+11-Ubuntu-1ubuntu124.04, mixed mode, sharing)


$ mvn --version
Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: $HOME/.sdkman/candidates/maven/current
Java version: 21.0.5, vendor: Ubuntu, runtime: /usr/lib/jvm/java-21-openjdk-amd64
Default locale: ja_JP, platform encoding: UTF-8
OS name: "linux", version: "6.8.0-49-generic", arch: "amd64", family: "unix"

Maven依存関係など。

    <properties>
        <maven.compiler.release>21</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>5.11.3</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.assertj</groupId>
            <artifactId>assertj-core</artifactId>
            <version>3.26.3</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

確認はテストコードで行います。

確認対象の作成

比較のために、@Inheritedアノテーションを付与しないアノテーションと

src/main/java/org/littlewings/annotation/MyAnnotation.java

package org.littlewings.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface MyAnnotation {
    String value();
}

付与するアノテーションを作成します。

src/main/java/org/littlewings/annotation/MyInheritableAnnotation.java

package org.littlewings.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
@Inherited
public @interface MyInheritableAnnotation {
    String value();
}

@Inheritedアノテーションを付与しないアノテーションを使ったクラスやインターフェース。

src/main/java/org/littlewings/annotation/MyAbstractClass.java

package org.littlewings.annotation;

@MyAnnotation("super-class")
public abstract class MyAbstractClass {
    @MyAnnotation("super-class-methodA")
    public void methodA() {
    }

    @MyAnnotation("super-class-methodB")
    public void methodB() {
    }

    @MyAnnotation("super-class-abstract-methodA")
    public abstract void abstractMethodA();

    @MyAnnotation("super-class-abstract-methodB")
    public abstract void abstractMethodB();
}

src/main/java/org/littlewings/annotation/MyInterface.java

package org.littlewings.annotation;

@MyAnnotation("interface")
public interface MyInterface {
    @MyAnnotation("interface-methodA")
    void methodA();

    @MyAnnotation("interface-methodB")
    void methodB();

    @MyAnnotation("interface-default-methodA")
    default void defaultMethodA() {
    }

    @MyAnnotation("interface-default-methodB")
    default void defaultMethodB() {
    }
}

@Inheritedアノテーションを付与したアノテーションを使ったクラスやインターフェース。

src/main/java/org/littlewings/annotation/MyAbstractClassWithInherited.java

package org.littlewings.annotation;

@MyInheritableAnnotation("super-class")
public abstract class MyAbstractClassWithInherited {
    @MyInheritableAnnotation("super-class-methodA")
    public void methodA() {
    }

    @MyInheritableAnnotation("super-class-methodB")
    public void methodB() {
    }

    @MyInheritableAnnotation("super-class-abstract-methodA")
    public abstract void abstractMethodA();

    @MyInheritableAnnotation("super-class-abstract-methodB")
    public abstract void abstractMethodB();
}

src/main/java/org/littlewings/annotation/MyInterfaceWithInherited.java

package org.littlewings.annotation;

@MyInheritableAnnotation("interface")
public interface MyInterfaceWithInherited {
    @MyInheritableAnnotation("interface-methodA")
    void methodA();

    @MyInheritableAnnotation("interface-methodB")
    void methodB();

    @MyInheritableAnnotation("interface-default-methodA")
    default void defaultMethodA() {
    }

    @MyInheritableAnnotation("interface-default-methodB")
    default void defaultMethodB() {
    }
}

これらを使って、テストコードでなにが継承されてなにが継承されないのかを確認していきます。

確認してみる

では、テストコードで確認していってみましょう。

@Inheritedアノテーションがない場合

まずは@Inheritedアノテーションがない場合から。

テストコードの雛形はこちら。

src/test/java/org/littlewings/annotation/NonInheritedAnnotationTest.java

package org.littlewings.annotation;

import org.junit.jupiter.api.Test;

import static org.assertj.core.api.Assertions.assertThat;

class NonInheritedAnnotationTest {

    // ここにテストを書く！
}

アノテーションを直接クラスやメソッドに付与した場合。

    @Test
    void direct() throws NoSuchMethodException {
        @MyAnnotation("class")
        class MyClass {
            @MyAnnotation("method")
            public void method() {}
        }

        assertThat(MyClass.class.getAnnotation(MyAnnotation.class).value())
                .isEqualTo("class");
        assertThat(MyClass.class.getMethod("method").getAnnotation(MyAnnotation.class).value())
                .isEqualTo("method");
    }

これはふつうですね。

アノテーションを付与したクラスの継承。

    @Test
    void extendsClass() throws NoSuchMethodException {
        class MyClass extends MyAbstractClass {
            @Override
            public void methodB() {
            }

            @Override
            public void abstractMethodA() {
            }

            @MyAnnotation("override-abstract-methodB")
            @Override
            public void abstractMethodB() {
            }
        }

        // クラス自体には付与していないのでnull
        assertThat(MyClass.class.getAnnotation(MyAnnotation.class))
                .isNull();
        // 親クラスのメソッドを見ている
        assertThat(MyClass.class.getMethod("methodA").getAnnotation(MyAnnotation.class).value())
                .isEqualTo("super-class-methodA");
        // オーバーライドしたメソッドにはアノテーションを付与していないのでnull
        assertThat(MyClass.class.getMethod("methodB").getAnnotation(MyAnnotation.class))
                .isNull();
        // オーバーライドしたメソッドにはアノテーションを付与していないのでnull
        assertThat(MyClass.class.getMethod("abstractMethodA").getAnnotation(MyAnnotation.class))
                .isNull();
        // オーバーライドしたメソッドに明示的にアノテーションを付与している
        assertThat(MyClass.class.getMethod("abstractMethodB").getAnnotation(MyAnnotation.class).value())
                .isEqualTo("override-abstract-methodB");
    }

メソッドに関しては親クラスのものを見ているか、もしくはオーバーライドしたメソッドにアノテーションを付与しているかどうかですね。

アノテーションを付与したインターフェースを実装。

    @Test
    void implementsInterface() throws NoSuchMethodException {
        class MyClass implements MyInterface {
            @Override
            public void methodA() {
            }

            @MyAnnotation("override-interface-methodB")
            @Override
            public void methodB() {
            }

            @MyAnnotation("override-interface-default-methodB")
            @Override
            public void defaultMethodB() {
            }
        }

        // クラスにはアノテーションを付与していないのでnull
        assertThat(MyClass.class.getAnnotation(MyAnnotation.class))
                .isNull();
        // オーバーライドしたメソッドにはアノテーションを付与していないのでnull
        assertThat(MyClass.class.getMethod("methodA").getAnnotation(MyAnnotation.class))
                .isNull();
        // オーバーライドしたメソッドにアノテーションを付与している
        assertThat(MyClass.class.getMethod("methodB").getAnnotation(MyAnnotation.class).value())
                .isEqualTo("override-interface-methodB");
        // インターフェースに定義されたメソッドを見ている
        assertThat(MyClass.class.getMethod("defaultMethodA").getAnnotation(MyAnnotation.class).value())
                .isEqualTo("interface-default-methodA");
        // オーバーライドしたメソッドに明示的にアノテーションを付与している
        assertThat(MyClass.class.getMethod("defaultMethodB").getAnnotation(MyAnnotation.class).value())
                .isEqualTo("override-interface-default-methodB");
    }

クラスを継承した時とそう変わりません。

@Inheritedアノテーションを使った場合

それでは@Inheritedアノテーションを使った場合にどう変わるのかを見ていきましょう。

テストコードの雛形はこちら。

src/test/java/org/littlewings/annotation/InheritedAnnotationTest.java

package org.littlewings.annotation;

import org.junit.jupiter.api.Test;

import static org.assertj.core.api.Assertions.assertThat;

class InheritedAnnotationTest {

    // ここに、テストを書く！
}

直接付与した場合。特に意味はないですが。

    @Test
    void direct() throws NoSuchMethodException {
        @MyInheritableAnnotation("class")
        class MyClass {
            @MyInheritableAnnotation("method")
            public void method() {}
        }

        assertThat(MyClass.class.getAnnotation(MyInheritableAnnotation.class).value())
                .isEqualTo("class");
        assertThat(MyClass.class.getMethod("method").getAnnotation(MyInheritableAnnotation.class).value())
                .isEqualTo("method");
    }

アノテーションを付与したクラスの継承。

    @Test
    void extendsClass() throws NoSuchMethodException {
        class MyClass extends MyAbstractClassWithInherited {
            @Override
            public void methodB() {
            }

            @Override
            public void abstractMethodA() {
            }

            @MyInheritableAnnotation("override-abstract-methodB")
            @Override
            public void abstractMethodB() {
            }
        }

        // クラス自体には付与していないが親クラスのアノテーションを引き継ぐ
        assertThat(MyClass.class.getAnnotation(MyInheritableAnnotation.class).value())
                .isEqualTo("super-class");
        // 親クラスのメソッドを見ている
        assertThat(MyClass.class.getMethod("methodA").getAnnotation(MyInheritableAnnotation.class).value())
                .isEqualTo("super-class-methodA");
        // メソッドについては引き継がない
        assertThat(MyClass.class.getMethod("methodB").getAnnotation(MyInheritableAnnotation.class))
                .isNull();
        // オーバーライドしたメソッドにはアノテーションを付与していないのでnull
        assertThat(MyClass.class.getMethod("abstractMethodA").getAnnotation(MyInheritableAnnotation.class))
                .isNull();
        // オーバーライドしたメソッドに明示的にアノテーションを付与している
        assertThat(MyClass.class.getMethod("abstractMethodB").getAnnotation(MyInheritableAnnotation.class).value())
                .isEqualTo("override-abstract-methodB");
    }

先ほどとの違いは、サブクラス自体にはアノテーションを付与していないのに、親クラスに付与されたアノテーションを引き継いでいる
ということですね。

        // クラス自体には付与していないが親クラスのアノテーションを引き継ぐ
        assertThat(MyClass.class.getAnnotation(MyInheritableAnnotation.class).value())
                .isEqualTo("super-class");

一方でメソッドについては引き継がれません。

            @Override
            public void methodB() {
            }


        // メソッドについては引き継がない
        assertThat(MyClass.class.getMethod("methodB").getAnnotation(MyInheritableAnnotation.class))
                .isNull();

クラスのみ、と書かれていましたからね。

このメタ注釈付きインタフェースは、注釈付きインタフェースを使用してクラス以外の注釈を付ける場合は効果がありません。

なんとなくクラスにも直接アノテーションを付与したパターンも書いておきました。

    @Test
    void extendsClassDirect() throws NoSuchMethodException {
        @MyInheritableAnnotation("class")
        class MyClass extends MyAbstractClassWithInherited {
            @Override
            public void methodB() {
            }

            @Override
            public void abstractMethodA() {
            }

            @MyInheritableAnnotation("override-abstract-methodB")
            @Override
            public void abstractMethodB() {
            }
        }

        // クラス自体には付与している
        assertThat(MyClass.class.getAnnotation(MyInheritableAnnotation.class).value())
                .isEqualTo("class");
        // 親クラスのメソッドを見ている
        assertThat(MyClass.class.getMethod("methodA").getAnnotation(MyInheritableAnnotation.class).value())
                .isEqualTo("super-class-methodA");
        // メソッドについては引き継がない
        assertThat(MyClass.class.getMethod("methodB").getAnnotation(MyInheritableAnnotation.class))
                .isNull();
        // オーバーライドしたメソッドにはアノテーションを付与していないのでnull
        assertThat(MyClass.class.getMethod("abstractMethodA").getAnnotation(MyInheritableAnnotation.class))
                .isNull();
        // オーバーライドしたメソッドに明示的にアノテーションを付与している
        assertThat(MyClass.class.getMethod("abstractMethodB").getAnnotation(MyInheritableAnnotation.class).value())
                .isEqualTo("override-abstract-methodB");
    }

アノテーションを付与したインターフェースの実装。

    @Test
    void implementsInterface() throws NoSuchMethodException {
        class MyClass implements MyInterfaceWithInherited {
            @Override
            public void methodA() {
            }

            @MyInheritableAnnotation("override-interface-methodB")
            @Override
            public void methodB() {
            }

            @MyInheritableAnnotation("override-interface-default-methodB")
            @Override
            public void defaultMethodB() {
            }
        }

        // インターフェースに定義されたアノテーションは引き継がない
        assertThat(MyClass.class.getAnnotation(MyInheritableAnnotation.class))
                .isNull();
        // オーバーライドしたメソッドにはアノテーションを付与していないのでnull
        assertThat(MyClass.class.getMethod("methodA").getAnnotation(MyInheritableAnnotation.class))
                .isNull();
        // オーバーライドしたメソッドにアノテーションを付与している
        assertThat(MyClass.class.getMethod("methodB").getAnnotation(MyInheritableAnnotation.class).value())
                .isEqualTo("override-interface-methodB");
        // インターフェースに定義されたメソッドを見ている
        assertThat(MyClass.class.getMethod("defaultMethodA").getAnnotation(MyInheritableAnnotation.class).value())
                .isEqualTo("interface-default-methodA");
        // オーバーライドしたメソッドに明示的にアノテーションを付与している
        assertThat(MyClass.class.getMethod("defaultMethodB").getAnnotation(MyInheritableAnnotation.class).value())
                .isEqualTo("override-interface-default-methodB");
    }

クラスの継承の時と異なり、インターフェースに付与されたアノテーションは引き継ぎません。

        // インターフェースに定義されたアノテーションは引き継がない
        assertThat(MyClass.class.getAnnotation(MyInheritableAnnotation.class))
                .isNull();

これも書かれていたとおりですね。

また、このメタ注釈の機能はスーパー・クラスから注釈を継承させるだけであり、実装されたインタフェースに対する注釈は無効であることにも留意してください。

というわけで、@Inheritedアノテーションはあくまでクラスの定義に付与されたアノテーションに対して有効なことがわかりました。

おわりに

@Inheritedアノテーションの動作について簡単に確認してみました。

前からちゃんと意味を確認しておいた方がいいかなと思っていたので、実際に動きを見ておいてよかったです。
クラスの定義に付与されたアノテーションのみが対象、というところがポイントですね。