public interface Info
Base class for info objects.
The purpose of the class information layer is to represent java objects (packages, classes, methods, and fields), and to provide a way to associate annotations to those java objects.
The layer provides data structures that are very similar to structures provided by java reflection. However, the implementation avoids java class resolution, and is tuned for fast and efficient annotation processing.
Several types are provided that represent java objects -- as a replacement for java reflection:
PackageInfo
ClassInfo
MethodInfo
FieldInfo
Several types are provided that represent annotations and annotation values:
AnnotationInfo
AnnotationValue
A single type is provided to represent a simplified method descriptor. This is used for fast method lookups:
MethodInfoDescriptorInterface
A number of implementation details are surfaced through the interface. That is, classes are further typed as array and primitive classes. Also, the class interface exposes limited knowledge of the persistence state of a particular class, as expressed through proxy and non-proxy classes.
Several operations provide parameter based variations. Most typical,
an operation may provide a variation that accepts a string parameter,
another variation that accepts a class object parameter, and a third variation
that access a java class parameter. For example, isAnnotationPresent(String)
, #isAnnotationPresent(ClassInfo), and {@link #isAnnotationPresent(Class)}.
These are related by name. That is, the following are equivalent:
isAnnotationPresent( "javax.ejb.EJB" );
isAnnotationPresent( classInfo.getName() );
isAnnotationPresent( javax.ejb.EJB.class.getName() );
That is, if classInfo
is the class object for the class
javax.ejb.EJB
.
Any info object, including annotation objects, may have annotations. In addition, class objects may have annotations through their methods and fields. An info object may have annotations which were declared on that object, and may have annotations which are present by annotation inheritance.
Model notes:
On the relationship of info objects to their annotations:
[ Info ] 1 -> * [ AnnotationInfo ] I.getDeclaredAnnotations() A.getDeclaringInfo() [ Info ] + -> * [ AnnotationInfo ] I.getAnnotations() A.getFoundInfo()
That is, an info has two collections of annotations: A collection of declared annotations, and a collection of all annotations which apply to the info object.
Both relationships are bi-directional, with one difference. Each annotation has exactly one declaring info, but have one or more found info objects.
The declaring info object is always one of the found info objects. Additional found info objects arise because of class inheritance, and because of JSR250 application of class annotations to fields and methods.
I.isDeclaredAnnotationPresent() I.isAnnotationPresent()
These have a meaning which will be described when the relationship between classes, fields, and methods, is described.
On the hierarchy of info object types:
[ Info ] [ PackageInfo ] [ ClassInfo ] [ MethodInfo ] [ FieldInfo ] [ ClassInfo ] [ PrimitiveClassInfo ] [ ArrayClassInfo ] [ NonDelayedClassInfo ] [ DelayedClassInfo ]
That is, an info may for a package, a class, a method, or a field. A class may be a primitive class, an array class, or either of a non-delayed class or a delayed class.
Non-delayed and delayed classes represent the same class objects, so that this representation provides only three different types of classes: primitive, array, and "other classes not primitive classes or array classes".
Here a class info object may represent either a java interface, or a java class.
[ ClassInfo ] 1 -> * [ MethodInfo ] C.getDeclaredMethods() M.getDeclaringClass() [ ClassInfo ] + -> * [ MethodInfo ] C.getMethods() M.getFoundClasses()
That is, a class has a (possibly empty) collection of declared methods, and a (possibly empty) collection of methods, which, depending on whether the class info object represents a java interface or a java class, includes either the declared methods plus the declared methods of all super-interfaces (when the class info object represents a java interface), or includes the declared methods plus the declared methods of all super-classes (when the class info object represents a java class).
A key point is that a method has exactly one declaring class, and one or more found classes, corresponding to the classes into which the method is inherited.
The situation for fields is exactly analogous, and is present with no further discussion:
[ ClassInfo ] 1 -> * [ FieldInfo ] C.getDeclaredFields() F.getDeclaringClass() [ ClassInfo ] + -> * [ FieldInfo ] C.getFields() F.getFoundClasses()
As info type objects, methods and fields may have annotations, and whether a class has any annotations, including both annotations on the class itself, and including annotations on fields or methods of the class, is a useful property to know. That leads to several new operations:
C.isMethodAnnotationPresent() C.isFieldAnnotationPresent()
Modifier and Type | Method and Description |
---|---|
AnnotationInfo |
getAnnotation(java.lang.Class<? extends java.lang.annotation.Annotation> clazz) |
AnnotationInfo |
getAnnotation(java.lang.String annotationClassName)
Answer the annotation of the receiver which has the specified name.
|
java.util.Collection<? extends AnnotationInfo> |
getAnnotations()
Answer the collection of annotations of the receiver.
|
AnnotationInfo |
getDeclaredAnnotation(java.lang.Class<? extends java.lang.annotation.Annotation> clazz) |
AnnotationInfo |
getDeclaredAnnotation(java.lang.String annotationClassName)
Answer the declared annotation of the receiver which has the specified
name.
|
java.util.Collection<? extends AnnotationInfo> |
getDeclaredAnnotations()
Answer the collection of annotations of the receiver.
|
java.lang.String |
getHashText()
Answer a print string for the receiver, for use in debugging.
|
InfoStore |
getInfoStore()
Answer the store which holds this info object.
|
int |
getModifiers()
Answer an integer encoding the modifiers (for example,
public , protected , or private )
of the receiver. |
java.lang.String |
getName()
Answer the name of the receiver.
|
java.lang.String |
getQualifiedName()
Answer the qualified name of the receiver.
|
boolean |
isAnnotationPresent()
Tell if any direct annotations are present.
|
boolean |
isAnnotationPresent(java.lang.String annotationClassName)
Tell if any annotation having the specified name is
present.
|
boolean |
isAnnotationWithin(java.util.Collection<java.lang.String> annotationNames)
Tell if any of the receiver's annotations is present in a set of
annotations, testing by name.
|
boolean |
isDeclaredAnnotationPresent()
Tell if any immediate declared annotations are present.
|
boolean |
isDeclaredAnnotationPresent(java.lang.String annotationClassName)
Tell if any declared annotation having the specified name is
present.
|
boolean |
isDeclaredAnnotationWithin(java.util.Collection<java.lang.String> annotationNames)
Tell if any of the receiver's declared annotations is present in a set of
annotations, testing by name.
|
boolean |
isPackagePrivate()
Tell if this info object was declared with no modifier.
|
boolean |
isPrivate()
Tell if this info object was declared with the
private modifier. |
boolean |
isProtected()
Tell if this info object was declared with the
protected modifier. |
boolean |
isPublic()
Tell if this info object was declared with the
public modifier. |
void |
log(com.ibm.websphere.ras.TraceComponent logger)
Log the receiver to the specified logger.
|
java.lang.String getHashText()
Answer a print string for the receiver, for use in debugging. The value is guaranteed to be unique during the lifetime of the receiver, and, for frequently created types, will be created on demand.
void log(com.ibm.websphere.ras.TraceComponent logger)
Log the receiver to the specified logger.
logger
- The logger to receive the display of the receiver.InfoStore getInfoStore()
Answer the store which holds this info object.
int getModifiers()
Answer an integer encoding the modifiers (for example,
public
, protected
, or private
)
of the receiver. The integer encoding uses the bit-field values
defined by java.lang.reflect.Modifier
.
java.lang.reflect.Modifier#PUBLIC
,
java.lang.reflect.Modifier#PRIVATE
,
java.lang.reflect.Modifier#PROTECTED
,
java.lang.reflect.Modifier#STATIC
,
java.lang.reflect.Modifier#FINAL
,
java.lang.reflect.Modifier#SYNCHRONIZED
,
java.lang.reflect.Modifier#VOLATILE
,
java.lang.reflect.Modifier#TRANSIENT
,
java.lang.reflect.Modifier#NATIVE
,
java.lang.reflect.Modifier#INTERFACE
,
java.lang.reflect.Modifier#ABSTRACT
,
java.lang.reflect.Modifier#STRICT
boolean isPublic()
Tell if this info object was declared with the public
modifier.
getModifiers()
,
java.lang.reflect.Modifiers#PUBLIC
boolean isProtected()
Tell if this info object was declared with the protected
modifier.
getModifiers()
,
java.lang.reflect.Modifiers#PROTECTED
boolean isPrivate()
Tell if this info object was declared with the private
modifier.
Particular rules apply for the inheritance of private fields or methods. While private fields and methods are not inherited per general java processing, there are cases where javaEE annotations processing is aware of annotations defined on private members on a superclass.
getModifiers()
,
java.lang.reflect.Modifiers#PRIVATE
boolean isPackagePrivate()
Tell if this info object was declared with no modifier.
getModifiers()
java.lang.String getName()
Answer the name of the receiver.
The name of a class, package, or annotation, is the same as the qualified name of the class or package. The name of a field or a method is the name within the enclosing class.
getQualifiedName()
java.lang.String getQualifiedName()
Answer the qualified name of the receiver. This is the same as the regular name, with two specific exceptions:
Qualified names provide unique IDs for packages, classes, methods, and fields. The names of annotations are the names of an annotation class, and are not unique.
boolean isDeclaredAnnotationPresent()
Tell if any immediate declared annotations are present.
java.util.Collection<? extends AnnotationInfo> getDeclaredAnnotations()
Answer the collection of annotations of the receiver.
This API does not provide the ability to update the retrieved collection of annotations.
boolean isDeclaredAnnotationPresent(java.lang.String annotationClassName)
Tell if any declared annotation having the specified name is present. (The name of an annotation is the name of the annotation class.
At most one annotation having the specified name may be present.
annotationClassName
- The name of the annotation to detect.AnnotationInfo getDeclaredAnnotation(java.lang.String annotationClassName)
Answer the declared annotation of the receiver which has the specified name.
At most one annotation having the specified name may be present.
Answer null if no matching annotation is found.
annotationClassName
- The name of the declared annotation to retrieve.AnnotationInfo getDeclaredAnnotation(java.lang.Class<? extends java.lang.annotation.Annotation> clazz)
boolean isDeclaredAnnotationWithin(java.util.Collection<java.lang.String> annotationNames)
Tell if any of the receiver's declared annotations is present in a set of annotations, testing by name.
This method is implemented to iterate across the receiver's annotations, not across the annotation names in the selection set. That tunes the implementation for cases where the expected number of annotations of the receiver is small compared to the number of annotations in the selection set.
annotationNames
- The names of annotations to test against.boolean isAnnotationPresent()
Tell if any direct annotations are present.
This test detects both declared annotations, and annotations which are present through field or method inheritance, or through annotation inheritance.
java.util.Collection<? extends AnnotationInfo> getAnnotations()
Answer the collection of annotations of the receiver.
This API does not provide the ability to update the retrieved collection of annotations.
boolean isAnnotationPresent(java.lang.String annotationClassName)
Tell if any annotation having the specified name is present. (The name of an annotation is the name of the annotation class.
At most one annotation having the specified name may be present.
annotationClassName
- The name of the annotation to detect.AnnotationInfo getAnnotation(java.lang.String annotationClassName)
Answer the annotation of the receiver which has the specified name.
At most one annotation having the specified name may be present.
Answer null if no matching annotation is found.
annotationClassName
- The name of the annotation to retrieve.AnnotationInfo getAnnotation(java.lang.Class<? extends java.lang.annotation.Annotation> clazz)
boolean isAnnotationWithin(java.util.Collection<java.lang.String> annotationNames)
Tell if any of the receiver's annotations is present in a set of annotations, testing by name.
This method is implemented to iterate across the receiver's annotations, not across the annotation names in the selection set. That tunes the implementation for cases where the expected number of annotations of the receiver is small compared to the number of annotations in the selection set.
annotationNames
- The names of annotations to test against.