Adnotacje w Javie

W Javie 1.5 zostały wprowadzone adnotacje. Możemy je często spotkać przy pisaniu testów jednostkowych, ORMach lub różnych frameworkach. Czym są właściwie adnotacje i co nam dają?

Adnotacje są to metadate, które dostarczają nam informacji na temat programu, ale same nie są częścią kodu, ani bezpośrednio nie wpływają na kod.

Najprostszą adnotacje możemy stworzyć w następujący sposób:

public @interface MyAnnotation {
}

Teraz możemy użyć jej w naszym kodzie:

@MyAnnotation
public class MyClass {
}

Pola

Do naszych adnotacji możemy dodawać pola. Aby to zrobić musimy je zdefiniować w ciele naszej adnotacji.

public @interface MyAnnotation {
	String name();
}

I samo użycie:

@MyAnnotation(name = "My name")
public class MyClass {
}

Jeżeli nasze pole będzie miał nazwę value, wtedy możemy pominąć nazwę pola w użyciu adnotacji.

public @interface MyAnnotation {
	String value();
}

@MyAnnotation("My name")
public class MyClass {
}

Domyślne wartości pól

W przykładach powyżej podanie wartości zdefiniowanych pól jest obowiązkowe. Jeżeli chcemy, aby podanie pola nie było wymagane musimy zdefiniować jego domyślną wartość.

public @interface MyAnnotation {
	String name() default "My default name";
}

Wtedy przy użyciu adnotacji możemy, ale nie musimy, podawać wartość pola.

Zakres adnotacji

Adnotacje domyślnie mogą być używane na:

• innych adnotacjach
• konstruktorach
• metodach
• polach
• lokalnych zmiennych
• pakietach
• parametrach metod
• klasach, interfejsach, enumach
• typach generycznych (od Java 8)

Domyślnie nowo stworzona adnotacja może być używana w każdym z  wymienionych wcześniej miejsc. Możemy jednak ograniczyć jej zasięg poprzez użycie adnotacji @Target z parametrami definiującymi zasięg.

@Target({ElementType.FIELD})
public @interface MyAnnotation {
	String name() default "My default name";
}

Wszystkie dostępne wartości ElementType to:

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

Kolejne wymienione wartości ElementType odpowiadają wcześniej wymienionym miejscom opisującym gdzie można użyć adnotacji.

Dodatkowo w Javie 8 wprowadzono ElementType.TYPE_USE, który może być użyty na wszystkich typach.

Retencja adnotacji

Dla każdej adnotacji możemy ustalić jej zakres widoczności. Definiujemy to przez dodanie adnotacji @Retention.

@Retention(RetentionPolicy.CLASS)
public @interface MyAnnotation {
}

Dostępne są trzy wartości dla adnotacji @Retention:

• RetentionPolicy.SOURCE – informacja o adnotacji jest dostępna jedynie podczas kompilacji; przykładami takich adnotacji są @Override i @SuppressWarnings
• RetentionPolicy.CLASS – adnotacja jest dostępna podczas ładowania klas; jest to domyślny poziom retencji
• RetentionPolicy.RUNTIME – adnotacja jest dostępna podczas działania aplikacji, dzięki czemu mamy do niej dostęp poprzez refleksje; przykładem takiej adnotacji jest @Deprecated

Krótkie podsumowanie

W wpisie przedstawiłem najważniejsze informacje na temat adnotacji w Javie. Mam nadzieję, że okażą się one przydatne i choć trochę ułatwią poruszanie się po frameworkach, które pełne są najróżniejszych adnotacji 🙂