Java Annotation API

An annotation is metadata attached to program elements like classes, methods, fields, and parameters.

No: It only provides metadata; behavior changes when tools/frameworks process it.

java.lang.annotation.

Defining custom annotations and controlling how/where they are applied and retained.

An annotation with no elements, e.g. @Override-style metadata marker.

Annotation with one commonly used element, often named value.

Annotation with multiple elements (attributes).

A method declared inside annotation type, representing metadata property.

Use @interface syntax.

```java public @interface Auditable {} ```

A fallback value declared with default keyword.

No, annotation elements cannot be null.

Primitives, String, Class, enum, annotation, and one-dimensional arrays of these.

No, only allowed Java annotation element types are supported.

Meta-annotation restricting where an annotation can be used.

• TYPE
• FIELD
• METHOD
• PARAMETER
• CONSTRUCTOR
• LOCAL_VARIABLE
• ANNOTATION_TYPE
• PACKAGE
• TYPE_USE
• TYPE_PARAMETER

Meta-annotation defining how long annotation metadata is kept.

• SOURCE
• CLASS
• RUNTIME

Annotation exists only in source code; removed by compiler.

Stored in bytecode but not necessarily available at runtime reflection.

Available in bytecode and visible through reflection at runtime.

Indicates annotation should appear in generated Javadoc.

Class-level annotation inheritance marker for subclasses.

No, only to class-level annotations.

Allows applying same annotation type multiple times to one element.

To attach multiple values without manual container annotation usage in source.

Annotation type that holds an array of repeatable annotation instances.

Yes, with proper @Target including CONSTRUCTOR.

Yes, if PARAMETER is included in target.

Yes, with TYPE_USE target.

@Override, @Deprecated, @SuppressWarnings.

Compiler checks method actually overrides a superclass/interface method.

Element is discouraged and may be removed in future.

Suppresses selected compiler warnings in annotated scope.

Yes.

Yes; use fully qualified names or imports to disambiguate.

Yes, interfaces are TYPE elements.

Yes.

Yes, via ANNOTATION_TYPE target.

An annotation that annotates another annotation type.

No, annotation elements are parameterless methods.

No.

No, they are special abstract-like declarations with optional defaults.

Using reflection APIs like getAnnotation().

Runtime reflection may not see the annotation.

Yes, defaults affect API usability and backward compatibility.

No, values must be compile-time constants (or class literals/enums/arrays thereof).

Only if they are compile-time constants.

Sometimes, but external config may still be better for environment-specific values.

Marking methods/classes for framework scanning and behavior toggles.

Only class-level and only with @Inherited.

No.

Forgetting to set @Retention(RetentionPolicy.RUNTIME) when runtime processing is needed.

Using wrong @Target and then being unable to place annotation where intended.

Define minimal, clear annotation contracts with explicit target and retention.

As proxy instances implementing annotation interfaces.

Logical equality by annotation type and element values.

Defined by JLS based on element names and values.

Use getAnnotations() or declared variants.

Declared returns directly present only; non-declared may include inherited class-level ones.

Use getAnnotationsByType(YourAnnotation.class).

Behavior may not give all entries; prefer getAnnotationsByType.

Compile-time processing of annotations to validate/generate code/resources.

javax.annotation.processing and related language model packages.

A compiler plugin that reacts to annotations during compilation rounds.

Convenience base class for implementing processors.

Receives annotated elements each round for validation/code generation.

Compiler may invoke processors multiple times as new sources are generated.

Override methods or use @SupportedAnnotationTypes.

Use @SupportedSourceVersion or override method.

Utility to create source/class/resource files during compilation.

Utility for compile-time notes/warnings/errors.

Compilation fails.

Better performance and earlier feedback with compile-time guarantees.

Boilerplate code, registries, mappers, metadata files.

Compiler representation of program structure (Element, TypeElement, etc.).

Compile-time type abstraction (TypeMirror) used by processors.

Reflection is runtime; TypeMirror is compile-time model.

Processor behavior optimized to reprocess only affected sources.

Faster builds in large projects.

Aggregating depends on many inputs globally; isolating maps output to specific input elements.

No, they generate new files; they do not edit existing source directly.

Generated code is compiled with project sources in same build.

Duplicate file generation, missing originating elements, unstable outputs.

Input element reference for better incremental tracking/tooling.

Yes, annotation element type can itself be another annotation.

Yes, via Class<?>-typed elements.

May trigger class loading unexpectedly when read.

When annotation references class not present at runtime.

Classpath/module scanning, reflection, and metadata indexes.

Large classpaths and repeated reflective lookups.

Limit scan packages, cache metadata, precompute indexes.

Custom annotation meta-annotated with other annotations to bundle semantics.

Reduces duplication and enforces consistent policy.

Mapping one annotation attribute to another for ergonomic configuration.

Large unstable APIs are hard to version and maintain.

Removing/renaming elements can break clients at compile/runtime.

Only if it has a default value; otherwise existing usages break.

Yes, but migration guidance is needed.

Nullability annotations on any type usage location.

Annotating generic type parameter declaration itself.

Validation, DI qualifiers, web request binding metadata.

Transactions, caching, security, retries, metrics, routing.

Component registration, configuration roles, serialization rules.

ORM mapping, injection, validation constraints.

Namespace-wide metadata in package-info.java.

Framework expects runtime annotation but annotation retained only SOURCE/CLASS.

Document processing mode and enforce tests.

Interceptors trigger behavior based on annotation presence.

Self-invocation and final/private method limitations (framework-dependent).

Frameworks may search meta-hierarchies differently; behavior is framework-specific.

Ambiguous semantics produce fragile and surprising behavior.

Use annotation processors emitting compile errors.

Startup checks scanning required constraints and failing fast.

Overusing many overlapping annotations causing complexity and unreadability.

Prefer cohesive composed annotations and sensible defaults.

Generally no; external config is better for frequently changing values.

Yes, test frameworks heavily use them (lifecycle, parameterization, tagging).

Clear contract, explicit retention/target, validation tooling, and minimal surface area.

Design annotation APIs like public APIs: versioned, documented, and backward compatible.

Lookup and proxy creation add overhead; caching metadata is important in hot paths.

Cache per class/method with invalidation tied to classloader lifecycle.

Strong references to classes/annotations can prevent unloading.

Use weak references and scoped caches.

Framework-generated merged view of annotations (direct, meta, aliases, inherited rules).

Must resolve precedence, alias conflicts, repeatables, and merged defaults.

Traversal strategy across element, hierarchy, interfaces, meta-annotations.

Ensures predictable behavior across versions and environments.

Stored via container annotation unless runtime API expands them.

Mixing direct container usage and repeatable syntax inconsistently.

Module boundaries can limit reflective access to non-open packages.

Use module descriptors with opens where deep reflection is required.

exports is not enough for deep reflection; opens is typically needed.

Reflection/scanning may require explicit metadata hints/configuration.

Shifts work to build time, reducing runtime reflection overhead.

Precomputing annotated element maps to avoid classpath scans at startup.

Tests that verify annotations produce intended framework behavior.

Annotation name remains but behavior changes subtly over time.

Strict docs, versioning policy, deprecation path, regression tests.

Annotations may enable privileged behavior if placed/processed improperly.

Validate allowed targets, restrict dangerous attributes, enforce policy checks.

No; avoid untrusted dynamic class resolution paths.

Annotations declare intent while central engine enforces allowed operations.

Safe, least-privilege defaults with explicit opt-in for risky features.

Too many annotation-triggered interceptors causing hidden control flow.

Ordering rules, explicit composition, diagnostics, and architectural boundaries.

Startup reports listing discovered annotations, resolved handlers, and conflicts.

Rules for handling mutually exclusive or overlapping annotations.

Fail fast at startup with actionable error messages.

Add new attributes with defaults; avoid removal; deprecate gradually.

Static analyzers/rewriters and compile-time warnings with autofix guides.

Deeply nested composed annotations that obscure effective behavior.

Keep shallow and readable; document effective merged settings.

Using annotations to declaratively configure framework behavior.

When configuration is highly dynamic or environment-specific.

Interoperability mostly works, but nullability/use-site targets may differ.

Annotation placement on field/getter/param may differ by language syntax.

Document target expectations and test across language compilers.

Org-wide standards for naming, retention, targets, and review policies.

They encode conventions/policies across many services.

Use compile-time for structural rules, runtime for environment/context checks.

Index metadata, lazy-init noncritical paths, reduce scan scope.

Multiple annotations/interceptors require stable order guarantees.

Use order attributes or external precedence rules.

Narrowing targets can break existing usages.

Yes, it may allow unintended placements and ambiguous processing semantics.

Small, explicit, validated, composable annotations with predictable behavior.

Using annotations as hidden imperative code rather than clear declarative metadata.

When existing configuration/mechanism can express intent more simply.

Optimize for clarity, determinism, and long-term maintainability over cleverness.