Package com.ibm.wsspi.anno.info

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 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 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, or private) of the receiver. The integer encoding uses the bit-field values defined by Modifier.

      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

      boolean isDeclaredAnnotationPresent(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(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(Class<? extends Annotation> clazz)

    • isDeclaredAnnotationWithin

      boolean isDeclaredAnnotationWithin(Collection<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

      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(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(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(Class<? extends Annotation> clazz)

    • isAnnotationWithin

      boolean isAnnotationWithin(Collection<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.