Interface Info
- All Known Subinterfaces:
ClassInfo
,FieldInfo
,MethodInfo
,PackageInfo
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 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.
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()
-
Method Summary
Modifier and TypeMethodDescriptiongetAnnotation
(Class<? extends Annotation> clazz) getAnnotation
(String annotationClassName) Answer the annotation of the receiver which has the specified name.Collection<? extends AnnotationInfo>
Answer the collection of annotations of the receiver.getDeclaredAnnotation
(Class<? extends Annotation> clazz) getDeclaredAnnotation
(String annotationClassName) Answer the declared annotation of the receiver which has the specified name.Collection<? extends AnnotationInfo>
Answer the collection of annotations of the receiver.Answer a print string for the receiver, for use in debugging.Answer the store which holds this info object.int
Answer an integer encoding the modifiers (for example,public
,protected
, orprivate
) of the receiver.getName()
Answer the name of the receiver.Answer the qualified name of the receiver.boolean
Tell if any direct annotations are present.boolean
isAnnotationPresent
(String annotationClassName) Tell if any annotation having the specified name is present.boolean
isAnnotationWithin
(Collection<String> annotationNames) Tell if any of the receiver's annotations is present in a set of annotations, testing by name.boolean
Tell if any immediate declared annotations are present.boolean
isDeclaredAnnotationPresent
(String annotationClassName) Tell if any declared annotation having the specified name is present.boolean
isDeclaredAnnotationWithin
(Collection<String> annotationNames) Tell if any of the receiver's declared annotations is present in a set of annotations, testing by name.boolean
Tell if this info object was declared with no modifier.boolean
Tell if this info object was declared with theprivate
modifier.boolean
Tell if this info object was declared with theprotected
modifier.boolean
isPublic()
Tell if this info object was declared with thepublic
modifier.void
log
(com.ibm.websphere.ras.TraceComponent logger) Log the receiver to the specified logger.
-
Method Details
-
getHashText
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.
- Returns:
- A print string for the receiver.
-
log
void log(com.ibm.websphere.ras.TraceComponent logger) Log the receiver to the specified logger.
- Parameters:
logger
- The logger to receive the display of the receiver.
-
getInfoStore
InfoStore getInfoStore()Answer the store which holds this info object.
- Returns:
- The store which holds this info object.
-
getModifiers
int getModifiers()Answer an integer encoding the modifiers (for example,
public
,protected
, orprivate
) of the receiver. The integer encoding uses the bit-field values defined byModifier
.- Returns:
- The integer encoding the receiver's modifiers.
- See Also:
-
isPublic
boolean isPublic()Tell if this info object was declared with the
public
modifier.- Returns:
- True if this info object was declared as public. Otherwise, false.
- See Also:
-
isProtected
boolean isProtected()Tell if this info object was declared with the
protected
modifier.- Returns:
- True if this info object was declared as protected. Otherwise, false.
- See Also:
-
isPrivate
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.
- Returns:
- True if this info object was declared as private. Otherwise, false.
- See Also:
-
isPackagePrivate
boolean isPackagePrivate()Tell if this info object was declared with no modifier.
- Returns:
- True if this info object was declared as package private. Otherwise, false.
- See Also:
-
getName
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.
- Returns:
- The name of the receiver.
- See Also:
-
getQualifiedName
String getQualifiedName()Answer the qualified name of the receiver. This is the same as the regular name, with two specific exceptions:
- For fields, the qualified name is the class name plus "." plus the field name.
- For methods, the qualified name is the class name plus "." plus the method name.
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.
- Returns:
- The qualified name of the receiver.
-
isDeclaredAnnotationPresent
boolean isDeclaredAnnotationPresent()Tell if any immediate declared annotations are present.
- Returns:
- True if any direct declared annotation is present. Otherwise, false.
-
getDeclaredAnnotations
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.
- Returns:
- The collection of annotations of the receiver.
-
isDeclaredAnnotationPresent
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.
- Parameters:
annotationClassName
- The name of the annotation to detect.- Returns:
- True if any declared annotation having the specified name is present. Otherwise, false.
-
getDeclaredAnnotation
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.
- Parameters:
annotationClassName
- The name of the declared annotation to retrieve.- Returns:
- The declared annotation of the receiver having the specified name. Null if no matching annotation is present.
-
getDeclaredAnnotation
-
isDeclaredAnnotationWithin
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.
- Parameters:
annotationNames
- The names of annotations to test against.- Returns:
- True if any of the receiver's declared annotations is in the selection set. Otherwise, false.
-
isAnnotationPresent
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.
- Returns:
- True if any declared annotation is present. Otherwise, false.
-
getAnnotations
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.
- Returns:
- The collection of annotations of the receiver.
-
isAnnotationPresent
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.
- Parameters:
annotationClassName
- The name of the annotation to detect.- Returns:
- True if any annotation having the specified name is present. Otherwise, false.
-
getAnnotation
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.
- Parameters:
annotationClassName
- The name of the annotation to retrieve.- Returns:
- The annotation of the receiver having the specified name. Null if no matching annotation is present.
-
getAnnotation
-
isAnnotationWithin
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.
- Parameters:
annotationNames
- The names of annotations to test against.- Returns:
- True if any of the receiver's annotations is in the selection set. Otherwise, false.
-