Ugrás a tartalomhoz

Java annotációk

A Wikipédiából, a szabad enciklopédiából
A lap korábbi változatát látod, amilyen 213.181.197.226 (vitalap) 2012. szeptember 12., 11:14-kor történt szerkesztése után volt. Ez a változat jelentősen eltérhet az aktuális változattól.

A Java programozási nyelvben annotációnak olyan nyelvi elemet nevezünk, amely lehetővé teszi a metaadatok beépülését egy forrásszövegbe. Ezt a Java 5.0-ás verziójá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ó processzor egy olyan fordító program 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. Azok az annotációk, amelyeknél ezt figyelembe vették, futási időben is kielemezhetők a reflekszió segítségével.

Az annotációt többek között a Java EE környezetben is használják, hogy osztályokat olyan információkkal bővíthessenek, amelyeket a Java 5-ös verziója 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 metaadatok speciális Javadoc kommentekkel is beépíthetőek a forráskódba. Ezek úgynevezett Docletek segítségével értékelhetőek ki. A leggyakrabban használt ilyen eszköz 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 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 fordító program 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 fordító program 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();
}

amelynél a személyt felsorolási típusként (enum) vagy annotációként kell definiá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 bájtkódba 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 mint 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árójeleket: 

@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 bájkódjá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 dobó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-deklaráció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

Forrás

A lap eredeti címe: „https://hu.wikipedia.org/w/index.php?title=Java_annotációk&oldid=12313185”