Die Anleitung zu Java Annotation

Was ist Annotation und das Benutzungszweck
Die verfügbare Annotation von Java
Ihre Annotation schreiben
Annotation Processing Tool (das fortgeschrittene Kenntnis)

1. Was ist Annotation und das Benutzungszweck

Annotation (Kommentar) wird zur Datenversorgung für Ihre Java Code benutzt. Als Dateninformation wirken die Annotation nicht direkt auf Ihre Kodierung aus, obwohl einige Annotation eigentlich für das Zweck benutzt werden. Annotaiton wird ab Java 5 angewendet

Annotation wird für die folgenden Zwecke benutzt:

Anweisung für Compiler
Anweisung in Build-time
Anweisung in Runtime)

Die Anleitung für den Kompiler

3 Annotation befinden sich im Java, das Sie für die Anweisung für die Java Compiler benutzen können

@Deprecated
@Override
@SuppressWarnings

Die Annotation werden detailiert in diesen Unterlagen übersetzt.

Die Anleitung in der Bauen-zeit (Build-time)

Annotation wird in Build-time benutzt wenn Sie Ihre Software bauen. Der Bauprozess besteht aus der Erstellung der Source Code, der Compiler von Source Code, Erstellung der XML file (wie Bezeichnung der Durchführung), Einpackung der Compiler Code und die File in einem JAR File ... Ein Soft ware bauen wird oft durch ein automatische Bauinstrument wie Apache Ant oder Apache Maven gemacht. Das Instrument bauen kann Ihr Java Code scannen und nach Ihrer Annotation können die Source Code oder die sonstige File erstellt werden

Die Anleitung in der Laufenzeit (Runtime)

Normaleweise sind die Annnotation nach Compile in Ihrem Java nicht. Aber Sie können die Annotation während Laufen bestimmen. Die Annotation wird dann durch Java Reflection zugegriffen und für die Hinweise Ihres Programm, oder third party API benutzt

Mehr sehen
Die Anleitung zu Java Reflection

2. Die verfügbare Annotation von Java

3 Annotation handen sich im Java vor

@Deprecated
@Override
@SuppressWarnings

@Deprecated

Das ist eine Annotation für das Kommentar einer veralteten Dinge, Sie sollen nicht mehr benutzen wie class oder method.
Annotation @Deprecated wird Ihnen von Compiler zu benachrichtigen benutzt, dass Sie eine Ersatz benutzen sollen . Oder IDE Programmierung wie Eclipse haben die Nachricht für Sie visuell

DeprecatedMethodDemo.java

package org.o7planning.tutorial.ann.builtin;

import java.util.Date;

public class DeprecatedMethodDemo {

  /**
   * @deprecated replaced by {@link #todo(String,Date)}
   */
  @Deprecated
  public void todoJob(String jobName) {
      System.out.println("Todo " + jobName);
  }

  public void todo(String jobName, Date atTime) {
      System.out.println("Todo " + jobName + " at " + atTime);
  }

  public void todoNothing() {
      System.out.println("Todo Nothing");
  }

  public static void main(String[] args) {

      DeprecatedMethodDemo obj = new DeprecatedMethodDemo();

      obj.todoJob("Java coding");

      obj.todoNothing();
  }
}

Unten ist die Image der Nachrichten von Eclipse

@Override

Annotation @Override wird für die Überschreibungmethode einer Methode in einer Vaterclass (superclass) benutzt . Wenn die Methode einer Methode in superclass nicht entspricht, schickt die Compiler Ihnen ein Fehler.

Annotation @Override ist nicht obligatorisch, auf die Überschreibungsmethode einer Methode der superclass zu kommentieren. Das ist eine gute Idee beim Benutzen. Wenn jemand die Methode der superclass ändert, ist die Methode von Ihrer Class die Überschreibungsmethode nicht mehr. Sie können nicht es finden wenn es keine Annotation@Override . Mit der Annotation @Override wird die Compiler Ihnen wissen lassen, dass die Methode in Tochterclass auf die superclass nicht überschreiben

Sehen Sie bitte das Beispiel

Job.java

package org.o7planning.tutorial.ann.builtin;

public class Job {

	// Das ist die Methode der Klasse Job
	public String getName() {
		return null;
	}

}

JavaCoding.java

package org.o7planning.tutorial.ann.builtin;

public class JavaCoding extends Job {

	// Das ist  die Methode um die Methode getName() 
	// von der VaterKlasse überzuschreiben.
	// @Override ist nicht zwanghaft, auf diese Methode zu binden. 
	// Aber es ist notwendig wenn jemand den Name der Methode getName() 
	// von der VaterKlasse ändert, wird eine Fehleranmeldung auftreten
	@Override
	public String getName() {
		return "Java Coding";
	}

}

Und hier ist die Nachricht von Java Compiler:

@SuppressWarnings

Mit Die Annotation @SuppressWarnings benachrichtigt der Compiler ein Problem der Methode nicht. Zum Beispiel Wenn eine Methode veraltet ist oder in einer Methode etwas nicht sicher, hat der Compiler eine Warnung. Sie können die Warnung durch die Annotation der Methode mit @SuppressWarnings stoppen

Sehen Sie ein BEispiel

SuppressWarningsDemo.java

package org.o7planning.tutorial.ann.builtin;

import java.util.Date;

public class SuppressWarningsDemo {

  @SuppressWarnings("deprecation")
  public Date getSomeDate() {

      Date date = new Date(2014, 9, 25);
      return date;
  }

}

Sehen Sie die Warnung von dem Kompiler

SuppressWarningsDemo2.java

package org.o7planning.tutorial.ann.builtin;

import java.util.ArrayList;
import java.util.Date;
import java.util.List;

public class SuppressWarningsDemo2 {

	public List<?> getDatas() {
		List<String> list = new ArrayList<String>();
		list.add("One");
		return list;
	}

	@SuppressWarnings({ "deprecation", "unused", "unchecked" })
	public void processDatas() {

		// Sie benutzen einen veralteten Constructor. 
		// Und die Variable 'date' wird erstellt aber sie wird nicht benutzt.
		Date date = new Date(2014, 9, 25);

		// Das Typ von cast unsicher. 
		// Und die Variable 'datas' wird erstellt aber sie wird in die Code nicht benutzt.
		List<String> datas = (List<String>) this.getDatas();
	}

}

Die Warnung des Kompiler

3. Ihre Annotation schreiben

Benutzen Sie @interface als ein Meldungsschlüsselwort zu einer Annotaion. Die Annotation ist ziemlich gleich wie eine Interface. Die Annotation hat die oder keine Elemente

Die Eigenschaften von Elemente von der Annotation

Es hat keinen Funktionskörper (body)
Es hat keinen Funktionsparameter
Die Rückgabe-Meldung muss ein bestimmtes Typ sein:
- primitive Typen (boolean, int, float, ...)
- Enum
- Annotation
- Die Klasse (zum Beispiel String.class)
Es kann die bestimmten Wert

Die erste Annotation

MyFirstAnnotation.java

package org.o7planning.tutorial.ann1;

public @interface MyFirstAnnotation {

	// Der Element 'name'.
	public String name();

	// Der Element  'description' mit der Default-Wert "".
	public String description() default "";

}

Die Annotation kann auf ... zugewiesen werden:

TYPE - Die Meldung von der Klasse (Class), der Interface, des enum, der Annotation.
FIELD - Die Meldung von Feld (field), einschließend die Enum Konstante.
METHOD - Die Meldung von Methode.
PARAMETER - Die Meldung von parameter
CONSTRUCTOR - Die Meldung von Constructor
LOCAL_VARIABLE - Die Meldung von der lokalen Variable
ANNOTATION_TYPE - Die Meldung der Annotation
PACKAGE - Die Meldung der Package

UsingMyFirstAnnotation.java

package org.o7planning.tutorial.ann1;

@MyFirstAnnotation(name = "Some name", description = "Some description")
public class UsingMyFirstAnnotation {

	// Annotation wird in einem Constructor gebindet.
	// Die Wert des Element 'name' ist "John"
	// Die Wert des Element 'description' ist "Write by John".
	@MyFirstAnnotation(name = "John", description = "Write by John")
	public UsingMyFirstAnnotation() {

	}

	// Annotation wird in einer Methode gebindet.
	// Die Wert des Element  'name' ist "Tom"
	// Die Wert des Element 'description' wird nicht erklärt, sondern nach dem Default .
	@MyFirstAnnotation(name = "Tom")
	public void someMethod() {

	}

	// Annotation bindet in einem Parameter der Methode.
	public void todo(@MyFirstAnnotation(name = "none") String job) {

		// Annotation bindet in einer lokalen Variable
		@MyFirstAnnotation(name = "Some name")
		int localVariable = 0;

	}

}

Die Annotation mit der Elemente value. (besonder)

Eine Annotation, die ein Element value hat, hat einige Besonderheit

AnnWithValue.java

package org.o7planning.tutorial.ann2;

public @interface AnnWithValue {

	// Ein Element heißt  'value' von der Annotation.
	// Es gibt ein bisschen besonder bei der Verwendung dieses Element.
	public int value();

	// Das Element 'name'
	public String name() default "";

}

UsingAnnWithValue.java

package org.o7planning.tutorial.ann2;

public class UsingAnnWithValue {

	// Die Elemente von der Annotation in den normalen Weg initializieren.
	@AnnWithValue(name = "Name1", value = 100)
	public void someMethod1() {

	}

	// Die Elemente von der Annotation in den noramlen Weg initializieren.
	// Das Element 'name' von der Annotation hat die Default-Wert
	@AnnWithValue(value = 100)
	public void someMethod2() {

	}

	// Das Element 'value' ist besonder.
	// Statt vom Schreiben  @AnnWithValue(value = 100)
	// Sie schreiben nur @AnnWithValue(100)
	@AnnWithValue(100)
	public void someMethod3() {

	}
}

@Retention & @Target

@Retention & @Target sind 2 vorhandene Annotaion vom Java.

@Retention

@Retention: ist für den Kommentar der Existenz einer Annotation. Es gibt gegenständlich 3 Level des annotierten Objekt:

RetentionPolicy.SOURCE: auf die Source Code existieren und wird durch den Kompiler (compiler) nicht gefunden.
RetentionPolicy.CLASS: Der Existenz wird von dem Kompiler gefunden aber von dem virtuellen Maschinen beim Runtime nicht gefunden.
RetentionPolicyRUNTIME: Der größten Existenzlevel und wird durch den Kompiler gefunden und das virtuelle Maschine findet den Existenz beim Runtime auch.

@Target

@Target: ist für das KOmmentar einer anderen Annotaion und die Annotation wird in welcher Bereich benutzt.

ElementType.TYPE - die Meldung der Klasse, Interface, Enum und Annotation verbinden.
ElementType.FIELD - die Meldung des Felds (field), einschließend die Enum Konstante verbinden.
ElementType.METHOD - die Meldung der Methode verbinden.
ElementType.PARAMETER - die Meldung des Parameter verbinden
ElementType.CONSTRUCTOR - die Meldung des Constructor verbinden
ElementType.LOCAL_VARIABLE - die Meldung des lokalen Variable verbinden.
ElementType.ANNOTATION_TYPE - die Meldung der Annotaion verbinden
ElementType.PACKAGE - die Meldung der Package verbinden.

AnnFM.java

package org.o7planning.tutorial.ann3;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

// Annotation sagt, dass AnnFM auf die Source Code nur erkannt wird.
// Es wird durch den Kompiler nicht erkannt,
// Und in der Laufzeit erkennt die virtuellen Maschine seine Existenz nicht
@Retention(value = RetentionPolicy.SOURCE)

// Annotation sagt:
// AnnFM wird auf FIELD oder METHOD nur benutzt.
@Target(value = { ElementType.FIELD, ElementType.METHOD })
public @interface AnnFM {

}

UsingAnnFM.java

package org.o7planning.tutorial.ann3;

public class UsingAnnFM {

	// AnnFM ist nur erlaubt, auf FIELD oder METHOD zu annotieren.
	@AnnFM
	protected int someField = 100;

	// AnnFM ist nur erlaubt, auf FIELD oder METHOD zu annotieren.
	@AnnFM
	public void someMethod() {

	}

}

Annotation & Reflection

Beachten SIe: Wenn Sie nur mit Java zu lernen anfängen,können Sie diese Part ignorieren. Denn es braucht eine Überblick und es ist nicht notwendig zu studieren

Java Reflection kann die Dinge wie Class, field, method, .. erkennen, die durch eine Annotation annotiert wird. Und natürlich kennt sie nur die Annotation mit @Retention(RetentionPolicy.RUNTIME)

Mehr sehen
Die Anleitung zu Java Reflection

Das nächste Beispiel stellt ein Programm für die Lesung aller Kommentar in Java File und Erstllung der html file. Jede class entspricht einer html file

AnnHtmlUL.java

package org.o7planning.tutorial.ann4;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.RUNTIME)

// Annotation sagt:
// AnnHtmlUL wird nur für Class, interface, annotation, enum benutzt.
@Target(value = { ElementType.TYPE })

// AnnHtmlUL: Den Tag (tag) <UL> in HTML simulieren.
public @interface AnnHtmlUL {

	public String border() default "border:1px solid blue;";
	
}

AnnHtmlLI.java

package org.o7planning.tutorial.ann4;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.RUNTIME)
@Target(value = { ElementType.FIELD, ElementType.METHOD })

// Den Tag (tag) <LI> in HTML simulieren
public @interface AnnHtmlLI {

	public String background();

	public String color() default "red";
	
}

DocumentClass.java

package org.o7planning.tutorial.ann4;

@AnnHtmlUL(border = "1px solid red")
public class DocumentClass {

	private String author;

	@AnnHtmlLI(background = "blue", color = "black")
	public String getDocumentName() {
		return "Java Core";
	}

	@AnnHtmlLI(background = "yellow")
	public String getDocumentVersion() {
		return "1.0";
	}

	@AnnHtmlLI(background = "green")
	public void setAuthor(String author) {
		this.author = author;
	}

	@AnnHtmlLI(background = "red", color = "black")
	public String getAuthor() {
		return author;
	}
	
	// Die Methode wird nicht durch eine Annotation annotiert
	public float getPrice()  {
		return 100;
	}

}

HtmlGenerator.java

package org.o7planning.tutorial.ann4;

import java.lang.reflect.Method;

public class HtmlGenerator {

	public static void main(String[] args) {

		Class<?> clazz = DocumentClass.class;

		// Prüfen, ob die Klasse durch AnnHtmlUL annotiert wird oder nicht.
		boolean isHtmlUL = clazz.isAnnotationPresent(AnnHtmlUL.class);

		StringBuilder sb = new StringBuilder();
		if (isHtmlUL) {

			// Das Objekt AnnHtmlUL herausnehmen und auf diese Klasse annotieren.
			AnnHtmlUL annUL = clazz.getAnnotation(AnnHtmlUL.class);

			sb.append("<H3>" + clazz.getName() + "</H3>");
			sb.append("\n");

			// Die Wert des Element 'border' von AnnHtmlUL.
			String border = annUL.border();

			sb.append("<UL style='border:" + border + "'>");

			// Zeilenschaltungen einfügen.
			sb.append("\n");

			Method[] methods = clazz.getMethods();

			for (Method method : methods) {
				// Prüfen, ob die Klasse durch AnnHtmlLI annotiert wird oder nicht.
				if (method.isAnnotationPresent(AnnHtmlLI.class)) {
					// Die Annotation herausnehmen.
					AnnHtmlLI annLI = method.getAnnotation(AnnHtmlLI.class);

					// Die Wert der Elemente von  AnnHtmlLI nehmen.
					String background = annLI.background();
					String color = annLI.color();

					sb.append("<LI style='margin:5px;padding:5px;background:" + background + ";color:" + color + "'>");
					sb.append("\n");
					sb.append(method.getName());
					sb.append("\n");
					sb.append("</LI>");
					sb.append("\n");
				}
			}
			sb.append("</UL>");
		}
		writeToFile(clazz.getSimpleName() + ".html", sb);
	}

	// Die Information auf dem Bildschirm Console (oder file) schreiben.
	private static void writeToFile(String fileName, StringBuilder sb) {
		System.out.println(sb);
	}

}

Ergebnis von Beispiel

<H3>org.o7planning.tutorial.ann4.DocumentClass</H3>
<UL style='border:1px solid red'>
<LI style='margin:5px;padding:5px;background:blue;color:black'>
getDocumentName
</LI>
<LI style='margin:5px;padding:5px;background:yellow;color:red'>
getDocumentVersion
</LI>
<LI style='margin:5px;padding:5px;background:green;color:red'>
setAuthor
</LI>
<LI style='margin:5px;padding:5px;background:red;color:black'>
getAuthor
</LI>
</UL>

Fall von der Erstellung einer html file

4. Annotation Processing Tool (das fortgeschrittene Kenntnis)

The situation is that:

Sie bauen einige Annotation und benutzen für Ihre Java Applikation. Die Annotaion haben einen Grundsatz, die von Ihnen geregelt. Sie möchten, der Complier bei der Komplierung eine Warnung der Verletzung von Grundsatz benachrichtigt. Und wenn Sie Eclipse für die Programmierung benutzen, möchten Sie, dass Eclipse die Fehlerwarnung in IDE macht.

Das passt ganz zu APT (Annotation Processing Tool).

Sie können die Hinweise APT in:

Anpassen von Java-Compiler, der Ihre Annotation verarbeitet (Annotation Processing Tool)