/usr/share/doc/aspectj-doc/adk15notebook/annotations.html is in aspectj-doc 1.8.9-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 2. Annotations</title><link rel="stylesheet" type="text/css" href="aspectj-docs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="The AspectJTM 5 Development Kit Developer's Notebook"><link rel="up" href="index.html" title="The AspectJTM 5 Development Kit Developer's Notebook"><link rel="prev" href="join-point-matching-summary.html" title="Summary of Join Point Matching"><link rel="next" href="annotations-aspectmembers.html" title="Annotating Aspects"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. Annotations</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="join-point-matching-summary.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="annotations-aspectmembers.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="annotations"></a>Chapter 2. Annotations</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="annotations.html#annotations-inJava5">Annotations in Java 5</a></span></dt><dd><dl><dt><span class="sect2"><a href="annotations.html#using-annotations">Using Annotations</a></span></dt><dt><span class="sect2"><a href="annotations.html#retention-policies">Retention Policies</a></span></dt><dt><span class="sect2"><a href="annotations.html#accessing-annotations-at-runtime">Accessing Annotations at Runtime</a></span></dt><dt><span class="sect2"><a href="annotations.html#annotation-inheritance">Annotation Inheritance</a></span></dt></dl></dd><dt><span class="sect1"><a href="annotations-aspectmembers.html">Annotating Aspects</a></span></dt><dt><span class="sect1"><a href="annotations-pointcuts-and-advice.html">Join Point Matching based on Annotations</a></span></dt><dd><dl><dt><span class="sect2"><a href="annotations-pointcuts-and-advice.html#annotation-patterns">Annotation Patterns</a></span></dt><dt><span class="sect2"><a href="annotations-pointcuts-and-advice.html#type-patterns">Type Patterns</a></span></dt><dt><span class="sect2"><a href="annotations-pointcuts-and-advice.html#signaturePatterns">Signature Patterns</a></span></dt><dt><span class="sect2"><a href="annotations-pointcuts-and-advice.html#example-pointcuts">Example Pointcuts</a></span></dt><dt><span class="sect2"><a href="annotations-pointcuts-and-advice.html#runtime-type-matching-and-context-exposure">Runtime type matching and context exposure</a></span></dt><dt><span class="sect2"><a href="annotations-pointcuts-and-advice.html#package-and-parameter-annotations">Package and Parameter Annotations</a></span></dt><dt><span class="sect2"><a href="annotations-pointcuts-and-advice.html#annotation-inheritance-and-pointcut-matching">Annotation Inheritance and pointcut matching</a></span></dt><dt><span class="sect2"><a href="annotations-pointcuts-and-advice.html#matchingOnAnnotationValues">Matching based on annotation values</a></span></dt></dl></dd><dt><span class="sect1"><a href="annotations-decp.html">Using Annotations with declare statements</a></span></dt><dd><dl><dt><span class="sect2"><a href="annotations-decp.html#declare-error-and-declare-warning">Declare error and declare warning</a></span></dt><dt><span class="sect2"><a href="annotations-decp.html#declare-parents">declare parents</a></span></dt><dt><span class="sect2"><a href="annotations-decp.html#declare-precedence">declare precedence</a></span></dt></dl></dd><dt><span class="sect1"><a href="annotations-declare.html">Declare Annotation</a></span></dt><dt><span class="sect1"><a href="annotations-itds.html">Inter-type Declarations</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="annotations-inJava5"></a>Annotations in Java 5</h2></div></div></div><p>
This section provides the essential information about annotations in
Java 5 needed to understand how annotations are treated in AspectJ 5.
For a full introduction to annotations in Java, please see the
documentation for the Java 5 SDK.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="using-annotations"></a>Using Annotations</h3></div></div></div><p>
Java 5 introduces <span class="emphasis"><em>annotation types</em></span> which can
be used to express metadata relating to program members in the
form of <span class="emphasis"><em>annotations</em></span>. Annotations in Java 5
can be applied to package and type declarations (classes,
interfaces, enums, and annotations), constructors, methods,
fields, parameters, and variables. Annotations are specified in the
program source by using the <code class="literal">@</code> symbol. For example,
the following piece of code uses the <code class="literal">@Deprecated</code>
annotation to indicate that the <code class="literal">obsoleteMethod()</code>
has been deprecated:
</p><pre class="programlisting">
@Deprecated
public void obsoleteMethod() { ... }
</pre><p>
Annotations may be <span class="emphasis"><em>marker annotations</em></span>,
<span class="emphasis"><em>single-valued annotations</em></span>, or
<span class="emphasis"><em>multi-valued annotations</em></span>.
Annotation types with no members or that provide default values
for all members may be used simply as marker annotations, as in
the deprecation example above. Single-value annotation types have
a single member, and the annotation may be written in one of
two equivalent forms:
</p><pre class="programlisting">
@SuppressWarnings({"unchecked"})
public void someMethod() {...}
</pre><p>
or
</p><pre class="programlisting">
@SuppressWarnings(value={"unchecked"})
public void someMethod() {...}
</pre><p>
Multi-value annotations must use the <code class="literal">member-name=value
</code> syntax to specify annotation values. For example:
</p><pre class="programlisting">
@Authenticated(role="supervisor",clearanceLevel=5)
public void someMethod() {...}
</pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="retention-policies"></a>Retention Policies</h3></div></div></div><p>
Annotations can have one of three retention policies:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Source-file retention</span></dt><dd><p>
Annotations with source-file retention are read by the
compiler during the compilation process, but are not
rendered in the generated <code class="literal">.class</code> files.
</p></dd><dt><span class="term">Class-file retention</span></dt><dd><p>
This is the default retention policy. Annotations
with class-file retention are read by the compiler
and also retained in the generated <code class="literal">
.class</code> files.
</p></dd><dt><span class="term">Runtime retention</span></dt><dd><p>
Annotations with runtime retention are read by the
compiler, retained in the generated <code class="literal">
.class</code> files, and also made available
at runtime.
</p></dd></dl></div><p>Local variable annotations are not retained in class files (or at runtime)
regardless of the retention policy set on the annotation type. See JLS 9.6.1.2.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="accessing-annotations-at-runtime"></a>Accessing Annotations at Runtime</h3></div></div></div><p>
Java 5 supports a new interface,
<code class="literal">java.lang.reflect.AnnotatedElement</code>, that is
implemented by the reflection classes in Java (<code class="literal">Class</code>,
<code class="literal">Constructor</code>,
<code class="literal">Field</code>, <code class="literal">Method</code>, and
<code class="literal">Package</code>). This interface gives you access
to annotations <span class="emphasis"><em>that have runtime retention</em></span> via
the <code class="literal">getAnnotation</code>, <code class="literal">getAnnotations</code>,
and <code class="literal">isAnnotationPresent</code>. Because annotation types are
just regular Java classes, the annotations returned by these methods
can be queried just like any regular Java object.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="annotation-inheritance"></a>Annotation Inheritance</h3></div></div></div><p>
It is important to understand the rules relating to inheritance of
annotations, as these have a bearing on join point matching
based on the presence or absence of annotations.
</p><p>
By default annotations are <span class="emphasis"><em>not</em></span> inherited. Given
the following program
</p><pre class="programlisting">
@MyAnnotation
class Super {
@Oneway public void foo() {}
}
class Sub extends Super {
public void foo() {}
}
</pre><p>
Then <code class="literal">Sub</code> <span class="emphasis"><em>does not</em></span> have
the <code class="literal">MyAnnotation</code> annotation, and
<code class="literal">Sub.foo()</code> is not an <code class="literal">@Oneway</code>
method, despite the fact that it overrides
<code class="literal">Super.foo()</code> which is.
</p><p>
If an annotation type has the meta-annotation <code class="literal">@Inherited</code>
then an annotation of that type on a <span class="emphasis"><em>class</em></span> will cause
the annotation to be inherited by sub-classes. So, in the example
above, if the <code class="literal">MyAnnotation</code> type had the
<code class="literal">@Inherited</code> attribute, then <code class="literal">Sub</code>
would have the <code class="literal">MyAnnotation</code> annotation.
</p><p>
<code class="literal">@Inherited</code> annotations are not inherited when used to
annotate anything other than a type. A type
that implements one or more interfaces never inherits any annotations from
the interfaces it implements.
</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="join-point-matching-summary.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="annotations-aspectmembers.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Summary of Join Point Matching </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Annotating Aspects</td></tr></table></div></body></html>
|