Package org.apache.xmlbeans.impl.jam

Interface JClass

  • All Superinterfaces:
    JAnnotatedElement, JElement, JMember
    All Known Subinterfaces:
    MClass
    All Known Implementing Classes:
    ArrayClassImpl, BuiltinClassImpl, ClassImpl, PrimitiveClassImpl, UnresolvedClassImpl, VoidClassImpl
    public interface JClass
extends JMember

    Represents a Java class that may or may not be loaded in the VM. JClass is typically implemented in one of two ways: by wrapping a java.lang.Class or by parsing a source file directly with a tool such as javadoc or javelin.

    If a JClass represents an inner class, its getParent() method returns the outer class. Otherwise, it returns the containing package.

    Important Note: Because JAM's classloading machinery may swap instances of JClass out of memory at any time, you should never rely on instance equality (i.e., '==') when comparing two JClasses. To illustrate: it is possible (though rather unlikely) that that the following expression will evaluate to false

    JMethod myJMethod = ... myJMethod.getReturnType() == myJMethod.getReturnType()

    Instead, you should always use equals()

    myJMethod.getReturnType().equals(myJMethod.getReturnType())

    REVIEW a bunch of these methods (getMethods, getConstructors...) could throw SecurityException if the JClass is backed by java.lang.Class (see javadocs for Class). We're currently ignoring this, because it seems unlikely and it seems heavyweight. Seems ok?

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      boolean equals​(java.lang.Object o)
      Two JClasses are always considered equal as long as their qualified names are the same.
      JClass forName​(java.lang.String name)
      Shorthand for myClass.getClassLoader().loadClass(name)
      JClass getArrayComponentType()
      Returns the Class representing the component type of an array.
      int getArrayDimensions()
      If this JClass represents an array type (isArray() == true), returns the number of dimensions in the array.
      JClass[] getClasses()
      Returns an unordered array containing the inner classes for this class.
      JamClassLoader getClassLoader()
      Returns the JamClassLoader which loaded this class.
      JConstructor[] getConstructors()
      Returns an unordered array containing Constructor objects reflecting all the public constructors of the class represented by this Class object.
      JClass getContainingClass()
      If this JClass is an inner class, returns the outer class.
      JPackage getContainingPackage()
      Returns a JPackage which represents the package which contains this JClass.
      JField[] getDeclaredFields()
      Returns an unordered array of Field objects reflecting all the fields declared by the class or interface represented by this Class object.
      JMethod[] getDeclaredMethods()
      Returns an unordered array of Method objects reflecting all the methods declared by the class or interface represented by this Class object.
      JProperty[] getDeclaredProperties()
      Like getProperties(), but only considers methods explicitly declared on this class in identifying the properties.
      java.lang.String getFieldDescriptor()
      Returns the name of this member in the format described in section 4.3.2 of the VM spec, 'Field Descriptors.' This is the same nasty format returned by java.lang.Class.getName(), and is the format you need to use in calls to Class.forName().
      JField[] getFields()
      REVIEW should we consider renaming this to getAllFields()? I think this makes it more clear but is not consistent with java.lang.Class.
      JClass[] getImportedClasses()
      Returns an unordered array of classes that were explicitly imported by this class using an import statement.
      JPackage[] getImportedPackages()
      Returns an unordered set of JPackages which are imported by this class using a package import statement (i.e.
      JClass[] getInterfaces()
      Returns an unordered array containing all of the interfaces directly implemented by this class.
      JMethod[] getMethods()
      REVIEW should we consider renaming this to getAllMethods()? I think this makes it more clear but is not consistent with java.lang.Class.
      java.lang.Class getPrimitiveClass()
      If this JClass represents a primitive (isPrimitiveType() returns true), this method returns the java.lang.Class representing the class of the primitive.
      JProperty[] getProperties()
      Returns a representation of a java bean property as detailed in section 8.3 of the Java Beans specification, 'Design Patterns for Properties.' A JProperty can be thought of as a union of a getter method and corresponding setter method, although only one of these is required (view-only and write-only properties are returned).
      JClass getSuperclass()
      Returns the Class representing the superclass of the entity (class, interface, primitive type or void) represented by this Class.
      boolean isAbstract()
      Return true if this class is abstract.
      boolean isAnnotationType()
      Returns true if this JClass represents a JSR175 annotation type.
      boolean isArrayType()
      Returns true if this JClass represents an array type.
      boolean isAssignableFrom​(JClass clazz)
      Determines if the class or interface represented by this Class object is either the same as, or is a superclass or superinterface of, the class or interface represented by the specified Class parameter.
      boolean isBuiltinType()
      Returns true if this class is a builtin type.
      boolean isEnumType()
      Returns true if this class is an enumerated type.
      boolean isFinal()
      Return true if this class is final.
      boolean isInterface()
      Returns true if this JClass represents an interface.
      boolean isObjectType()
      Returns true if this JClass represents java.lang.Object.
      boolean isPrimitiveType()
      Return true if this JClass represents primitive type (int, long, double, and so forth).
      boolean isStatic()
      Return true if this class is static.
      boolean isUnresolvedType()
      Returns true if a backing entity for this class could not be resolved.
      boolean isVoidType()
      Returns true if this JClass represents the void type.

    • Method Detail

      • getContainingPackage

        JPackage getContainingPackage()

        Returns a JPackage which represents the package which contains this JClass.

      • getSuperclass

        JClass getSuperclass()

        Returns the Class representing the superclass of the entity (class, interface, primitive type or void) represented by this Class. If this Class represents either the Object class, an interface, a primitive type, or void, then null is returned. If this object represents an array class then the Class object representing the Object class is returned.

      • getInterfaces

        JClass[] getInterfaces()
        Returns an unordered array containing all of the interfaces directly implemented by this class. Returns an empty array if no interfaces are implemented. REVIEW we probably want getInterfaces and getDeclaredInterfaces.

      • getFields

        JField[] getFields()

        REVIEW should we consider renaming this to getAllFields()? I think this makes it more clear but is not consistent with java.lang.Class.

        Returns an unordered array containing Field objects reflecting all the accessible public fields of the class or interface represented by this Class object. The elements2 in the array returned are not sorted and are not in any particular order. This method returns an array of length 0 if the class or interface has no accessible public fields, or if it represents an array class, a primitive type, or void.

        Specifically, if this JClass object represents a class, this method returns the public fields of this class and of all its superclasses. If this JClass object represents an interface, this method returns the fields of this interface and of all its superinterfaces.

        The implicit length field for array class is not reflected by this method. User code should use the methods of class Array to manipulate arrays.

        Note that no guarantees are made about the ordering of fields in this array.

        See The Java Language Specification, sections 8.2 and 8.3.

      • getDeclaredFields

        JField[] getDeclaredFields()

        Returns an unordered array of Field objects reflecting all the fields declared by the class or interface represented by this Class object. This includes public, protected, default (package) access, and private fields, but excludes inherited fields. The elements2 in the array returned are not sorted and are not in any particular order. This method returns an array of length 0 if the class or interface declares no fields, or if this Class object represents a primitive type, an array class, or void.

        See The Java Language Specification, sections 8.2 and 8.3.

      • getMethods

        JMethod[] getMethods()

        REVIEW should we consider renaming this to getAllMethods()? I think this makes it more clear but is not consistent with java.lang.Class.

        Returns an array containing Method objects reflecting all the public member methods of the class or interface represented by this Class object, including those declared by the class or interface and and those inherited from superclasses and superinterfaces. The elements2 in the array returned are not sorted and are not in any particular order. This method returns an array of length 0 if this Class object represents a class or interface that has no public member methods, or if this Class object represents an array class, primitive type, or void.

        The class initialization method is not included in the returned array. If the class declares multiple public member methods with the same parameter types, they are all included in the returned array.

      • getDeclaredMethods

        JMethod[] getDeclaredMethods()

        Returns an unordered array of Method objects reflecting all the methods declared by the class or interface represented by this Class object. This includes public, protected, default (package) access, and private methods, but excludes inherited methods. The elements2 in the array returned are not sorted and are not in any particular order. This method returns an array of length 0 if the class or interface declares no methods, or if this Class object represents a primitive type, an array class, or void. The class initialization method is not included in the returned array. If the class declares multiple public member methods with the same parameter types, they are all included in the returned array.

        See The Java Language Specification, section 8.2.

      • getConstructors

        JConstructor[] getConstructors()

        Returns an unordered array containing Constructor objects reflecting all the public constructors of the class represented by this Class object. An array of length 0 is returned if the class has no public constructors, or if the class is an array class, or if the class reflects a primitive type or void.

      • getProperties

        JProperty[] getProperties()
        Returns a representation of a java bean property as detailed in section 8.3 of the Java Beans specification, 'Design Patterns for Properties.' A JProperty can be thought of as a union of a getter method and corresponding setter method, although only one of these is required (view-only and write-only properties are returned). Note that public fields are never considered properties, as deetailed in the specification.

      • getDeclaredProperties

        JProperty[] getDeclaredProperties()

        Like getProperties(), but only considers methods explicitly declared on this class in identifying the properties.

      • isInterface

        boolean isInterface()

        Returns true if this JClass represents an interface.

      • isAnnotationType

        boolean isAnnotationType()

        Returns true if this JClass represents a JSR175 annotation type.

      • isPrimitiveType

        boolean isPrimitiveType()
        Return true if this JClass represents primitive type (int, long, double, and so forth). Remember that primitive wrapper classes such as java.lang.Integer are NOT considered primitives.

      • isBuiltinType

        boolean isBuiltinType()
        Returns true if this class is a builtin type. This is true if any of the following returns true: isPrimitive(), isArray(), isVoid(), or isUnresolved..
        Returns:

      • getPrimitiveClass

        java.lang.Class getPrimitiveClass()

        If this JClass represents a primitive (isPrimitiveType() returns true), this method returns the java.lang.Class representing the class of the primitive. For example, JClass representing an integer returns the equivalent of 'int.class' or 'java.lang.Integer.type.'

        Returns:
        The primitive class, or null if this is JClass is not primitive.

      • isFinal

        boolean isFinal()
        Return true if this class is final.

      • isStatic

        boolean isStatic()
        Return true if this class is static. Note that top-level classes are never static.

      • isAbstract

        boolean isAbstract()
        Return true if this class is abstract.

      • isVoidType

        boolean isVoidType()

        Returns true if this JClass represents the void type.

      • isObjectType

        boolean isObjectType()

        Returns true if this JClass represents java.lang.Object.

      • isArrayType

        boolean isArrayType()

        Returns true if this JClass represents an array type.

      • getArrayComponentType

        JClass getArrayComponentType()

        Returns the Class representing the component type of an array. If this JClass does not represent an array class this method returns null.

        Note that this method differs substantially from java.lang.Class.getComponentType() in the way it treats multidimensional arrays. Specifically, let fooArrayClass be the class of an n dimensional array of class foo for n > 2. For the java.lang.Class representation of fooArrayClass, getComponentType() will return a java.lang.Class for an (n-1)-dimensional array of foos. By contrast, the JClass representation of fooArrayClass will always simply return a JClass representing foo for any value of n > 1.

        In other words, this method always returns the 'core' type of the array, effectively hiding away all of the intermediary array types. Given that JClass provides the additional getArrayDimensions facility, it is felt that this is a much easier convention for tool authors to work with.

      • getArrayDimensions

        int getArrayDimensions()

        If this JClass represents an array type (isArray() == true), returns the number of dimensions in the array. Otherwise returns zero.

      • isAssignableFrom

        boolean isAssignableFrom​(JClass clazz)

        Determines if the class or interface represented by this Class object is either the same as, or is a superclass or superinterface of, the class or interface represented by the specified Class parameter. It returns true if so; otherwise it returns false. If this Class object represents a primitive type, this method returns true if the specified Class parameter is exactly this Class object; otherwise it returns false.

        Specifically, this method tests whether the type represented by the specified Class parameter can be converted to the type represented by this Class object via an identity conversion or via a widening reference conversion. See The Java Language Specification, sections 5.1.1 and 5.1.4 , for details.

      • equals

        boolean equals​(java.lang.Object o)
        Two JClasses are always considered equal as long as their qualified names are the same.
        Overrides:
        equals in class java.lang.Object

      • getClasses

        JClass[] getClasses()

        Returns an unordered array containing the inner classes for this class. The array contains JClass objects representing all the public classes and interfaces that are members of the class represented by this JClass. This includes public class and interface members inherited from superclasses and public class and interface members declared by the class. This method returns an array of length 0 if this Class object has no public member classes or interfaces. This method also returns an array of length 0 if this JClass object represents a primitive type, an array class, or void.

        Note that no guarantees are made about the ordering of classes in this array.

      • getContainingClass

        JClass getContainingClass()

        If this JClass is an inner class, returns the outer class. If the class or interface represented by this JClass object is a member of another class, returns the JClass object representing the class in which it was declared. This method returns null if this class or interface is not a member of any other class. If this JClass object represents an array class, a primitive type, or void, then this method returns null.

        Specified by:
        getContainingClass in interface JMember

      • getFieldDescriptor

        java.lang.String getFieldDescriptor()

        Returns the name of this member in the format described in section 4.3.2 of the VM spec, 'Field Descriptors.' This is the same nasty format returned by java.lang.Class.getName(), and is the format you need to use in calls to Class.forName(). For example, the ClassfileName of the class of a two-dimensional array of strings is [[Ljava.lang.String;. For details, see http://java.sun.com/docs/books/vmspec/2nd-edition/html/ClassFile.doc.html

      • isEnumType

        boolean isEnumType()

        Returns true if this class is an enumerated type.

      • getClassLoader

        JamClassLoader getClassLoader()

        Returns the JamClassLoader which loaded this class.

      • forName

        JClass forName​(java.lang.String name)
        Shorthand for myClass.getClassLoader().loadClass(name)

      • getImportedClasses

        JClass[] getImportedClasses()

        Returns an unordered array of classes that were explicitly imported by this class using an import statement. It does not include any classes that might be imported via package imports (i.e. with the '*' wildcard), nor does it include any classes that are simply used via fully-qualified name in the body of this class.

        Note that this is an optional operation; if the source for the class is not available (i.e. this JClass is backed by a java.lang.Class), then this method will return an array of length 0.

      • getImportedPackages

        JPackage[] getImportedPackages()

        Returns an unordered set of JPackages which are imported by this class using a package import statement (i.e. with the '*' wildcard), as well as the containing packages of all of the JClasses returned by getImportedClasses().

        Note that this is an optional operation; if the source for the class is not available (i.e. this JClass is backed by a java.lang.Class), then this method will return an array of length 0.

      • isUnresolvedType

        boolean isUnresolvedType()

        Returns true if a backing entity for this class could not be resolved. This will be true, for example, of the JClass which you get when requesting a method's return type when no class for that type can be found. In this case, the JClass will be have only a name - all other properties will be null/empty.