Interface Info
-
- All Known Subinterfaces:
ClassInfo
,FieldInfo
,MethodInfo
,PackageInfo
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)
, {@link #isAnnotationPresent(ClassInfo), and#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 classjavax.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()
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method 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
, orprivate
) 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 theprivate
modifier.boolean
isProtected()
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 Detail
-
getHashText
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.
- 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:
Modifier.PUBLIC
,Modifier.PRIVATE
,Modifier.PROTECTED
,Modifier.STATIC
,Modifier.FINAL
,Modifier.SYNCHRONIZED
,Modifier.VOLATILE
,Modifier.TRANSIENT
,Modifier.NATIVE
,Modifier.INTERFACE
,Modifier.ABSTRACT
,Modifier.STRICT
-
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:
getModifiers()
,java.lang.reflect.Modifiers#PUBLIC
-
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:
getModifiers()
,java.lang.reflect.Modifiers#PROTECTED
-
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:
getModifiers()
,java.lang.reflect.Modifiers#PRIVATE
-
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:
getModifiers()
-
getName
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.
- Returns:
- The name of the receiver.
- See Also:
getQualifiedName()
-
getQualifiedName
java.lang.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
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.
- Returns:
- The collection of annotations of the receiver.
-
isDeclaredAnnotationPresent
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.
- Parameters:
annotationClassName
- The name of the annotation to detect.- Returns:
- True if any declared annotation having the specified name is present. Otherwise, false.
-
getDeclaredAnnotation
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.
- 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
AnnotationInfo getDeclaredAnnotation(java.lang.Class<? extends java.lang.annotation.Annotation> clazz)
-
isDeclaredAnnotationWithin
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.
- 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
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.
- Returns:
- The collection of annotations of the receiver.
-
isAnnotationPresent
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.
- Parameters:
annotationClassName
- The name of the annotation to detect.- Returns:
- True if any annotation having the specified name is present. Otherwise, false.
-
getAnnotation
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.
- 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
AnnotationInfo getAnnotation(java.lang.Class<? extends java.lang.annotation.Annotation> clazz)
-
isAnnotationWithin
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.
- 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.
-
-