Java – Annotations Anotace v Javě Martin Majliš

Cíl Spojit dodatečnou informaci s elementem programu Snadnější údržba Kód se dá generovat Kontrola chyb Mnohá API potřebují dodatečné soubory (Spring, hibernate, EJB 3, Seam, JAX-RPC)

Spojit dodatečnou informaci s elementem programu

Snadnější údržba

Kód se dá generovat

Kontrola chyb

Mnohá API potřebují dodatečné soubory (Spring, hibernate, EJB 3, Seam, JAX-RPC)

Ukázka class A { @Override public boolean equals ( A a ) { ... } @Deprecated public void myDeprecatedMethod () { ... } } Kompilátor: ”method does not override or implement a method from a supertype” Kompilátor: "The method myDeprecatedMethod() from the type A is deprecated."

Kompilátor: ”method does not override or implement a method from a supertype”

Kompilátor: "The method myDeprecatedMethod() from the type A is deprecated."

Historie JSR-175 Představeno: 1. 4. 2002 Finální verze: 30. 9. 2004 http://www.jcp.org/en/jsr/detail?id=175 Poprvé v JDK 1.5 Provizorní rozhraní pro apt v JDK 1.5 JSR-269 – formalizováno, integrováno do 1.6

JSR-175

Představeno: 1. 4. 2002

Finální verze: 30. 9. 2004

http://www.jcp.org/en/jsr/detail?id=175

Poprvé v JDK 1.5

Provizorní rozhraní pro apt v JDK 1.5

JSR-269 – formalizováno, integrováno do 1.6

Deklarace – příklad - 1 public @ interface Foo { } public @ interface RequestForEnhancement { int id (); String synopsis (); String engineer () default "[unassigned]" ; String date () default "[unimplemented]" ; }

Deklarace – gramatika – 1 AnnotationTypeDeclaration : InterfaceModifiers @ interface Identifier AnnotationTypeBody AnnotationTypeBody : { AnnotationTypeElementDeclarations } AnnotationTypeElementDeclarations : AnnotationTypeElementDeclaration AnnotationTypeElementDeclarations AnnotationTypeElementDeclaration

Deklarace – gramatika – 2 AnnotationTypeElementDeclaration : AbstractMethodModifiers Type Identifier ( ) DefaultValue ; ConstantDeclaration ClassDeclaration InterfaceDeclaration EnumDeclaration AnnotationTypeDeclaration ; DefaultValue : default ElementValue

Deklarace – vlastnosti – 1 Stejné jako interface Místo deklarace Rozsah platnosti Rozsah viditelnosti Nesmí být generickým typem Nesmí obsahovat extends (implicitně dědí od annotation.Annotation) Libovolný počet elementů (0..*)

Stejné jako interface

Místo deklarace

Rozsah platnosti

Rozsah viditelnosti

Nesmí být generickým typem

Nesmí obsahovat extends (implicitně dědí od annotation.Annotation)

Libovolný počet elementů (0..*)

Deklarace – vlastnosti – 2 Nesmí se používat zděděné vlastnosti Elementy můžou mít defaultní hodnotu Defaultní hodnota je z doby přečtení (ne kompilace) Anotace T nesmí obsahovat element typu T (přímo i nepřímo) @ interface SelfRef { SelfRef value (); } @ interface Ping { Pong value (); } @ interface Pong { Ping value (); }

Nesmí se používat zděděné vlastnosti

Elementy můžou mít defaultní hodnotu

Defaultní hodnota je z doby přečtení (ne kompilace)

Anotace T nesmí obsahovat element typu T (přímo i nepřímo)

@ interface SelfRef { SelfRef value (); }

@ interface Ping { Pong value (); }

@ interface Pong { Ping value (); }

Deklarace – vlastnosti – 3 Přímým předkem je vždy annotation.Annotation Metody nesmí mít žádné parametry Metody nesmí mít žádné typové parametry ( <T extends Annotation> T getAnnotation(Class<T> annotationType); ) Deklarace metod nesmí obsahovat throws

Přímým předkem je vždy annotation.Annotation

Metody nesmí mít žádné parametry

Metody nesmí mít žádné typové parametry ( <T extends Annotation> T getAnnotation(Class<T> annotationType); )

Deklarace metod nesmí obsahovat throws

Deklarace – vlastnosti – 4 Návratová hodnota musí být: Primitivní typ String Class Enum Anotace Pole předchozích typů @ interface Illegal { String [][] value (); }

Návratová hodnota musí být:

Primitivní typ

String

Class

Enum

Anotace

Pole předchozích typů

Deklarace – příklad – 2 public @ interface Name { String first (); String last (); } public @ interface Author { Name value (); }

Deklarace – příklad – 3 public @ interface Foo { } public @ interface RequestForEnhancement { int id (); String synopsis (); String engineer () default &quot;[unassigned]&quot; ; String date () default &quot;[unimplemented]&quot; ; }

Použití – příklad – 1 @ RequestForEnhancement ( id = 2868724 , synopsis = &quot;Provide time-travel functionality&quot; , engineer = &quot;Mr. Peabody&quot; , date = &quot;4/1/2004&quot; ) public void travelThroughTime ( Date destination ) { @Preliminary public class TimeTravel {

Použití – gramatika – 1 Annotations : Annotation Annotations Annotation Annotation : NormalAnnotation MarkerAnnotation SingleElementAnnotation

Použití – gramatika – 2 NormalAnnotation : @ TypeName ( ElementValuePairs ) ElementValuePairs : ElementValuePair ElementValuePairs , ElementValuePair ElementValuePair : Identifier = ElementValue

Použití – gramatika – 3 ElementValue : ConditionalExpression Annotation ElementValueArrayInitializer ElementValueArrayInitializer : { ElementValues } ElementValues : ElementValue ElementValues , ElementValue

Použití – gramatika – 4 MarkerAnnotation : @ TypeName SingleElementAnnotation : @ TypeName ( ElementValue )

Použití – vlastnosti – 1 Mezi @ a identifikátorem může být mezera Nesmí být 2 anotace stejného typu Musí obsahovat element-value pár pro každý element z použité anotace (defaultních ne) Může být na libovolném místě mezi modifikátory (konvence: na prvním místě)

Mezi @ a identifikátorem může být mezera

Nesmí být 2 anotace stejného typu

Musí obsahovat element-value pár pro každý element z použité anotace (defaultních ne)

Může být na libovolném místě mezi modifikátory (konvence: na prvním místě)

Použití – vlastnosti – 2 Může být použita jako modifikátor pro: Package Class Interface Člensku proměnnou Metodu Paramater metody Konstruktor Lokální proměnnou

Může být použita jako modifikátor pro:

Package

Class

Interface

Člensku proměnnou

Metodu

Paramater metody

Konstruktor

Lokální proměnnou

Použití – vlastnosti – 3 Hodnota nesmí být null Pokud je element pole a hodnota není ElementValueArrayInitializer, tak se použije jako jediný prvek pole

Hodnota nesmí být null

Pokud je element pole a hodnota není ElementValueArrayInitializer, tak se použije jako jediný prvek pole

Použití – příklad – 2 @ Author ( @ Name ( first = &quot;Joe&quot; , last = &quot;Hacker&quot; )) public class BitTwiddle { ... } @ Quality ( Quality . Level . GOOD ) public class Karma { ... } @ Copyright ( &quot;2002 Yoyodyne Systems, Inc., All rights reserved.&quot; ) public class OscillationOverthruster { ... }

Použití – příklad – 3 @ RequestForEnhancement ( id = 2868724 , synopsis = &quot;Provide time-travel functionality&quot; // , // engineer = &quot;Mr. Peabody&quot; , // date = &quot;4/1/2004&quot; ) public void travelThroughTime ( Date destination ) {

Předdefinované anotace Závislé na příslušném API Některé vyžadují speciální sémantiku Anotace, které potřebují speciální chování: Target Retentition Inherited Override SuppressWarnings

Závislé na příslušném API

Některé vyžadují speciální sémantiku

Anotace, které potřebují speciální chování:

Target

Retentition

Inherited

Override

SuppressWarnings

Target – 1 Specifikuje, k jakému typu elementu může být anotace připojena Přípustné hodnoty: ANNOTATION_TYPE - deklarace anotace CONSTRUCTOR - deklarace konstruktoru FIELD - deklarace člena třídy LOCAL_VARIABLE - deklarace lokální proměnné PACKAGE - deklarace balíku METHOD - deklarace metody

Specifikuje, k jakému typu elementu může být anotace připojena

Přípustné hodnoty:

ANNOTATION_TYPE - deklarace anotace

CONSTRUCTOR - deklarace konstruktoru

FIELD - deklarace člena třídy

LOCAL_VARIABLE - deklarace lokální proměnné

PACKAGE - deklarace balíku

METHOD - deklarace metody

Target – 2 Přípustné hodnoty: PARAMETER - deklarace parametru metody TYPE - deklarace typu (třída, rozhraní, anotace, výčtový typ) @ Target ( ElementType . TYPE ) public @ interface Foo { }

Přípustné hodnoty:

PARAMETER - deklarace parametru metody

TYPE - deklarace typu (třída, rozhraní, anotace, výčtový typ)

Retentition Specifikuje, kde a jak dlouho bude anotace dostupná Přípustné hodnoty: SOURCE – pouze ve zdrojovém kódu CLASS – v době kompilace, ignorována JVM RUNTIME – read-only pro JVM @ Retention ( RetentionPolicy.RUNTIME ) public @ interface Foo { }

Specifikuje, kde a jak dlouho bude anotace dostupná

Přípustné hodnoty:

SOURCE – pouze ve zdrojovém kódu

CLASS – v době kompilace, ignorována JVM

RUNTIME – read-only pro JVM

Inherited @ Retention ( RetentionPolicy . RUNTIME ) @ Target ( ElementType . ANNOTATION_TYPE ) public @ interface Inherited { } Takto oanotovana anotace se dědí Pouze pro anotace tříd a interfaců Ukazka: ExInherited

Takto oanotovana anotace se dědí

Pouze pro anotace tříd a interfaců

Ukazka: ExInherited

Override @ Retention ( RetentionPolicy . SOURCE ) @ Target ( ElementType . METHOD ) public @ interface Override { } Občas dojde k přetížení (overload) metedy, než k jejímu předefinování (override) Ukázka: ExOverride

Občas dojde k přetížení (overload) metedy, než k jejímu předefinování (override)

Ukázka: ExOverride

Override – příklad class A { @Override public boolean equals ( A a ) { return false ; } } Kompilátor: ”method does not override or implement a method from a supertype”

Kompilátor: ”method does not override or implement a method from a supertype”

SuppressWarnings @ Target ( { TYPE , FIELD , METHOD , PARAMETER , CONSTRUCTOR , LOCAL_VARIABLE } ) @ Retention ( RetentionPolicy . SOURCE ) public @ interface SuppressWarnings { String [] value (); } Poskytuje kompilátoru informaci, že má vypnout hlášení warningů Užitečné při kompilaci 1.4 kódu 5.0 kompilátorem

Poskytuje kompilátoru informaci, že má vypnout hlášení warningů

Užitečné při kompilaci 1.4 kódu 5.0 kompilátorem

SuppressWarnings – příklad @ SuppressWarnings ( &quot;unchecked&quot; ) public static List toList ( Object [] array ) { return Arrays . asList ( array ); } Kompilátor: &quot;List is a raw type. References to generic type List<E> should be parameterized&quot;.

Kompilátor: &quot;List is a raw type. References to generic type List<E> should be parameterized&quot;.

Deprecated @ Target ( ElementType . RUNTIME ) public @ interface Deprecated { } Upozorní na použití nevhodného elementu (nebezpečné, existuje lepší alternativa)

Upozorní na použití nevhodného elementu (nebezpečné, existuje lepší alternativa)

Deprecated – příklad public class Foo { @Deprecated public void myDeprecatedMethod () { ... } } Kompilátor: &quot;The method myDeprecatedMethod() from the type Foo is deprecated.&quot;

Kompilátor: &quot;The method myDeprecatedMethod() from the type Foo is deprecated.&quot;

Reference The Java language Specification, Third Edition ( http://java.sun.com/docs/books/jls/index.html ) JSR 175: A Metadata Facility for the JavaTM Programming Language ( http://www.jcp.org/en/jsr/detail?id=175 ) http://www.javabeat.net/articles/java-5-0/2007/08/annotations/

The Java language Specification, Third Edition ( http://java.sun.com/docs/books/jls/index.html )

JSR 175: A Metadata Facility for the JavaTM Programming Language ( http://www.jcp.org/en/jsr/detail?id=175 )

http://www.javabeat.net/articles/java-5-0/2007/08/annotations/

Otázky? Otázky?

Konec Děkuji za pozornost!