IAnnotatedElement Interface
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Represents an annotated element of the program currently running in this VM.
[Android.Runtime.Register("java/lang/reflect/AnnotatedElement", "", "Java.Lang.Reflect.IAnnotatedElementInvoker")]
public interface IAnnotatedElement : Android.Runtime.IJavaObject, IDisposable, Java.Interop.IJavaPeerable[<Android.Runtime.Register("java/lang/reflect/AnnotatedElement", "", "Java.Lang.Reflect.IAnnotatedElementInvoker")>]
type IAnnotatedElement = interface
interface IJavaObject
interface IDisposable
interface IJavaPeerable- Derived
- Attributes
- Implements
Remarks
Represents an annotated element of the program currently running in this VM. This interface allows annotations to be read reflectively. All annotations returned by methods in this interface are immutable and serializable. The arrays returned by methods of this interface may be modified by callers without affecting the arrays returned to other callers.
Android note: methods that return multiple annotations of different types such as #getAnnotations() and #getDeclaredAnnotations() can be affected by the explicit character-code ordering of annotations types specified by the DEX format. Annotations of different types on a single element are not guaranteed to be returned in the order they are declared in source.
The #getAnnotationsByType(Class) and #getDeclaredAnnotationsByType(Class) methods support multiple annotations of the same type on an element. If the argument to either method is a repeatable annotation type (JLS 9.6), then the method will "look through" a container annotation (JLS 9.7), if present, and return any annotations inside the container. Container annotations may be generated at compile-time to wrap multiple annotations of the argument type.
The terms <em>directly present</em>, <em>indirectly present</em>, <em>present</em>, and <em>associated</em> are used throughout this interface to describe precisely which annotations are returned by methods:
<ul>
<li> An annotation A is <em>directly present</em> on an element E if E is annotated by A in the original source.
<li>An annotation A is <em>indirectly present</em> on an element E if E is annotated by a container annotation of A.
<li>An annotation A is present on an element E if either:
<ul>
<li>A is directly present on E; or
<li>No annotation of A 's type is directly present on E, and E is a class, and A 's type is inheritable, and A is present on the superclass of E.
</ul>
<li>An annotation A is <em>associated</em> with an element E if either:
<ul>
<li>A is directly or indirectly present on E; or
<li>No annotation of A 's type is directly or indirectly present on E, and E is a class, and A's type is inheritable, and A is associated with the superclass of E.
</ul>
</ul>
The table below summarizes which kind of annotation presence different methods in this interface examine.
<table class="plain"> <caption>Overview of kind of presence detected by different AnnotatedElement methods</caption> <thead> <tr><th colspan=2 scope="col">Method</th> <th colspan=4 scope="col">Kind of Presence</th> <tr><th scope="col">Return Type</th> <th scope="col">Signature</th> <th scope="col">Directly Present</th> <th scope="col">Indirectly Present</th> <th scope="col">Present</th> <th scope="col">Associated</th> </thead> <tbody> <tr><td style="text-align:right">T</td> <th scope="row" style="font-weight:normal; text-align:left">#getAnnotation(Class) getAnnotation(Class<T>)<td></td><td></td><td style="text-align:center">X</td><td></td> </tr> <tr><td style="text-align:right">Annotation[]</td> <th scope="row" style="font-weight:normal; text-align:left">#getAnnotations getAnnotations()<td></td><td></td><td style="text-align:center">X</td><td></td> </tr> <tr><td style="text-align:right">T[]</td> <th scope="row" style="font-weight:normal; text-align:left">#getAnnotationsByType(Class) getAnnotationsByType(Class<T>)<td></td><td></td><td></td><td style="text-align:center">X</td> </tr> <tr><td style="text-align:right">T</td> <th scope="row" style="font-weight:normal; text-align:left">#getDeclaredAnnotation(Class) getDeclaredAnnotation(Class<T>)<td style="text-align:center">X</td><td></td><td></td><td></td> </tr> <tr><td style="text-align:right">Annotation[]</td> <th scope="row" style="font-weight:normal; text-align:left">#getDeclaredAnnotations getDeclaredAnnotations()<td style="text-align:center">X</td><td></td><td></td><td></td> </tr> <tr><td style="text-align:right">T[]</td> <th scope="row" style="font-weight:normal; text-align:left">#getDeclaredAnnotationsByType(Class) getDeclaredAnnotationsByType(Class<T>)<td style="text-align:center">X</td><td style="text-align:center">X</td><td></td><td></td> </tr> </tbody> </table>
For an invocation of get[Declared]AnnotationsByType( Class < T >), the order of annotations which are directly or indirectly present on an element E is computed as if indirectly present annotations on E are directly present on E in place of their container annotation, in the order in which they appear in the value element of the container annotation.
There are several compatibility concerns to keep in mind if an annotation type T is originally <em>not</em> repeatable and later modified to be repeatable.
The containing annotation type for T is TC.
<ul>
<li>Modifying T to be repeatable is source and binary compatible with existing uses of T and with existing uses of TC.
That is, for source compatibility, source code with annotations of type T or of type TC will still compile. For binary compatibility, class files with annotations of type T or of type TC (or with other kinds of uses of type T or of type TC) will link against the modified version of T if they linked against the earlier version.
(An annotation type TC may informally serve as an acting containing annotation type before T is modified to be formally repeatable. Alternatively, when T is made repeatable, TC can be introduced as a new type.)
<li>If an annotation type TC is present on an element, and T is modified to be repeatable with TC as its containing annotation type then:
<ul>
<li>The change to T is behaviorally compatible with respect to the get[Declared]Annotation(Class<T>) (called with an argument of T or TC) and get[Declared]Annotations() methods because the results of the methods will not change due to TC becoming the containing annotation type for T.
<li>The change to T changes the results of the get[Declared]AnnotationsByType(Class<T>) methods called with an argument of T, because those methods will now recognize an annotation of type TC as a container annotation for T and will "look through" it to expose annotations of type T.
</ul>
<li>If an annotation of type T is present on an element and T is made repeatable and more annotations of type T are added to the element:
<ul>
<li> The addition of the annotations of type T is both source compatible and binary compatible.
<li>The addition of the annotations of type T changes the results of the get[Declared]Annotation(Class<T>) methods and get[Declared]Annotations() methods, because those methods will now only see a container annotation on the element and not see an annotation of type T.
<li>The addition of the annotations of type T changes the results of the get[Declared]AnnotationsByType(Class<T>) methods, because their results will expose the additional annotations of type T whereas previously they exposed only a single annotation of type T.
</ul>
</ul>
If an annotation returned by a method in this interface contains (directly or indirectly) a Class-valued member referring to a class that is not accessible in this VM, attempting to read the class by calling the relevant Class-returning method on the returned annotation will result in a TypeNotPresentException.
Similarly, attempting to read an enum-valued member will result in a EnumConstantNotPresentException if the enum constant in the annotation is no longer present in the enum type.
If an annotation type T is (meta-)annotated with an @Repeatable annotation whose value element indicates a type TC, but TC does not declare a value() method with a return type of T[], then an exception of type java.lang.annotation.AnnotationFormatError is thrown.
Finally, attempting to read a member whose definition has evolved incompatibly will result in a java.lang.annotation.AnnotationTypeMismatchException or an java.lang.annotation.IncompleteAnnotationException.
Added in 1.5.
Java documentation for java.lang.reflect.AnnotatedElement.
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.
Properties
| Handle |
Gets the JNI value of the underlying Android object. (Inherited from IJavaObject) |
| JniIdentityHashCode |
Returns the value of |
| JniManagedPeerState |
State of the managed peer. (Inherited from IJavaPeerable) |
| JniPeerMembers |
Member access and invocation support. (Inherited from IJavaPeerable) |
| PeerReference |
Returns a JniObjectReference of the wrapped Java object instance. (Inherited from IJavaPeerable) |
Methods
| Disposed() |
Called when the instance has been disposed. (Inherited from IJavaPeerable) |
| DisposeUnlessReferenced() |
If there are no outstanding references to this instance, then
calls |
| Finalized() |
Called when the instance has been finalized. (Inherited from IJavaPeerable) |
| GetAnnotation(Class) |
Returns this element's annotation for the specified type if such an annotation is <em>present</em>, else null. |
| GetAnnotations() |
Returns annotations that are <em>present</em> on this element. |
| GetAnnotationsByType(Class) |
Returns annotations that are <em>associated</em> with this element. |
| GetDeclaredAnnotation(Class) |
Returns this element's annotation for the specified type if such an annotation is <em>directly present</em>, else null. |
| GetDeclaredAnnotations() |
Returns annotations that are <em>directly present</em> on this element. |
| GetDeclaredAnnotationsByType(Class) |
Returns this element's annotation(s) for the specified type if such annotations are either <em>directly present</em> or <em>indirectly present</em>. |
| IsAnnotationPresent(Class) |
Returns true if an annotation for the specified type is <em>present</em> on this element, else false. |
| SetJniIdentityHashCode(Int32) |
Set the value returned by |
| SetJniManagedPeerState(JniManagedPeerStates) | (Inherited from IJavaPeerable) |
| SetPeerReference(JniObjectReference) |
Set the value returned by |
| UnregisterFromRuntime() |
Unregister this instance so that the runtime will not return it from future Java.Interop.JniRuntime+JniValueManager.PeekValue invocations. (Inherited from IJavaPeerable) |
Extension Methods
| JavaCast<TResult>(IJavaObject) |
Performs an Android runtime-checked type conversion. |
| JavaCast<TResult>(IJavaObject) | |
| GetJniTypeName(IJavaPeerable) | |