Java -Annotation

In dem Java Computer -Programmiersprache, ein Anmerkung ist eine Form der Syntaktik Metadaten Das kann Java hinzugefügt werden Quellcode.[1] Klassen, Methoden, Variablen, Parameter und Java -Pakete kann kommentiert werden. Wie Javadoc Tags, Java -Anmerkungen können aus Quelldateien gelesen werden. nicht wie Javadoc Tags, Java -Anmerkungen können auch eingebettet und gelesen werden Java -Klassendateien generiert von der Java Compiler. Dadurch können Anmerkungen von der beibehalten werden Java virtuelle Maschine bei Laufzeit und lesen Sie über Betrachtung.[2] Es ist möglich, Meta-Annotationen aus den vorhandenen in Java zu erstellen.[3]

Geschichte

Das Java -Plattform hat verschiedene ad hoc Annotationsmechanismen - zum Beispiel die vorübergehend Modifikator oder der @Veraltet Javadoc -Tag. Das Java -Spezifikationsanfrage JSR-175 führte die allgemeine Annotation vor (auch bekannt als Metadaten) Einrichtung zur Java Community -Prozess in 2002; Es erhielt die Genehmigung im September 2004.[4] Anmerkungen wurden in der Sprache selbst verfügbar, beginnend mit Version 1.5 der Java Entwickler-Kit (JDK). Das geeignet Werkzeug stellte eine vorläufige Schnittstelle für die Annotationsverarbeitung von Kompilierzeit in JDK Version 1.5 zur Verfügung; JSR-269 formalisierte dies und es wurde in die integriert Javac Compiler in Version 1.6.

Eingebaute Anmerkungen

Java definiert eine Reihe von Anmerkungen, die in die Sprache eingebaut sind. Von den sieben Standardanmerkungen sind drei Teil von Java.langund die restlichen vier werden aus java.lang.annotation importiert.[5][6]

Anmerkungen, die auf Java -Code angewendet werden:

  • @Override - Überprüft, ob die Methode eine ist überschreiben. Ursachen a Kompilierungsfehler Wenn die Methode nicht in einem der gefunden wird Elternklassen oder implementiert Schnittstellen.
  • @Veraltet - Markiert die Methode als veraltet. Verursacht eine Kompilierung Warnung, wenn die Methode verwendet wird.
  • @Suppresswarnings - weist den Compiler an, die zu unterdrücken Zeit kompilieren Warnungen in den Annotationsparametern angegeben.

Anmerkungen, die für andere Anmerkungen angewendet werden (auch als "Meta -Anmerkungen" bezeichnet):

  • @Zurückbehaltung - Gibt an, wie die markierte Annotation gespeichert wird, ob nur in Code, in der Klasse zusammengestellt oder zur Laufzeit durch Reflexion verfügbar.
  • @Documented - markiert eine weitere Annotation für die Aufnahme in die Dokumentation.
  • @Ziel - markiert eine weitere Annotation, um einzuschränken, auf welche Art von Java -Elementen die Annotation angewendet werden kann.
  • @Vererbt - markiert eine weitere Annotation, die an Unterklassen der kommentierten Klasse geerbt wird (standardmäßig werden Anmerkungen nicht durch Unterklassen geerbt).

Seit Java 7 wurden drei zusätzliche Anmerkungen zur Sprache hinzugefügt.

  • @Safevarargs - Unterdrückung Warnungen für alle Anrufer einer Methode oder eines Konstruktors mit a Generika Varargs Parameter, seit Java 7.
  • @FunctionalInterface - Gibt an, dass die Typdeklaration soll a sein FunktionsschnittstelleSeit Java 8.
  • @Wiederholbar - Gibt an, dass die Anmerkung mehr als einmal auf dieselbe Erklärung angewendet werden kann, da Java 8.

Beispiel

Eingebaute Anmerkungen

Dieses Beispiel zeigt die Verwendung der @Override Anmerkung. Es weist den Compiler an, übergeordnete Klassen auf Übereinstimmungsmethoden zu überprüfen. In diesem Fall wird ein Fehler erzeugt, weil die Gettype () Methode der Klassenkatze überschreibt tatsächlich nicht Gettype () des Klassentiers ist wegen der gewünscht, wegen der Fehlanpassungsfall. Wenn die @Override Annotation fehlte eine neue Namensmethode Gettype () würde in der Klassenkatze erstellt werden.

Öffentlichkeit Klasse Tier {  Öffentlichkeit Leere sprechen() {  }  Öffentlichkeit Saite Gettyp() {  Rückkehr "Generisches Tier";  } } Öffentlichkeit Klasse Katze erweitert Tier {  @Override  Öffentlichkeit Leere sprechen() { // Dies ist eine gute Überschrift.  System.aus.println("Miau.");  }  @Override  Öffentlichkeit Saite Gettyp() { // Kompilierzeitfehler aufgrund von Tippfehler: Sollte Gettyp () nicht Gettype () sein.  Rückkehr "Katze";  } }

Benutzerdefinierte Anmerkungen

Annotationstypdeklarationen ähneln den normalen Schnittstellenklarationen. Ein AT-Sign (@) geht dem voraus Stichwort "Schnittstelle".

  // @twizzle ist eine Annotation zu Methode Toggle ().  @Twizzle  Öffentlichkeit Leere Umschalten() {  }  // erklärt die Annotation Twizzle.  Öffentlichkeit @Schnittstelle Twizzle {  }

Anmerkungen können eine Reihe von Schlüsselwertpaaren enthalten, die als Methoden des Annotyps modelliert werden. Jede Methodedeklaration definiert ein Element des Annotyps. Methodendeklarationen dürfen keine Parameter oder eine Würfe -Klausel haben. Rückgabetypen sind beschränkt auf Primitive, Saite, Klasse, Aufschwung, Anmerkungen und Arrays der vorhergehenden Typen. Methoden können haben Standardwerte.

  // Gleich wie: @EDIBLE (value = true)  @Essbar(Stimmt)  Artikel Artikel = Neu Karotte();  Öffentlichkeit @Schnittstelle Essbar {  Boolesche Wert() Ursprünglich FALSCH;  }  @Autor(Erste = "Oompah", letzte = "Loompah")  Buch Buchen = Neu Buch();  Öffentlichkeit @Schnittstelle Autor {  Saite Erste();  Saite letzte();  }

Anmerkungen selbst können annotiert werden, um anzuzeigen, wo und wann sie verwendet werden können:

  @Zurückbehaltung(Aufbewahrungsrichtlinie.LAUFZEIT) // Machen Sie diese Annotation zur Laufzeit über Reflexion zugänglich.  @Ziel({{Elementtype.METHODE})  // Diese Annotation kann nur auf Klassenmethoden angewendet werden.  Öffentlichkeit @Schnittstelle Pinzable {  }

Der Compiler behält sich eine Reihe spezieller Anmerkungen vor (einschließlich @Veraltet, @Override und @Suppresswarnings) für syntaktische Zwecke.

Anmerkungen werden oft von verwendet von Frameworks Um Verhaltensweisen bequem auf benutzerdefinierte Klassen und Methoden anzuwenden, die ansonsten in einer externen Quelle (wie einer XML-Konfigurationsdatei) oder programmatisch (mit API-Aufrufen) deklariert werden müssen. Das Folgende ist zum Beispiel ein Annotierter JPA Datenklasse:

@Einheit  // erklärt dies als Entitätsbohne @Tisch(Name = "Personen")  // ordnet die Bohne an SQL -Tabelle "People" zu. Öffentlichkeit Klasse Person Geräte Serialisierbar {  @Ausweis  // Zeichnen Sie dies der Primärschlüsselspalte ab.  @GeneratedValue(Strategie = GenerationTyp.AUTO) // Datenbank generiert neue Primärschlüssel, nicht wir.  Privatgelände Ganze Zahl Ich würde;  @Spalte(Länge = 32)  // Spaltenwerte auf 32 Zeichen verkürzen.  Privatgelände Saite Name;  Öffentlichkeit Ganze Zahl Getid() {  Rückkehr Ich würde;  }  Öffentlichkeit Leere setId(Ganze Zahl Ich würde) {  Dies.Ich würde = Ich würde;  }  Öffentlichkeit Saite GetName() {  Rückkehr Name;  }  Öffentlichkeit Leere Name einsetzen(Saite Name) {  Dies.Name = Name;  } }

Die Anmerkungen sind keine Methodenaufrufe und werden für sich nicht selbst etwas tun. Vielmehr wird das Klassenobjekt an das übergeben JPA Implementierung bei Laufzeit, was dann die Anmerkungen extrahiert, um eine zu generieren Objektrelationskartierung.

Ein vollständiges Beispiel ist unten angegeben:

Paket com.Annotation; importieren java.lang.annotation.documented; importieren java.lang.annotation.elementtype; importieren Java.lang.annotation.inherited; importieren java.lang.annotation.retention; importieren java.lang.annotation.retentionpolicy; importieren java.lang.annotation.target; @Documented @Zurückbehaltung(Aufbewahrungsrichtlinie.LAUFZEIT) @Ziel({{Elementtype.TYP,Elementtype.METHODE,  Elementtype.KONSTRUKTEUR,Elementtype.Annotation_Type,  Elementtype.PAKET,Elementtype.AUFSTELLEN,Elementtype.LOKALE VARIABLE}) @Vererbt Öffentlichkeit @Schnittstelle Unvollendet {  Öffentlichkeit Auflauf Priorität { NIEDRIG, MITTEL, HOCH }  Saite Wert();  Saite[] verändert von() Ursprünglich "" ";  Saite[] Last Changedby() Ursprünglich "" ";  Priorität Priorität() Ursprünglich Priorität.MITTEL;  Saite erstellt von() Ursprünglich "James Gosling";  Saite zuletzt geändert() Ursprünglich "2011-07-08"; } 
Paket com.Annotation; Öffentlichkeit @Schnittstelle Bauarbeiten im Gange {  Saite Eigentümer() Ursprünglich "Patrick Naughton";  Saite Wert() Ursprünglich "Objekt befindet sich im Bau.";  Saite erstellt von() Ursprünglich "Mike Sheridan";  Saite zuletzt geändert() Ursprünglich "2011-07-08"; } 
Paket com.validators; importieren javax.faces.application.facesMessage; importieren javax.faces.component.uicomponent; importieren javax.faces.context.facesContext; importieren javax.faces.validator.validator; importieren javax.faces.validator.validatorexception; importieren com.Annotation.underconstruction; importieren com.Annotation.unfinierte; importieren com.Annotation.unfinished.Priority; importieren com.util.util; @Bauarbeiten im Gange(Eigentümer="Jon Doe") Öffentlichkeit Klasse DateValidator Geräte Validator { 	  Öffentlichkeit Leere bestätigen(Facescontext Kontext, Uicomponent Komponente, Objekt Wert)  Würfe Validatorexception {  Saite Datum = (Saite) Wert;  Saite Fehlerlabel = "Bitte gib ein korrektes Datum an.";  wenn (!Komponente.Getattributes().ist leer()) {  Fehlerlabel = (Saite) Komponente.Getattributes().erhalten("Errordisplayval");  }  wenn (!Util.validateagivendate(Datum)) {  @Unvollendet(verändert von = "Steve",  Wert = "Ob eine Nachricht zum Kontext hinzufügen oder nicht, bestätigen Sie",  Priorität = Priorität.HOCH  )  Facesmessage Botschaft = Neu Facesmessage();  Botschaft.SetSeverity(Facesmessage.Schweregrad);  Botschaft.setSummary(Fehlerlabel);  Botschaft.SetDetail(Fehlerlabel);  Wurf Neu Validatorexception(Botschaft);  }  } }

wird bearbeitet

Wenn der Java-Quellcode kompiliert wird, können Anmerkungen von Compiler-Plug-Ins bezeichnet werden, die als Annotationsprozessoren bezeichnet werden. Prozessoren können Informationsnachrichten erstellen oder zusätzliche Java -Quelldateien oder Ressourcen erstellen, die wiederum kompiliert und verarbeitet werden können. Annotationsprozessoren können jedoch den kommentierten Code selbst nicht ändern. (Code -Änderungen können mithilfe von Methoden implementiert werden Aufbewahrungsrichtlinie von KLASSE oder LAUFZEIT. Später die JVM oder andere Programme können nach den Metadaten suchen, um festzustellen, wie sie mit den Programmelementen interagieren oder ihr Verhalten ändern können.

Neben der Verarbeitung einer Annotation mit einem Annotationsprozessor kann ein Java -Programmierer seinen eigenen Code schreiben, der Reflexionen verwendet, um die Annotation zu verarbeiten. Java se 5 unterstützt eine neue Schnittstelle, die in der definiert ist java.lang.reflect Paket. Dieses Paket enthält die Schnittstelle genannt Annotierelement das wird von den Java -Reflexionsklassen einschließlich implementiert Klasse, Konstrukteur, Aufstellen, Methode, und Paket. Die Implementierungen dieser Schnittstelle werden verwendet, um ein kommentiertes Element des Programms darzustellen, das derzeit in der java -virtuellen Maschine ausgeführt wird. Mit dieser Schnittstelle können Anmerkungen reflektierend gelesen werden.

Das Annotierelement Die Schnittstelle bietet Zugriff auf Anmerkungen mit LAUFZEIT Zurückbehaltung. Dieser Zugang wird von der bereitgestellt Getannotation, Getannotationen, und INAntationPresent Methoden. Da Annotationstypen in Byte -Code -Dateien genau wie Klassen zusammengestellt und gespeichert werden, können die nach diesen Methoden zurückgegebenen Anmerkungen wie jedes reguläre Java -Objekt abgefragt werden. Ein vollständiges Beispiel für die Verarbeitung einer Annotation finden Sie unten:

importieren java.lang.annotation.retention; importieren java.lang.annotation.retentionpolicy; // Dies ist die Annotation, die verarbeitet werden muss // Standard für Ziel sind alle Java -Elemente // Aufbewahrungsrichtlinie in der Laufzeit ändern (Standard ist Klasse) @Zurückbehaltung(Aufbewahrungsrichtlinie.LAUFZEIT) Öffentlichkeit @Schnittstelle Typader {  // Standardwert für das Entwicklerattribut angegeben  Saite Entwickler() Ursprünglich "Unbekannt";  Saite zuletzt bearbeitet();  Saite [] Teammitglieder();  int Sinn des Lebens(); } 
// Dies ist die Annotation, die auf eine Klasse angewendet wird @TypeHeader(Entwickler = "Bob Bee",  zuletzt bearbeitet = "2013-02-12",  Teammitglieder = { "Ann", "Dan", "Fran" },  Sinn des Lebens = 42) Öffentlichkeit Klasse SetCustomannotation {  // Klasseninhalte gehen hier } 
// Dies ist der Beispielcode, der die Annotation verarbeitet importieren java.lang.annotation.annotation; importieren java.lang.reflect.annotatedElement; Öffentlichkeit Klasse Usecustomannotation {  Öffentlichkeit statisch Leere hauptsächlich(Saite [] Args) {  Klasse<SetCustomannotation> classObject = SetCustomannotation.Klasse;  Readannotation(classObject);  }  statisch Leere Readannotation(Annotierelement Element) {  Versuchen {  System.aus.println("Annotation -Element -Werte: \ n");  wenn (Element.INAntationPresent(Typader.Klasse)) {  // GetAnnotation gibt Annotationstyp zurück  Anmerkung Singleannotation =   Element.Getannotation(Typader.Klasse);  Typader Header = (Typader) Singleannotation;  System.aus.println("Entwickler:" + Header.Entwickler());  System.aus.println("Zuletzt bearbeitet: " + Header.zuletzt bearbeitet());  // Teammitglieder kehrten als String [] zurück  System.aus.drucken("Teammitglieder:");  zum (Saite Mitglied : Header.Teammitglieder())  System.aus.drucken(Mitglied + ",");  System.aus.drucken("\n");  System.aus.println("Sinn des Lebens: "+ Header.Sinn des Lebens());  }  } Fang (Ausnahme Ausnahme) {  Ausnahme.printstacktrace();  }  } }

Verwendung in freier Wildbahn

Forscher haben die Verwendung von Java-Annotationen über 1.094 bemerkenswerte Open-Source-Java-Projekte untersucht, die auf GitHub veranstaltet werden. Sie stellten fest, dass Anmerkungen aktiv aufrechterhalten werden, wobei viele Anmerkungen hinzugefügt werden, aber auch aufgrund von Fehler im Annotationstyp oder -Werte geändert oder entfernt wurden. Insgesamt stellt diese Studie fest, dass es eine kleine, aber signifikante Beziehung zwischen Annotationsverwendung und Code-Fehlerunfähigkeit gibt: Java-Code mit Anmerkungen ist tendenziell weniger fehleranfällig.[7]

Siehe auch

Verweise

  1. ^ "Anmerkungen". Sun Microsystems. Archiviert von das Original Am 2011-09-25. Abgerufen 2011-09-30..
  2. ^ Sun Microsystems (2005). Java (TM) Sprachspezifikation (3. Aufl.). Prentice Hall. ISBN 0-321-24678-0..
  3. ^ Dare Obasanjo (2007). "Ein Vergleich der C# -Pergramm -Sprache von Microsoft mit der Java -Programmiersprache von Sun Microsystems: Metadatenanmerkungen". Wagen Sie Obasanjo. Archiviert von das Original am 09.09.2012. Abgerufen 2012-09-20.
  4. ^ Coward, Danny (2006-11-02). "JSR 175: Eine Metadatenanlage für die Javatm -Programmiersprache". Java Community -Prozess. Abgerufen 2008-03-05.
  5. ^ "Vordefinierte Annotationstypen". Oracle Corporation. Abgerufen 2016-12-17.
  6. ^ "Die integrierten Anmerkungen: Standardanmerkungen". Abgerufen 2016-12-17.
  7. ^ Yu, zhongxing; Bai, Chenggang; Seinturier, Lionel; Monperrus, Martin (2019). "Charakterisierung der Verwendung, Entwicklung und Auswirkungen von Java -Anmerkungen in der Praxis". IEEE -Transaktionen auf Software -Engineering. 47 (5): 969–986. Arxiv:1805.01965. doi:10.1109/tse.2019.2910516. S2CID 102351817.

Externe Links