com.bea.util.jam
Interface JClass

All Superinterfaces:

JAnnotatedElement, JElement, JMember

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

Instead, you should always use equals()

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?

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..

getPrimitiveClass

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(Object o)

Two JClasses are always considered equal as long as their qualified names are the same.

Overrides:

equals in class 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

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(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.

getImportedStarPackages

JPackage[] getImportedStarPackages()

Returns an unordered set of JPackages which are imported by this class using a package import statement and if the pckages end with the '*' wildcard)

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.

getImports

JImport[] getImports()

Returns an unordered set of JImport which are imported by this class using a package import statement.

From the JImport, you can get more import information.

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.

isSourceAvailable

boolean isSourceAvailable()

Returns true if this JClass was populated from Java source. This lets you know whether comments will be viewiable, for example.

Specified by:

isSourceAvailable in interface JElement