harpoon.ClassFile
Class HClass

java.lang.Object
  harpoon.ClassFile.HClass

All Implemented Interfaces:

HType, Comparable<HClass>, ReferenceUnique

public abstract class HClass
extends Object
implements Comparable<HClass>, ReferenceUnique, HType

Instances of the class HClass represent classes and interfaces of a java program. Every array also belongs to a class that is reflected as a HClass object that is shared by all arrays with the same element type and number of dimensions. Finally, the primitive Java types (boolean, byte, char, short, int, long, float, and double) and the keyword void are also represented as HClass objects.

There is no public constructor for the class HClass. HClass objects are created with the forName, forDescriptor and forClass methods of Linker.

A note on mutability: HClass objects may be mutable. Of course, this is unpleasant for any attempt to cache the result of the expensive computations on such objects (e.g., getMethod(String,String)). If you are VERY familiar with Flex, you can use caching in the periods when HClasses are guaranteed not to be mutated. You just have to enter such a period (we call it immutability epoch) explicitly using HClass.enterImmutableEpoch() and end it using HClass.exitImmutableEpoch(). E.g.,

 HClass.enterImmutableEpoch();

  Big computation that does not mutate HClass'es; e.g., a computation
  that calls HClass.getMethod(String, String) a lot: construction of a
  CallGraphImpl + all possible queries on it.

 HClass.exitImmutableEpoch();

Knowing that HClasses are not mutated in a certain code sequence is actually tricky, because most of the HCodeFactories are lazy; a good method is to use a CachingCodeFactory that has already computed the code of every method of interest.

Version:

$Id: HClass.java,v 1.52 2005/10/25 14:33:21 salcianu Exp $

Author:

C. Scott Ananian <cananian@alumni.princeton.edu>

See Also:

ClassFile, Class

Field Summary

static ArrayFactory<HClass>	arrayFactory Array factory: returns new HClass[].
static HClass	Boolean The HClass object representing the primitive type boolean.
static HClass	Byte The HClass object representing the primitive type byte.
static HClass	Char The HClass object representing the primitive type char.
static HClass	Double The HClass object representing the primitive type double.
static HClass	Float The HClass object representing the primitive type float.
static HClass	Int The HClass object representing the primitive type int.
static HClass	Long The HClass object representing the primitive type long.
static HClass	Short The HClass object representing the primitive type short.
static HClass	Void The HClass object representing the primitive type void.

Method Summary

int	compareTo(HClass o) Compares two HClasses by lexicographic order of their descriptors.
static void	enterImmutableEpoch() Notifies the HClass implementation that Flex enters an immutability epoch, i.e., a period of time when no HClass will be mutated.
static void	exitImmutableEpoch() Notifies the HClass implementation that Flex exits an immutability epoch (i.e., in the future, Flex may mutate one or more HClass.
abstract HInitializer	getClassInitializer() Returns the class initializer method, if there is one; otherwise null.
abstract HClass	getComponentType() If this class represents an array type, returns the HClass object representing the component type of the array; otherwise returns null.
abstract HConstructor	getConstructor(HClass[] parameterTypes) Returns an HConstructor object that reflects the specified declared constructor of the class or interface represented by this HClass object.
abstract HConstructor[]	getConstructors() Returns an array of HConstructor objects reflecting all the constructors declared by the class represented by the HClass object.
abstract HField	getDeclaredField(String name) Returns a HField object that reflects the specified declared field of the class or interface represented by this HClass object.
abstract HField[]	getDeclaredFields() Returns an array of HField objects reflecting all the fields declared by the class or interface represented by this HClass object.
abstract HMethod	getDeclaredMethod(String name, HClass[] parameterTypes) Returns a HMethod object that reflects the specified declared method of the class or interface represented by this HClass object.
abstract HMethod	getDeclaredMethod(String name, String descriptor) Returns a HMethod object that reflects the specified declared method of the class or interface represented by this HClass object.
abstract HMethod[]	getDeclaredMethods() Returns an array of HMethod objects reflecting all the methods declared by the class or interface represented by this HClass object.
abstract String	getDescriptor() Returns a ComponentType descriptor for the type represented by this HClass object.
HField	getField(String name) Returns a HField object that reflects the specified accessible member field of the class or interface represented by this HClass object.
HField[]	getFields() Returns an array containing HField objects reflecting all the accessible fields of the class or interface represented by this HClass object.
HType[]	getGenericInterfaces() Returns the HTypes representing the interfaces implemented by the class or interface represented by this object.
HType	getGenericSuperclass() Returns the HType representing the superclass of the entity (class, interface, primitive type or void) represented by this HClass.
abstract HClass[]	getInterfaces() Determines the interfaces implemented by the class or interface represented by this object.
Linker	getLinker() Returns the linker responsible for the resolution of this HClass object.
HMethod	getMethod(String name, HClass[] parameterTypes) Returns an HMethod object that reflects the specified accessible method of the class or interface represented by this HClass object.
HMethod	getMethod(String name, String descriptor) Returns an HMethod object that reflects the specified accessible method of the class or interface represented by this HClass object.
HMethod[]	getMethods() Returns an array containing HMethod object reflecting all accessible member methods of the class or interface represented by this HClass object, including those declared by the class or interface and those inherited from superclasses and superinterfaces.
abstract int	getModifiers() Returns the Java language modifiers for this class or interface, encoded in an integer.
HClassMutator	getMutator() Returns a mutator for this HClass, or null if this object is immutable.
abstract String	getName() Returns the fully-qualified name of the type (class, interface, array, or primitive) represented by this HClass object, as a String.
abstract String	getPackage() Returns the package name of this HClass.
abstract String	getSourceFile() Return the name of the source file for this class, or a zero-length string if the information is not available.
abstract HClass	getSuperclass() If this object represents any class other than the class Object, then the object that represents the superclass of that class is returned.
HClassTypeVariable[]	getTypeParameters() Returns an array of HClassTypeVariable objects that represents the type variables declared by the class or interface represented by this HClass object, in declaration order.
HClass	getWrapper(Linker l) If this HClass is a primitive type, return the wrapper class for values of this type.
boolean	hasBeenModified() Determines whether any part of this HClass has been modified from its originally loaded state.
int	hashCode() Returns a hashcode value for this HClass.
abstract boolean	isArray() If this HClass object represents an array type, returns true, otherwise returns false.
boolean	isAssignableFrom(HClass cls) Determines if the class or interface represented by this HClass object is either the same as, or is a superclass or superinterface of, the class or interface represented by the specified HClass parameter.
boolean	isInstanceOf(HClass hc) Determines if this HClass is an instance of the given HClass hc.
abstract boolean	isInterface() Determines if the specified HClass object represents an interface type.
abstract boolean	isPrimitive() Determines if the specified HClass object represents a primitive Java type.
boolean	isSuperclassOf(HClass hc) Determines if this HClass is a superclass of a given HClass hc.
boolean	isSuperinterfaceOf(HClass hc) Determines if this HClass is a superinterface of a given HClass hc.
Set<HClass>	parents() Return the parents of this HClass.
void	print(PrintWriter pw) Prints a formatted representation of this class.
String	toString() Converts the object to a string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

Boolean

public static final HClass Boolean

The HClass object representing the primitive type boolean.

Byte

public static final HClass Byte

The HClass object representing the primitive type byte.

Short

public static final HClass Short

The HClass object representing the primitive type short.

Int

public static final HClass Int

The HClass object representing the primitive type int.

Long

public static final HClass Long

The HClass object representing the primitive type long.

Float

public static final HClass Float

The HClass object representing the primitive type float.

Double

public static final HClass Double

The HClass object representing the primitive type double.

Char

public static final HClass Char

The HClass object representing the primitive type char.

Void

public static final HClass Void

The HClass object representing the primitive type void.

arrayFactory

public static final ArrayFactory<HClass> arrayFactory

Array factory: returns new HClass[].

Method Detail

getLinker

public final Linker getLinker()

Returns the linker responsible for the resolution of this HClass object.

getMutator

public HClassMutator getMutator()

Returns a mutator for this HClass, or null if this object is immutable.

hasBeenModified

public boolean hasBeenModified()

Determines whether any part of this HClass has been modified from its originally loaded state.

getComponentType

public abstract HClass getComponentType()

If this class represents an array type, returns the HClass object representing the component type of the array; otherwise returns null.

See Also:

Array

getName

public abstract String getName()

Returns the fully-qualified name of the type (class, interface, array, or primitive) represented by this HClass object, as a String.

Returns:

the fully qualified name of the class or interface represented by this object.

getPackage

public abstract String getPackage()

Returns the package name of this HClass. If this HClass represents a primitive or array type, then returns null. Returns "" (a zero-length string) if this class is not in a package.

getDescriptor

public abstract String getDescriptor()

Returns a ComponentType descriptor for the type represented by this HClass object.

getDeclaredField

public abstract HField getDeclaredField(String name)
                                 throws NoSuchFieldError

Returns a HField object that reflects the specified declared field of the class or interface represented by this HClass object. The name parameter is a String that specifies the simple name of the desired field.

Throws:

NoSuchFieldError - if a field with the specified name is not found.

See Also:

HField

getDeclaredFields

public abstract HField[] getDeclaredFields()

Returns an array of HField objects reflecting all the fields declared by the class or interface represented by this HClass object. This includes public, protected, default (package) access, and private fields, but excludes inherited fields. Returns an array of length 0 if the class or interface declares no fields, or if this HClass object represents a primitive type.

See Also:

"The Java Language Specification, sections 8.2 and 8.3", HField

getField

public final HField getField(String name)
                      throws NoSuchFieldError

Returns a HField object that reflects the specified accessible member field of the class or interface represented by this HClass object. The name parameter is a String specifying the simple name of the desired field.

The field to be reflected is located by searching all member fields of the class or interface represented by this HClass object (and its superclasses and interfaces) for an accessible field with the specified name.

Throws:

NoSuchFieldError - if a field with the specified name is not found.

See Also:

"The Java Language Specification, sections 8.2 and 8.3", HField

getFields

public HField[] getFields()

Returns an array containing HField objects reflecting all the accessible fields of the class or interface represented by this HClass object. Returns an array of length 0 if the class or interface has no accessible fields, or if it represents an array type or a primitive type.

Specifically, if this HClass object represents a class, returns the accessible fields of this class and of all its superclasses. If this HClass object represents an interface, returns the accessible fields of this interface and of all its superinterfaces. If this HClass object represents an array type or a primitive type, returns an array of length 0.

The implicit length field for array types is not reflected by this method.

See Also:

"The Java Language Specification, sections 8.2 and 8.3", HField

getDeclaredMethod

public abstract HMethod getDeclaredMethod(String name,
                                          HClass[] parameterTypes)
                                   throws NoSuchMethodError

Returns a HMethod object that reflects the specified declared method of the class or interface represented by this HClass object. The name parameter is a String that specifies the simple name of the desired method, and the parameterTypes parameter is an array of HClass objects that identify the method's formal parameter types, in declared order.

Throws:

NoSuchMethodError - if a matching method is not found.

See Also:

HMethod

getDeclaredMethod

public abstract HMethod getDeclaredMethod(String name,
                                          String descriptor)
                                   throws NoSuchMethodError

Returns a HMethod object that reflects the specified declared method of the class or interface represented by this HClass object. The name parameter is a String that specifies the simple name of the desired method, and descriptor is a string describing the parameter types and return value of the method.

Throws:

NoSuchMethodError - if a matching method is not found.

See Also:

HMethod.getDescriptor()

getDeclaredMethods

public abstract HMethod[] getDeclaredMethods()

Returns an array of HMethod objects reflecting all the methods declared by the class or interface represented by this HClass object. This includes public, protected, default (package) access, and private methods, but excludes inherited methods. Returns an array of length 0 if the class or interface declares no methods, or if this HClass object represents a primitive type.

Constructors are included.

See Also:

"The Java Language Specification, section 8.2", HMethod

getMethod

public final HMethod getMethod(String name,
                               HClass[] parameterTypes)
                        throws NoSuchMethodError

Returns an HMethod object that reflects the specified accessible method of the class or interface represented by this HClass object. The name parameter is a string specifying the simple name of the desired method, and the parameterTypes parameter is an array of HClass objects that identify the method's formal parameter types, in declared order.

The method to reflect is located by searching all the member methods of the class or interface represented by this HClass object for an accessible method with the specified name and exactly the same formal parameter types.

Throws:

NoSuchMethodError - if a matching method is not found.

See Also:

"The Java Language Specification, sections 8.2 and 8.4"

getMethod

public final HMethod getMethod(String name,
                               String descriptor)
                        throws NoSuchMethodError

Returns an HMethod object that reflects the specified accessible method of the class or interface represented by this HClass object. The name parameter is a string specifying the simple name of the desired method, and the descriptor is a string describing the parameter types and return value of the method.

The method is located by searching all the member methods of the class or interface represented by this HClass object for an accessible method with the specified name and exactly the same descriptor.

Throws:

NoSuchMethodError - if a matching method is not found.

See Also:

HMethod.getDescriptor()

enterImmutableEpoch

public static final void enterImmutableEpoch()

Notifies the HClass implementation that Flex enters an immutability epoch, i.e., a period of time when no HClass will be mutated. Inside an immutability epoch, expensive HClass computations may perform caching. These caches are invalidated at the end of the current immutability epoch, so there is danger of reusing caches from an old epoch.

exitImmutableEpoch

public static final void exitImmutableEpoch()

Notifies the HClass implementation that Flex exits an immutability epoch (i.e., in the future, Flex may mutate one or more HClass.

getMethods

public HMethod[] getMethods()

Returns an array containing HMethod object reflecting all accessible member methods of the class or interface represented by this HClass object, including those declared by the class or interface and those inherited from superclasses and superinterfaces. Returns an array of length 0 if the class or interface has no public member methods, or if the HClass corresponds to a primitive type or array type.

Constructors are included.

See Also:

"The Java Language Specification, sections 8.2 and 8.4"

getConstructor

public abstract HConstructor getConstructor(HClass[] parameterTypes)
                                     throws NoSuchMethodError

Returns an HConstructor object that reflects the specified declared constructor of the class or interface represented by this HClass object. The parameterTypes parameter is an array of HClass objects that identify the constructor's formal parameter types, in declared order.

Throws:

NoSuchMethodError - if a matching method is not found.

getConstructors

public abstract HConstructor[] getConstructors()

Returns an array of HConstructor objects reflecting all the constructors declared by the class represented by the HClass object. These are public, protected, default (package) access, and private constructors. Returns an array of length 0 if this HClass object represents an interface or a primitive type.

See Also:

"The Java Language Specification, section 8.2"

getClassInitializer

public abstract HInitializer getClassInitializer()

Returns the class initializer method, if there is one; otherwise null.

See Also:

"The Java Virtual Machine Specification, section 3.8"

getModifiers

public abstract int getModifiers()

Returns the Java language modifiers for this class or interface, encoded in an integer. The modifiers consist of the Java Virtual Machine's constants for public, protected, private, final, and interface; they should be decoded using the methods of class Modifier.

See Also:

"The Java Virtual Machine Specification, table 4.1", Modifier

getSuperclass

public abstract HClass getSuperclass()

If this object represents any class other than the class Object, then the object that represents the superclass of that class is returned.

If this object is the one that represents the class Object or this object represents an interface, null is returned. If this object represents an array, then the HClass representing java.lang.Object is returned.

Returns:

the superclass of the class represented by this object.

getInterfaces

public abstract HClass[] getInterfaces()

Determines the interfaces implemented by the class or interface represented by this object.

If this object represents a class, the return value is an array containing objects representing all interfaces implemented by the class. The order of the interface objects in the array corresponds to the order of the interface names in the implements clause of the declaration of the class represented by this object.

If the object represents an interface, the array contains objects representing all interfaces extended by the interface. The order of the interface objects in the array corresponds to the order of the interface names in the extends clause of the declaration of the interface represented by this object.

If the class or interface implements no interfaces, the method returns an array of length 0.

NOTE THAT the array returned does NOT contain interfaces implemented by superclasses. Thus the interface list may be incomplete. This is pretty bogus behaviour, but it's what our prototype, java.lang.Class, does.

Returns:

an array of interfaces implemented by this class.

parents

public final Set<HClass> parents()

Return the parents of this HClass. The returned set contains this class'es superclass and the interfaces that this class implements. This information is not transitive: we do not consider the superclass of the superclass, nor the interfaces extended by the directly implemented interfaces.

getSourceFile

public abstract String getSourceFile()

Return the name of the source file for this class, or a zero-length string if the information is not available.

See Also:

AttributeSourceFile

getWrapper

public final HClass getWrapper(Linker l)

If this HClass is a primitive type, return the wrapper class for values of this type. For example:

HClass.forDescriptor("I").getWrapper()

will return l.forName("java.lang.Integer"). Calling getWrapper with a non-primitive HClass will return the value null.

isArray

public abstract boolean isArray()

If this HClass object represents an array type, returns true, otherwise returns false.

isInterface

public abstract boolean isInterface()

Determines if the specified HClass object represents an interface type.

Returns:

true is this object represents an interface; false otherwise.

isPrimitive

public abstract boolean isPrimitive()

Determines if the specified HClass object represents a primitive Java type.

There are nine predefined HClass objects to represent the eight primitive Java types and void.

isAssignableFrom

public final boolean isAssignableFrom(HClass cls)

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

Specifically, this method tests whether the type represented by the specified HClass parameter can be converted to the type represented by this HClass object via an identity conversion or via a widening reference conversion.

Throws:

NullPointerException - if the specified HClass parameter is null.

See Also:

"The Java Language Specification, sections 5.1.1 and 5.1.4"

isSuperclassOf

public final boolean isSuperclassOf(HClass hc)

Determines if this HClass is a superclass of a given HClass hc. [Does not look at interface information.]

Returns:

true if this is a superclass of hc, false otherwise.

isSuperinterfaceOf

public final boolean isSuperinterfaceOf(HClass hc)

Determines if this HClass is a superinterface of a given HClass hc. [does not look at superclass information]

Returns:

true if this is a superinterface of hc, false otherwise.

isInstanceOf

public final boolean isInstanceOf(HClass hc)

Determines if this HClass is an instance of the given HClass hc.

hashCode

public int hashCode()

Returns a hashcode value for this HClass. The hashcode is identical to the hashcode for the class descriptor string.

toString

public final String toString()

Converts the object to a string. The string representation is the string "class" or "interface" followed by a space and then the fully qualified name of the class. If this HClass object represents a primitive type, returns the name of the primitive type.

Overrides:

toString in class Object

Returns:

a string representation of this class object.

print

public final void print(PrintWriter pw)

Prints a formatted representation of this class. Output is pseudo-Java source.

getGenericInterfaces

public HType[] getGenericInterfaces()

Returns the HTypes representing the interfaces implemented by the class or interface represented by this object.

If this object represents a class, the return value is an array containing objects representing all interfaces implemented by the class. The order of the interface objects in the array corresponds to the order of the interface names in the implements clause of the declaration of the class represented by this object. In the case of an array class, the interfaces Cloneable and Serializable are returned in that order.

If this object represents an interface, the array contains objects representing all interfaces extended by the interface. The order of the interface objects in the array corresponds to the order of the interface names in the extends clause of the declaration of the interface represented by this object.

If this object represents a class or interface that implements no interfaces, the method returns an array of length 0.

If this object represents a primitive type or void, the method returns an array of length 0.

In particular, if the compile-time type of any superinterface is a parameterized type, than an object of the appropriate type (i.e., HParameterizedType) will be returned.

Returns:

an array of interfaces implemented by this class.

getGenericSuperclass

public HType getGenericSuperclass()

Returns the HType representing the superclass of the entity (class, interface, primitive type or void) represented by this HClass. If this HClass 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 HClass object representing the Object class is returned.

In particular, if the compile-time superclass declaration is a parameterized type, than an object of the appropriate type (i.e., HParameterizedType) will be returned.

Returns:

the superclass of the class represented by this object.

getTypeParameters

public HClassTypeVariable[] getTypeParameters()

Returns an array of HClassTypeVariable objects that represents the type variables declared by the class or interface represented by this HClass object, in declaration order. Returns an array of length 0 if the underlying class or interface declares no type variables.

compareTo

public final int compareTo(HClass o)

Compares two HClasses by lexicographic order of their descriptors.

Specified by:

compareTo in interface Comparable<HClass>