Lesson 5: Java @ Annotations

All major Java @ use cases: built-ins, custom annotations, meta-annotations, repeatable annotations, type-use annotations, package and record targets, decorator-style metadata, getter/setter metadata, and reflection.

scripts/run.sh lesson_5 demo
scripts/run.sh lesson_5 exercise
scripts/apply_answers.sh lesson_5
scripts/run.sh lesson_5 verify
scripts/reset_exercises.sh lesson_5

Lesson README

Lesson 5: Java @ Annotations

This lesson explains what the @ symbol means in Java and shows the major places it appears: built-in annotations, custom annotations, meta-annotations, repeatable annotations, type-use annotations, package annotations, record component annotations, type-parameter annotations, decorator/interceptor-style annotations, getter/setter-style annotations, reflection, and @interface annotation declarations.

120-Minute Plan

Exercise

Use workbook.md for the full two-hour learner path. It includes annotation-reading drills, implementation rounds, and edge-case checks.

Edit src/exercise/java/tutorial/lesson5/exercise/AnnotationExplorer.java.

Functions to implement:

• annotationSimpleNames
• endpointSummary
• permissionValues
• inheritedRuntimeCheck
• typeUseHintsOnFirstParameter
• deprecatedSummary
• decoratorName
• hasGetterSetterMetadata
• packageMarkerValue
• recordComponentColumn
• typeParameterTags

The lesson compiles before implementation. After applying answers, run scripts/run.sh lesson_5 verify to check reflection, repeatable annotations, inherited annotations, type-use annotations, deprecated metadata, decorator-style metadata, getter/setter-style metadata, package annotations, record component annotations, and type-parameter annotations.

Learner Workbook

Learner Workbook: Lesson 5 Java @ Annotations

This workbook is designed to take about two hours. The goal is to understand what Java annotations are, how annotation declarations work, where annotations can be placed, and how runtime reflection can read them.

What You Should Understand By The End

• @Something attaches metadata to Java program elements.
• public @interface Name declares a new annotation type.
• Meta-annotations such as @Retention and @Target control where annotation metadata exists and where it can be used.
• Runtime reflection can read only annotations retained with RetentionPolicy.RUNTIME.
• Repeatable annotations are read with getAnnotationsByType.
• @Inherited applies only to class annotations, not method annotations.
• @Target(TYPE_USE) lets annotations appear inside types, such as a method parameter's annotated type.
• Decorator/interceptor annotations such as @Logged or @Decorates are metadata until framework code interprets them.
• Getter/setter annotations such as Lombok-style @Getter and @Setter require an annotation processor or framework; in this repo they are intentionally metadata only.
• Package annotations use package-info.java.
• Record component and type-parameter annotations have their own reflection APIs.

0-15 Minutes: Run And Inventory

Run:

scripts/reset_exercises.sh lesson_5
scripts/run.sh lesson_5 demo
scripts/run.sh lesson_5 exercise

Before opening the source, write down every @ name printed or implied by the output. Group them into:

• built-in Java annotations
• custom course annotations
• meta-annotations that configure other annotations
• annotations read through reflection
• decorator/interceptor metadata
• getter/setter-style metadata

15-35 Minutes: Built-In Annotation Tour

Open:

• JsonHandler.java
• RequestHandler.java
• AnnotationUtilities.java

Find these examples:

• @Override: asks the compiler to prove a method overrides or implements another method.
• @FunctionalInterface: asks the compiler to prove an interface has one abstract method.
• @SafeVarargs: documents and checks safer use of generic varargs.
• @SuppressWarnings: suppresses selected compiler warnings at a narrow scope.
• @Deprecated: marks an API as old and exposes metadata such as since and forRemoval.

For each one, answer: is this used by the compiler, tools, runtime reflection, or some combination?

35-55 Minutes: Custom Annotation Declarations

Open:

• Route.java
• Trace.java
• Role.java
• Roles.java
• Audited.java
• NonBlank.java
• Getter.java
• Setter.java
• Logged.java
• PackageMarker.java
• RecordKey.java
• TypeParameterRole.java

Study the @interface syntax. Annotation methods such as String path(); are not normal methods with bodies; they declare annotation elements.

Focus on these meta-annotations:

• @Retention(RetentionPolicy.RUNTIME): reflection can read it at runtime.
• @Retention(RetentionPolicy.CLASS): stored in class files but not visible through normal runtime reflection.
• @Target(ElementType.METHOD): restricts where the annotation can be used.
• @Documented: tells Javadoc to include the annotation in generated docs.
• @Inherited: subclasses can see class-level annotation metadata.
• @Repeatable: lets the same annotation appear more than once.
• @Target(PACKAGE): used through package-info.java.
• @Target(RECORD_COMPONENT): used on record components and read with record reflection.
• @Target(TYPE_PARAMETER): used on generic type parameter declarations.

55-75 Minutes: Reflection Trace

Open AnnotationUseDemo.java.

Trace these reflection calls:

• type.getAnnotations()
• type.getAnnotation(Audited.class)
• method.getAnnotation(Route.class)
• type.getAnnotationsByType(Role.class)
• method.getParameters()[0].getAnnotatedType().getAnnotations()
• type.getPackage().getAnnotation(PackageMarker.class)
• recordType.getRecordComponents()
• type.getTypeParameters()

Answer these questions:

• Why is @ClassOnly not visible through isAnnotationPresent at runtime?
• Why does AdminController see @Audited even though it does not declare it?
• Why does @Role need both Role and Roles?
• Why is type-use reflection different from parameter annotation reflection?
• Why does @Getter not generate a getter in this repo?
• What would need to exist for @Decorates to actually wrap a method call?
• Why do package annotations live in a special file rather than a normal class?

75-105 Minutes: Implement In Rounds

Edit src/exercise/java/tutorial/lesson5/exercise/AnnotationExplorer.java.

Round 1:

• Implement annotationSimpleNames.
• Use type.getAnnotations().
• Sort names to keep output deterministic.

Round 2:

• Implement endpointSummary.
• Find a method by name and read @Endpoint.
• Return <missing> when either the method or annotation is absent.

Round 3:

• Implement permissionValues.
• Use getAnnotationsByType(Permission.class), not only getAnnotation(Permissions.class).

Round 4:

• Implement inheritedRuntimeCheck.
• Confirm UserService inherits @RuntimeCheck from BaseService.

Round 5:

• Implement typeUseHintsOnFirstParameter.
• Inspect parameter.getAnnotatedType().getAnnotations().

Round 6:

• Implement deprecatedSummary.
• Read @Deprecated.since() and @Deprecated.forRemoval().

Round 7:

• Implement decoratorName.
• Read @Decorates from a method.
• Remember: the annotation does not decorate by itself.

Round 8:

• Implement hasGetterSetterMetadata.
• Read @AutoGetter on the class and @AutoSetter on the field.
• Remember: the annotations do not generate code in this repo.

Round 9:

• Implement packageMarkerValue.
• Read the package annotation from package-info.java.

Round 10:

• Implement recordComponentColumn.
• Use recordType.getRecordComponents().

Round 11:

• Implement typeParameterTags.
• Use type.getTypeParameters().

105-115 Minutes: Verify Answers

Run:

scripts/apply_answers.sh lesson_5
scripts/run.sh lesson_5 verify
scripts/reset_exercises.sh lesson_5

The verifier checks missing methods, missing annotations, repeatable annotations, inherited annotations, type-use annotations, non-deprecated methods, decorator metadata, getter/setter metadata, package annotations, record component annotations, and type-parameter annotations.

115-120 Minutes: Annotation Design Drill

Design one annotation for a real project you know. Decide:

• Where can it be used?
• Should it be visible at runtime?
• Should it be repeatable?
• Who reads it: compiler, framework, test, documentation tool, or runtime code?
• Would an explicit method call be clearer than metadata?

Instructor Notes

Instructor Notes: Lesson 5 Java @ Annotations

Session Goal

Teach annotations as metadata attached to Java declarations and types. Learners should understand common built-in annotations, how custom annotations are declared, how meta-annotations constrain them, how frameworks use reflection to read them, and why getter/setter annotations usually need annotation processors.

Learning Outcomes

By the end of 120 minutes, learners should be able to:

• Explain the difference between using an annotation and declaring one with @interface.
• Explain @Retention, @Target, @Inherited, and @Repeatable.
• Read annotation attributes through reflection.
• Explain why not all annotations are visible at runtime.
• Use built-in annotations correctly without treating them as magic comments.
• Explain decorator/interceptor annotations and getter/setter annotations as metadata-driven framework patterns.

Before Class

Run:

scripts/reset_exercises.sh lesson_5
scripts/run.sh lesson_5 demo
scripts/run.sh lesson_5 exercise

Know the key files:

• src/demo/java/tutorial/lesson5/demo/AnnotationUseDemo.java
• src/demo/java/tutorial/lesson5/demo/AnnotationUtilities.java
• src/demo/java/tutorial/lesson5/demo/Route.java
• src/demo/java/tutorial/lesson5/demo/Role.java
• src/demo/java/tutorial/lesson5/demo/Logged.java
• src/demo/java/tutorial/lesson5/demo/Getter.java
• src/demo/java/tutorial/lesson5/demo/Setter.java
• src/exercise/java/tutorial/lesson5/exercise/AnnotationExplorer.java

Teaching Flow

Teaching Script

Use this framing:

"The @ symbol does not run code by itself. It attaches metadata. Something else must care: the compiler, Javadoc, a framework, an annotation processor, or runtime reflection."

Important distinctions:

• @Override is useful even though runtime code does not read it.
• @Deprecated is visible to tools and can also be reflected.
• @Retention determines whether runtime reflection can see an annotation.
• @Target prevents annotations from being placed on the wrong program element.
• @Repeatable changes how multiple copies are stored and retrieved.
• @Inherited is narrow: it only works for class annotations through class inheritance.
• Decorator/interceptor annotations such as @Logged are metadata; an interceptor or proxy must read them to add behavior.
• Getter/setter annotations such as Lombok-style @Getter and @Setter need an annotation processor to generate methods. In this repo they are metadata only, so explicit methods still exist.

Exercise Guidance

Learners edit AnnotationExplorer.java.

Give hints in this order:

• getAnnotations() returns runtime-visible annotations, including inherited class annotations.
• Repeatable annotations should be read with getAnnotationsByType.
• Missing method and missing annotation are different edge cases but both return <missing> in this exercise.
• Type-use annotations are found through getAnnotatedType, not plain getAnnotations on the parameter.
• @Deprecated has attributes; it is not only a marker.
• Package annotations are read from a package object and declared in package-info.java.
• Record component annotations are read from RecordComponent.
• Type parameter annotations are read from generic declarations such as Class.getTypeParameters.

Common Mistakes

• Assuming every annotation is visible at runtime.
• Using getDeclaredAnnotations() and missing inherited annotations.
• Reading only the repeatable container annotation instead of getAnnotationsByType.
• Looking for type-use annotations on Parameter.getAnnotations().
• Treating annotations as behavior instead of metadata that another tool or runtime code interprets.
• Assuming Lombok-style annotations generate methods without Lombok or an annotation processor.
• Assuming decorator annotations wrap methods without proxy/interceptor code.

Functions In This Lesson

private AnnotationExplorer() {

public static List<String> annotationSimpleNames(Class<?> type) {

public static String endpointSummary(Class<?> type, String methodName) {

public static List<String> permissionValues(Class<?> type) {

public static Optional<String> inheritedRuntimeCheck(Class<?> type) {

public static List<String> typeUseHintsOnFirstParameter(Class<?> type, String methodName) {

public static String deprecatedSummary(Method method) {

public static Optional<String> decoratorName(Class<?> type, String methodName) {

public static boolean hasGetterSetterMetadata(Class<?> type, String fieldName) {

public static Optional<String> packageMarkerValue(Package targetPackage) {

public static Optional<String> recordComponentColumn(Class<?> recordType, String componentName) {

public static List<String> typeParameterTags(Class<?> type) {

private static Optional<Method> findMethod(Class<?> type, String methodName) {

private static List<String> typeHintValues(Parameter parameter) {

public Account(String displayName) {

public String displayName() {

public void changeDisplayName(String displayName) {

private AnnotationUseDemo() {

public static void main(String[] args) throws ReflectiveOperationException {

private static String runHandler(RequestHandler handler, String name) {

private static void printClassAnnotations(Class<?> type) {

private static void printInheritedAnnotation() {

private static void printMethodAnnotations(Method method) {

private static void printRepeatableAnnotations(Class<?> type) {

private static void printRetentionVisibility() {

private static void printTypeUseAnnotation() throws ReflectiveOperationException {

private static void printDecoratorStyleAnnotation() throws ReflectiveOperationException {

private static void printGetterSetterStyleAnnotations() throws ReflectiveOperationException {

private static void printPackageAnnotation() {

private static void printRecordComponentAnnotation() {

private static void printTypeParameterAnnotation() {

private static void printConstructorProperties() throws ReflectiveOperationException {

private static void printSourceOnlyMarkers() {

private AnnotationUtilities() {

public static <T> List<T> flatten(List<T>... lists) {

public static List<String> rawListDemo() {

public static String oldEndpoint() {

public String createUser(@NonBlank String name) {

String value();

public BeanPoint(int x, int y) {

public int x() {

public int y() {

public String charge(String accountId, int cents) {

public String handle(String name) {

String value();

private NativeConstantExample() {

String value();

String value();

String handle(String name);

private RetentionExamples() {

String value();

Role[] value();

String method();

String path();

public SerializableToken(String value) {

private Object readResolve() {

public String value() {

public TypedRepository(Class<T> entityType) {

public Class<T> entityType() {

String value();

private AnnotationExplorer() {

public static List<String> annotationSimpleNames(Class<?> type) {

public static String endpointSummary(Class<?> type, String methodName) {

public static List<String> permissionValues(Class<?> type) {

public static Optional<String> inheritedRuntimeCheck(Class<?> type) {

public static List<String> typeUseHintsOnFirstParameter(Class<?> type, String methodName) {

public static String deprecatedSummary(Method method) {

public static Optional<String> decoratorName(Class<?> type, String methodName) {

public static boolean hasGetterSetterMetadata(Class<?> type, String fieldName) {

public static Optional<String> packageMarkerValue(Package targetPackage) {

public static Optional<String> recordComponentColumn(Class<?> recordType, String componentName) {

public static List<String> typeParameterTags(Class<?> type) {

private AnswerVerifier() {

public static void main(String[] args) throws NoSuchMethodException {

private static void expectEquals(Object expected, Object actual, String label) {

public String save(String value) {

String value();

String method();

String path();

private ExerciseRunner() {

public static void main(String[] args) throws NoSuchMethodException {

private LegacyApi() {

public static String oldName() {

String value();

String value();

Permission[] value();

public Profile(String nickname) {

public String nickname() {

public void changeNickname(String nickname) {

String value();

String value();

String value();

String value();

public String findUser(@TypeHint("external-id") String id) {

private AnnotationExplorer() {

public static List<String> annotationSimpleNames(Class<?> type) {

public static String endpointSummary(Class<?> type, String methodName) {

public static List<String> permissionValues(Class<?> type) {

public static Optional<String> inheritedRuntimeCheck(Class<?> type) {

public static List<String> typeUseHintsOnFirstParameter(Class<?> type, String methodName) {

public static String deprecatedSummary(Method method) {

public static Optional<String> decoratorName(Class<?> type, String methodName) {

public static boolean hasGetterSetterMetadata(Class<?> type, String fieldName) {

public static Optional<String> packageMarkerValue(Package targetPackage) {

public static Optional<String> recordComponentColumn(Class<?> recordType, String componentName) {

public static List<String> typeParameterTags(Class<?> type) {