Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Language Features by Version

Built-in Java annotations

Reference for Java's built-in annotations: @Override, @Deprecated, @SuppressWarnings, @SafeVarargs and @FunctionalInterface, with retention and what the compiler checks.

An annotation is metadata attached to a declaration, written with @. Annotations do nothing by themselves: a tool (the compiler, a build plugin, a framework reading them at run time) decides what they mean. Java ships with a handful of annotations in java.lang that the compiler understands and enforces; they turn common mistakes into compile errors or silence warnings you have already considered.

The five you will meet constantly are @Override, @Deprecated, @SuppressWarnings, @SafeVarargs and @FunctionalInterface. The annotations used to define other annotations (@Retention, @Target, @Repeatable, @Documented, @Inherited) are covered in custom annotations.

Java
@Override
public String toString() { return "..."; }

@FunctionalInterface
interface Parser<T> { T parse(String text); }

Try it

Java Using the built-in annotations

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Which annotations survive until run time?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The annotations

Annotation Target Retention Effect
@Override Methods Source Compile error if the method does not override or implement a supertype method.
@Deprecated(since, forRemoval) Most declarations Runtime Marks an API as discouraged; callers get warnings.
@SuppressWarnings({"..."}) Most declarations, variables Source Silences the named compiler warnings in that scope.
@SafeVarargs Constructors, static/final/private methods (and since 9 private instance methods) Runtime Promises a generic varargs method does not misuse its array, removing the heap-pollution warning at the declaration and at call sites.
@FunctionalInterface Interfaces Runtime Compile error unless the interface has exactly one abstract method (not counting Object's public methods).

Common @SuppressWarnings names

"unchecked" (unchecked generic operations), "rawtypes" (raw types), "deprecation" (use of deprecated APIs), "removal" (use of APIs deprecated for removal), "unused" (supported by many IDEs and by javac for some cases), "serial" and "fallthrough". Unknown names are ignored. Several can be given as @SuppressWarnings({"unchecked", "rawtypes"}).

Usage notes

  • Always write @Override. Without it, a typo such as tostring() or a wrong parameter type silently creates a new method instead of an override.
  • @Override is also valid on methods that implement an interface method and on record accessor methods you declare yourself.
  • @FunctionalInterface is optional: any interface with a single abstract method works as a lambda target. The annotation just documents the intent and protects it from a second abstract method being added later.
  • Put @SuppressWarnings on the smallest scope you can: a variable declaration beats a method, and a method beats a class. Add a comment saying why it is safe.
  • @SafeVarargs is a promise by you: do not store the array into a shared place or let it escape. Use it only when that is true.
  • Source-retention annotations (@Override, @SuppressWarnings) vanish after compilation, so reflection never sees them, as the second example shows.
  • Non-JDK annotations such as @Nullable, @NonNull, @Test or @Inject come from libraries and are read by their tools.