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 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()
     
    • 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, 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.
    • 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, 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:
        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.