epubjs
Version:
Render ePub documents in the browser, across many devices
119 lines (116 loc) • 14.7 kB
HTML
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Annotations</title><link rel="stylesheet" href="core.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"/></head><body><div class="sect1" title="Annotations"><div class="titlepage"><div><div><h1 class="title"><a id="learnjava3-CHP-7-SECT-4"/>Annotations</h1></div></div></div><p>As we mentioned in <a class="xref" href="ch04.html" title="Chapter 4. The Java Language">Chapter 4</a>, Java for a
long time has supported a limited kind of metadata in Java source code
through the use of Javadoc comment tags. With Javadoc tags like <a id="I_indexterm7_id705739" class="indexterm"/><code class="literal">@deprecated</code> or <a id="I_indexterm7_id705752" class="indexterm"/><code class="literal">@author</code>, we can add some
information to a class, method, or field by sticking it into comments
above the item. In this case, the information is mainly useful to the
Javadoc documentation generator, because comments exist only in Java
source code. However, developers have long wanted a way to generalize
metadata for other purposes. And in fact, some tools have been developed
over the years that read extended Javadoc-style tags in comments and do
all sorts of things with them, including code generation and
documentation. In Java 5.0, a formal, extensible metadata system called
annotations was added to the language that provides this kind of
source-level functionality as well as new possibilities for using metadata
at runtime.</p><p><a id="I_indexterm7_id705772" class="indexterm"/>Annotations allow you to add metadata to Java packages,
classes, methods, and fields. This metadata can be utilized by tools at
compile time and optionally retained in the compiled Java classes for use
at runtime as well. The availability of annotation data to the running
program opens up new uses for metadata. For example, annotations cannot
only be used at compile time to generate auxiliary classes or resources,
but also could be used by a server to provide special services to classes
such as importing or exporting of values, security, or monitoring.
<a id="I_indexterm7_id705786" class="indexterm"/><a id="I_indexterm7_id705792" class="indexterm"/><a id="I_indexterm7_id705797" class="indexterm"/><a id="I_indexterm7_id705803" class="indexterm"/>Annotations will be used heavily in Java XML Binding (JAXB),
the Java Servlets API, and Java Web Services (JAX-WS), as we’ll see later
in the book. In those cases, annotations are used to simplify
configuration and deployment information.</p><p>Technically, according to the spec, annotations are not supposed to
“directly affect the semantics of a program.” However, that admonition is
a little vague and there is some fear in the Java community that this
facility will open a Pandora’s box of possible abuses. Hopefully,
developers will use them with restraint.</p><p>Only a handful of “built-in” annotations are commonly used in Java
and we’ll summarize them in this section. More built-in annotations are
used with specialized packages such as those for web services and some are
used in creating the annotations themselves. Creating your own annotations
for use in your code is syntactically easy (essentially just like
declaring an interface), but implementing the behavior for them via the
compiler or a runtime system is a bit beyond the scope of this book, so we
won’t cover that here. The JDK provides a framework tool called
<span class="emphasis"><em>apt</em></span> that can be used to implement source-level
annotations that generate and compile code or resource files at compile
time. Accessing annotation data at runtime is done via the Reflection API
as described briefly earlier in this chapter.</p><div class="sect2" title="Using Annotations"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-7-SECT-4.1"/>Using Annotations</h2></div></div></div><p><a id="idx10349" class="indexterm"/> <a id="idx10352" class="indexterm"/> <a id="idx10371" class="indexterm"/>Annotations are placed in the code preceding the annotated
item using an <code class="literal">@</code> (at) symbol followed
by the annotation class name. The <a id="I_indexterm7_id705890" class="indexterm"/><code class="literal">@Deprecated</code> annotation
is an example of the simplest kind, a <span class="emphasis"><em>marker</em></span> or
<a id="I_indexterm7_id705907" class="indexterm"/><span class="emphasis"><em>flag</em></span> annotation. A marker annotation
indicates some semantics just by its presence. (In the case of <code class="literal">@Deprecated</code>, it means that the member is
deprecated and the compiler should generate warnings if it is used.) To
use the <code class="literal">@Deprecated</code> annotation, we
place it before a Java class, method, or field like this:</p><a id="I_7_tt387"/><pre class="programlisting"> <code class="nd">@Deprecated</code>
<code class="kd">class</code> <code class="nc">OldClass</code> <code class="o">{</code> <code class="o">...</code> <code class="o">}</code>
<code class="kd">class</code> <code class="nc">AgingClass</code>
<code class="o">{</code>
<code class="nd">@Deprecated</code>
<code class="kd">public</code> <code class="nf">someMethod</code><code class="o">()</code> <code class="o">{</code> <code class="o">...</code> <code class="o">}</code>
<code class="o">...</code>
<code class="o">}</code></pre><p>More generally, annotations may take “arguments” in an extended
method-like syntax. <a class="xref" href="ch07s04.html#learnjava3-CHP-7-TABLE-1" title="Table 7-1. Use of arguments in annotations">Table 7-1</a>
summarizes the possible variations.</p><div class="table"><a id="learnjava3-CHP-7-TABLE-1"/><p class="title">Table 7-1. Use of arguments in annotations</p><div class="table-contents"><table summary="Use of arguments in annotations" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; "><colgroup><col/><col/></colgroup><thead><tr><th style="text-align: left"><p>Example</p></th><th style="text-align: left"><p>Description</p></th></tr></thead><tbody><tr><td style="text-align: left"><p> <a id="I_indexterm7_id705992" class="indexterm"/> <code class="literal">@Deprecated</code>
</p></td><td style="text-align: left"><p>Marker annotation (no
“data”)</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm7_id706019" class="indexterm"/> <code class="literal">@WarningMessage("Something about...")</code>
</p></td><td style="text-align: left"><p>Single argument</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm7_id706045" class="indexterm"/> <code class="literal">@TestValues( { "one",
"two" } )</code> </p></td><td style="text-align: left"><p>Array of arguments</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm7_id706072" class="indexterm"/> <code class="literal">@Author( first="Pat",
last="Niemeyer" )</code> </p></td><td style="text-align: left"><p>Named arguments</p></td></tr></tbody></table></div></div><p>The first annotation in the table, <code class="literal">@Deprecated</code>, is a real annotation as described
earlier; the remaining three are fictitious. To accept multiple values,
an annotation may either use the curly brace ({}) array syntax or the
more novel named argument syntax listed in the final example. The named
syntax allows arguments to be passed in any order.</p><div class="sect3" title="Package annotations"><div class="titlepage"><div><div><h3 class="title"><a id="id1175282"/>Package annotations</h3></div></div></div><p><a id="I_indexterm7_id706107" class="indexterm"/> <a id="I_indexterm7_id706115" class="indexterm"/> <a id="I_indexterm7_id706129" class="indexterm"/> <a id="I_indexterm7_id706140" class="indexterm"/>In the introduction, we mentioned that Java packages can
be annotated. This raises the question of where one would place such
an annotation, as there is ordinarily no location where we “declare” a
Java package; we normally just use them implicitly. The answer is that
by convention we can create a file named <a id="I_indexterm7_id706152" class="indexterm"/><span class="emphasis"><em>package-info.java</em></span> and place it into
the folder corresponding to the Java package. The file cannot contain
Java classes, but should contain a package statement. Package
annotations can be placed on this package statement. In the following
example, we deprecate the whole package <code class="literal">learningjava.oldstuff</code> such that using any of
its classes generates the deprecation warning.<a id="I_indexterm7_id706170" class="indexterm"/><a id="I_indexterm7_id706177" class="indexterm"/><a id="I_indexterm7_id706184" class="indexterm"/></p><a id="I_programlisting7_id706191"/><pre class="programlisting"><code class="c1">// file: learningjava/service/package-info.java</code>
<code class="cm">/** </code>
<code class="cm"> * We can put package comments here too! </code>
<code class="cm"> */</code>
<code class="nd">@Deprecated</code>
<code class="kn">package</code> <code class="n">learningjava</code><code class="o">.</code><code class="na">oldstuff</code><code class="o">;</code></pre></div></div><div class="sect2" title="Standard Annotations"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-7-SECT-4.2"/>Standard Annotations</h2></div></div></div><p><a id="idx10348" class="indexterm"/> <a id="idx10351" class="indexterm"/> <a id="idx10370" class="indexterm"/> <a id="idx10387" class="indexterm"/> <a class="xref" href="ch07s04.html#learnjava3-CHP-7-TABLE-2" title="Table 7-2. Standard annotations">Table 7-2</a> summarizes
common annotations supplied with Java.</p><div class="table"><a id="learnjava3-CHP-7-TABLE-2"/><p class="title">Table 7-2. Standard annotations</p><div class="table-contents"><table summary="Standard annotations" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; "><colgroup><col/><col/></colgroup><thead><tr><th style="text-align: left"><p>Annotation</p></th><th style="text-align: left"><p>Description</p></th></tr></thead><tbody><tr><td style="text-align: left"><p> <code class="literal">@Deprecated</code> </p></td><td style="text-align: left"><p>Deprecation warning on
member</p></td></tr><tr><td style="text-align: left" valign="top"><p> <a id="I_indexterm7_id706327" class="indexterm"/> <code class="literal">@Override</code>
</p></td><td style="text-align: left"><p>Indicates that the annotated method
must override a method in the parent class or else a compiler
warning is issued</p></td></tr><tr><td style="text-align: left" valign="top"><p> <code class="literal">@SuppressWarnings(value="</code>
<span class="emphasis"><em>type</em></span> <code class="literal">")</code>
</p></td><td style="text-align: left"><p>Indicates that the specified warning
types should be suppressed by the compiler for the annotated
class or method</p></td></tr></tbody></table></div></div><p>We have already discussed the <code class="literal">@Deprecated</code> and <code class="literal">@Override</code> annotations, the latter of which we
covered in the section <a class="xref" href="ch06s01.html#learnjava3-CHP-6-SECT-1.2" title="Overriding Methods">Overriding Methods</a>. The
<a id="I_indexterm7_id706399" class="indexterm"/><code class="literal">@SuppressWarnings</code>
annotation is intended to have a compelling use in bridging legacy code
with newer code using generics after Java 5.0, but some compilers may
not implement it.</p><p>Additional annotations are supplied with Java as part of the
<a id="I_indexterm7_id706417" class="indexterm"/><code class="literal">java.lang.annotations</code>
package that are used to annotate only other annotations (they are
really meta-annotations). For example, the <code class="literal">java.lang.annotation.Retention</code> annotation sets
the retention policy for an annotation, specifying whether it is
retained in the compiled class and loaded at runtime.<a id="I_indexterm7_id706436" class="indexterm"/><a id="I_indexterm7_id706444" class="indexterm"/><a id="I_indexterm7_id706451" class="indexterm"/><a id="I_indexterm7_id706458" class="indexterm"/></p></div><div class="sect2" title="The apt Tool"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-7-SECT-4.3"/>The apt Tool</h2></div></div></div><p><a id="I_indexterm7_id706471" class="indexterm"/> <a id="idx10347" class="indexterm"/> <a id="I_indexterm7_id706490" class="indexterm"/> <a id="I_indexterm7_id706497" class="indexterm"/> <a id="I_indexterm7_id706510" class="indexterm"/>The Java JDK ships with the command-line Annotation
Processing Tool, <span class="emphasis"><em>apt</em></span>, which is a sort of frontend
to the <a id="I_indexterm7_id706525" class="indexterm"/><span class="emphasis"><em>javac</em></span> compiler.
<span class="emphasis"><em>apt</em></span> uses pluggable annotation processors to process
the annotations in source files before the code is compiled by
<span class="emphasis"><em>javac</em></span>. If you write your own source-level
annotations, you can build a plug-in annotation processor for
<span class="emphasis"><em>apt</em></span> that will be invoked to process your
annotations in the source code. Your annotation processor can be quite
sophisticated, examining the structure of the source code (in a
read-only fashion) through the supplied syntax tree (object model) and
generating any additional files or actions that it wishes. If you
generate new Java source files, they will be automatically compiled by
<span class="emphasis"><em>javac</em></span> for you. Running <span class="emphasis"><em>apt</em></span> on
a source file with no annotations simply falls through to
<span class="emphasis"><em>javac</em></span>.<a id="I_indexterm7_id706564" class="indexterm"/></p></div></div></body></html>