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.
@Override public String toString() { return "..."; } @FunctionalInterface interface Parser<T> { T parse(String text); }
Try it
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.
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 astostring()or a wrong parameter type silently creates a new method instead of an override. @Overrideis also valid on methods that implement an interface method and on record accessor methods you declare yourself.@FunctionalInterfaceis 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
@SuppressWarningson 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. @SafeVarargsis 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,@Testor@Injectcome from libraries and are read by their tools.