Java - anotace

Mnoho API vyžaduje velké množství dokumentačního kódu. Pokud například chcete napsat webovou službu JAX-RPC, musíte poskytnout rozhraní spárované s implementací. Dokumentace by mohla být automaticky vytvořena nějakým nástrojem pokud by byl program "ozdoben" anotacemi označujícími které metody byly vzdáleně přístupné.

Jiná API zase vyžadují "postranní soubory" aby mohla být udržována paralelně s programy. Například JavaBeans vyžaduje aby třída BeanInfo byla udržována paralelně s bean, a Enterprise JavaBeans (EJB) vyžaduje popisovač rozmístění. Bylo by mnohem lepší a méně náchylnější k chybám kdyby informace z těchto postranních souborů byly udržovány jako anotace v samotném programu.

Platforma Java měla vždy nějaké nahodilé mechanismy anotace. Napříkad modifikátor transient je nahodilou anotací indikující že rozhraní by mělo být ignorováno serializačním subsystémem, a tag @deprecated je nahodilou implementací indikující že metoda by neměla být déle používána. Od verze 5.0 obsahuje platforma obecnou formu anotace (také známmou jako metadata) která vám dovoluje definovat a používat svoje vlastní typy anotací. Forma sestává ze syntaxe pro deklaraci typu anotace, syntaxe pro anotaci deklarací, API pro čtení anotací, .class souboru představujícího anotace a nástroj pro zpracování anotací.

Anotace nepřímo ovliv��ují sémantiku programu, ale ovliv��ují způsob jakým nástroje a knihovny zacházejí s programy, což může v důsledku ovlivnit sémantiku běžícího programu. Anotace mohou být čteny ze zdrojových souborů, .class souborů nebo pomocí reflexe za běhu programu.

Běžně programátoři aplikací nikdy nebudou muset definovat typ anotace, ale není těžké tak učinit. Deklarace typů anotací jsou podobné normální delkaraci rozhraní. Klíčovému slovu interface předchází zavináč @. Každá deklarace metody definuje prvek typu anotace. Deklarace metody nesmí obsahovat parametry nebo klauzuli throws. Návratové typy jsou omezeny na primitivní datové typy, String, Class, výčtové typy, anotace a pole předchozích datových typů. Metody mohou mít defaultní hodnoty. Tady je příklad deklarace typu anotace:

/**
 * Popisuje Požadavek-Na-Rozšíření (Request-For-Enhancement, RFE) 
 * který vedl k přítomnosti anotovaného prvku v API.
 */

public @interface RequestForEnhancement {
	int id();
	String synopsis();
	String engineer() default "[unassigned]";
	String date() default "[unimplemented]";
}

Jakmile je jednou typ anotace definován, můžete ho použít k anotaci deklarací. Anotace je zvláštní druh modifikátoru, a můž být použit kdekoli s ostatními modifikátory (jako public, static nebo final). Dle konvencí anotace předcházejí ostatní modifikátory. Anotace sestávají ze zavináče (@) následovaného typem anotace a seznamem prvků-hodnot v závorce. Hodnoty musí být konstantami které lze zkontrolovat při kompilaci. Zde je deklarace metody s anotací odpovídající typu anotace deklarované v předešlé ukázce kódu:

	@RequestForEnhancement {
		id = 2868724,
		synopsis = "Enable time-travel",
		engineer = "Mr. Peabody",
		date = "4/1/3007"
	}

	public static void travelThroughTime(Date destination) {
		. . .
	}