What is the purpose of annotations in Java?

Annotations are just metadata. On their own they serve little to no purpose. There must be an annotation processor, either at the compiler or run time level that uses them for something.

With an annotation like

@Author(
   name = "Benjamin Franklin",
   date = "3/27/2003"
)

for example, some annotation processor might read it with reflection at run time and create some log file that this author wrote whatever it's annotating on that date.

Annotations are metadata. @Override annotation is used to make sure that you are overriding method of a superclass and not just making a method with the same name. Common mistakes here consist of:

• spelling the method's name wrong equal(Object o) instead of equals(Object o)

• putting different set of arguments

  MyString extends String { public boolean equals(MyString str) {} }

equals(MyString str) is not overriding the method equals(Object o) and therefore will not be used by standard Java comparators (which is used in some standard functions, such as List.contains() and this is prone to error situation). This annotation helps compiler to ensure that you code everything correctly and in this way it helps program.

@Deprecated annotation doesn't make program not to compile but it makes developers think about using the code that can and/or will be removed in a future releases. So they (developers) would think about moving onto another (updated) set of functions. And if you compile your program with the flag -Xlint compilation process will return with an error unless you remove all usages of deprecated code or explicitly mark them with annotation @SuppressWarnings("deprecation").

@SuppressWarnings is used to suppress warnings (yes, I know it's Captain Obvious style :)). There is a deprecation suppression with @SuppressWarnings("deprecation"), unsafe type casting with @SuppressWarnings("unchecked") and some others. This is helpfull when your project compiler have a compilation flag -Xlint and you cannot (or don't want to) change that.

There are also annotation processors that you integrate into your program build process to ensure that program code meets some sort of criteria. For example with IntelliJ Idea IDE annotation processor you can use @Nullable and @NotNull annotations. They show other programmers when they use your code so that can transfer null as a certain parameter to a method or not. If they transfer null it will cause exception during compilation or before executing a single line method's code.

So annotations are quite helpful if you use them to their full potential.

Annotations are most likely used by other programs. Examples include:

@Override IDE (compiler?) ensures that the signatures match

@Deprecated IDE marks occurences, compiler warning

@FXML JavaFX can use these annotations initialize variables in a controller class when an .fxml File is inflated (see http://docs.oracle.com/javafx/2/get_started/fxml_tutorial.htm). They are also used by JavaFX Scene Builder.

Annotations works as a way to marking up the code. Several frameworks uses it, and some others make a great use of it producing your own.

Besides, is important to understand that annotations are the equivalent to meta-data, but is much more than that, since it works as a tag language for the code.

Java @Annotation

@Annotation(from Java 5) adds a metadata which are used for instruction in compile, deployment and run time. It is defined by RetentionPolicy

RetentionPolicy defines a lifetime

• RetentionPolicy.SOURCE: It is visible only in compile time(@Override, @SuppressWarnings, @StringDef). For example it can be used by apt to generate some code
• RetentionPolicy.CLASS: It is visible in compile and deployment time(.class). For example it can be used by ASM or Java AOP paradigm like AspectJ
• RetentionPolicy.RUNTIME: It is visible in deployment and run time. For example it can be used java reflection using getAnnotations(). Dagger 2 uses @Scope annotation

Create a custom Annotation

@Retention(<retention_policy>) //optional
@Target(<element_type>) //optional to specify Java element like, field, method...
@Inherited // optional will be visible by subclass 
@Documented // optional will be visible by JavaDoc
@interface MyAnnotation {
    //attributes:
    String someName();
}

using

@MyAnnotation(someName = "Alex")
public class SomeClass {
}