Java annotációk

Annotáció java

A Java programozó nyelvben annotációnak olyan nyelvi elemet nevezünk, amely lehetővé teszi a meta adatatok beépülését egy forrásszövegbe. Ezt a Java 5.0-ás verziónál vezették be. Az annotációk programszöveg elemeihez rendelhetők (csomagokhoz, típusokhoz, metódusokhoz, attribútumokhoz, konstruktorokhoz, lokális változókhoz). Plusz információt hordoznak a Java fordító vagy valamilyen speciális eszközök számára.

Az annotáció @ jellel kezdődik, majd ehhez kapcsolódik a neve. Esetenként vesszővel elválasztva követheti a nevet egy paraméterlista, amelyet kerek zárójelbe foglalunk. Például a következő forrásszöveg részletében az annotáció megelőzi az A osztályt (deprecated):

@Deprecated public class A {}

Az annotáció processor egy olyan Compiler-Plugin, amely az annotációt a fordításnál kielemzi, és ezzel figyelmeztetéseket és hibajelentéseket nyomhat el illetve válthat ki, vagy további forráskódokat vagy más adatokat generálhat. Viszont annotációval ellátott kódokat nem tud megváltoztatni. Olyan annotációknál ahol ezt figyelembe vették, futási idő közben is kielemezhetők a reflekszió segítségével.

Az annotáció többek között a Java-EE környezetben is felhasználják, hogy osztályokat olyan információkkal bővíthessenek, amelyeket a Java 5-ös verziók előtt külön kellett feltüntetni. Fontos példák erre például a Home- és Local interfészek, valamint a Deployment-Descriptorok

A metaadatokat a forráskódba speciális Javadoc kommentárokkal is beépíthetőek. Ezeket úgynevezett Doclets-ek segítségével értékelhetőek ki. Ennek a módszernek a leggyakrabban használt eszköze az XDoclet. Ezt a módszert az annotáció bevezetése után (továbbra) is lehet alkalmazni.

Előre definiált annotációfajták

A Java SE 5.0-ban 7 előre definiált annotáció típus létezik, a java.lang vagy java.lang.annotation –ban találhatóak. Mindegyik (ellentétben a legtöbb annotációval) fordítással értékelhető ki. Továbbiakat magunk hozhatunk létre.

Az java.lang csomagban található annotációk:

1. @Deprecated

Olyan osztályokat, attribútumokat vagy metódusokat lehet vele ellátni, amelyeket nem szabad felhasználni. Ha egy ilyen elem kerül használatba, akkor a Compiler küld egy figyelmeztetést.

Ajánlott egy plusz Javadoc kommentár elhelyezése, ami feltünteti, hogy az adott elemet milyen módon lehet helyettesíteni. Példa:

/**
 * @deprecated  Az A osztály használatát a 10.3-as verziótól az Anew   osztály váltotta ki.
 */
@Deprecated
public class A {}

2. @ Override

Ezzel a módszerrel egy olyan metódust jelzünk, amely a metódus ősosztályát írja felül. Ebben az esetben a compiler biztosítja, hogy az ősosztály tartalmazza ezt a metódust, vagy ha mégsem akkor hibajelzést küld. Pl:

public class A {
    public void method() {}
}
 
public class B extends A {
    @Override
    public void method() {}
}

3. @SuppressWarnings

Ennél az annotációfajtánál a compiler bizonyos hibaüzeneteket/figyelmeztetéseket tilt le. Az annotáció ehhez egy Arrayt Stringekkel együtt ad le, amelyek tartalmazzák a letiltandó figyelmeztetéseket. Pl:

public class A {
    @SuppressWarnings({"deprecation"})
    public void method() {
        DeprecatedClass b = new DeprecatedClass();
    }
}

A java.lang.annotation csomagban található annotációk. (Ezeket csak az annotáció definiálására használjuk):

1. @Documented

Ezt az annotáció típust meta-annotációként alkalmazzuk: Ez a típusú annotáció biztosítja az újonnan létrehozott annotációknál, hogy a javadoc dokumentáció létrehozásánál figyelembe legyenek véve.

2. @Inherited

Egy annotáció annotálására alkalmazzák. Ezzel biztosíthatjuk, hogy a saját annotációnkat egy adott osztály örökölje. Ez az öröklődés kiterjed az alosztályokra is.

3. @Retention

Ezt a típust is az annotáció annotálására alkalmazzák. Megadja hogy mikor hivatkozhat önmagára. 3 lehetséges értéke lehet, amelyek a java.lang.annotation.retentionPolicy enumerációjában jelennek meg. A 3 lehetséges érték: Class, Runtime illetve Source

4. @Target

Ezt is az annotációk annotálására használják. Megmutatja hogy a program mely elemeire alkalmazható. Az annotáció értékei a java.lang.annotation.ElementType enumerációban érhető el.

• Type: Csak osztályokra, interfészekre vagy enumerációkra alkalmazható.

• Method: Csak metódusokra alkalmazható

• Annotation_Type: Csak annotációkra alkalmazható.

Saját annotáció definiálása

Az annotációk speciális kapcsolódási pontok, ezért a nevüket nagybetűvel írjuk. A specifikáció alapján az interface előtt @ jel áll. Implicit bővítik a java.lang.annotation.Annotation kapcsolódási pontjait. Más kapcsolódási pontot nem bővíthetnek (vagyis tiltott az extends), és nem generikusak. A metódusaik paraméter nélküliek és nem generikusak. Visszatérési típusként (return type) csak a következő típusok megengedettek:

• primitív típusok
• felsorolási típusok
• annotáció típusok
• string
• class
• felsorolások (arrays) ezekből a típusokból

Nem dobhatnak kivételt, és nem lehetnek rekurzívak. Sok annotáció nem tartalmaz metódusokat.

@interface Template { }

Más annotációk (ahogy más kapcsolódási pontoknál jellemző) metódusokat tartalmaznak, de csak az előbb felsorolt visszatérési típusokat. Ha egy annotáció csak egy mezőt tartalmaz, akkor neve a konvencióknak megfelelően value

@interface Test {
        boolean value();
}

vagy

@interface Author {
        String[] value(); // szerző neve
}

vagy

@interface Costumer {
        Person[] value();
}

aminél személyt felsorolási típusként (enum) vagy annotációként kell difiniálni. Pl:

@interface Person {
        String name();
        int age();
}

Az annotációk konvencióinál gyakran a java.lang.annotation csomagból választják ki a standard annotációkat. Különösen a @Retention-nal kell feltüntetni, hogy meddig tartsák meg az annotációkat: csak a forrásszövegben (source), a tárolt class-adatoknál (class) vagy a betöltött osztályoknál (runtime). @Target jelzi, hogy melyik programelemeknél használhatóak az annotációk. Például az összes java.lang.annotation csomagban található annotáció a

@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)

annotációkkal van ellátva. Ezek a Bytecode-ban betölthetők, és futási idő alatt kiértékelhetőek, továbbiakban csak annotáció típusokként használhatóak.

Saját annotációk felhasználása

Egy metódus annotáció nélkül mit pl a @Template, egy osztály elé állítható:

@Template
class SampleClass {
        void sampleMethod(); 
}

Ha az eredménytípus felsorolás, akkor felsorolási literálokat kell alkalmazni:

@Author({"Szerző 1", "Szerző 2"})
String book = "Könyv"

Ha a felsorolás nem tartalmaz elemeket akkor ({}) jellel kell jelezni. De a csak egy elemet tartalmaz, akkor elhagyhatjuk a belső zárojeleket:

@Author("Szerző")
String anotherBook = "Könyv"

Ha egy annotáció több metódussal rendelkezik, akkor mindegyiknél zárójelben hozzá kell rendelni egy konstans értéket:

@Person(name = "Név", age = 30)
Bill bill = new Bill();

Az annotációknál is van egy módszer, amelyekkel az értéket a névnél meg lehet adni (felesleges, csak olvashatóbb)

@Test(value = true)

Egy komplex annotációt egymásba ágyazva kell alkalmazni.

@Costumer(@Person(name = "Név", age = 30))
class Company { … }

Az annotációknál a metódusoknak kezdőértékeket határozhatunk meg, ekkor felhasználásnál elhagyhatjuk a megfelelő értékek megadását. Mivel az annotációk kapcsolódási pontok, ezért önmaguk annotációval is megjelölhetőek.

@Author("Szerző")
public @interface Test {
        boolean buy() default false; // érték nélkül is hívható 
}

Annotációk kiértékelése

Ha az annotáció az osztály Bytecodejának segítségével betölthető, akkor a reflekszió segítségével kiértékelhető. Például megállapítható, hogy egy annotációt megadtak –e vagy sem.

boolean template = SampleClass.class.isAnnotationPresent(Template.class);

Megállapítottuk az annotáció jelenlétét, akkor az értéke is olvasható, pl. hogy a metódus még a tesztelés folyamatában van vagy nem.

boolean isTesting = Template.class.getMethod ( „method”, new Class [ ] {}).

Ha az annotáció nem található, akkor a getAnnotation() által NullPointerException aktiválódik. Egy komplex annotációnál az elemeit egyesével kell kiválasztani.

Person costumer = Company.class.getAnnotation(Costumer.class)[0];

Csomagok annotációja

A Java Language Specification engedélyezi a csomagok annotációját, például egy csomag dokumentációjának az előkészítéséhez. Csomagonként maximum egy package-Deklaraciót használhatunk fel egy annotációval. Ha egy csomag annotációt kapna akkor a Java Language Specifikációt, ajánl egy elkülönített package-info.java adatot, melyet a csomag jegyzékében ajánlott elhelyezni. Ez az adat tartalmazza a package-Deklarációt az annotációval együtt.

További példák

• További példák (angol)

Forrás

• Annotations in Suns Java-Tutorial (angol)
• Annotation Processing Tool (apt) (angol)
• The J2SE 5.0 Annotations Feature bei Sun (angol)
• JSR 175: A Metadata Facility for the JavaTM Programming Language (angol)
• Annotations Java Language Specification (angol)