Java Debug Interface

com.sun.jdi
Interface ReferenceType

All Known Subinterfaces:
ArrayType, ClassType, InterfaceType

public abstract interface ReferenceType
extends Type, java.lang.Comparable, Accessible

The type of an object in a target VM. ReferenceType encompasses classes, interfaces, and array types as defined in the Java Language Specification (and has corresponding subinterfaces for each). The VM creates Class objects for all three, so from the VM perspective, each ReferenceType maps to a distinct Class object.

ReferenceTypes can be obtained by querying a particular ObjectReference for its type or by getting a list of all reference types from the VirtualMachine.

ReferenceType provides access to static type information such as methods and fields and provides access to dynamic type information such as the corresponding Class object and the classloader.

Since:
1.3
See Also:
ObjectReference, ObjectReference.referenceType(), VirtualMachine, VirtualMachine.allClasses()

Method Summary
 java.util.List allFields()
          Returns a list containing each Field declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces.
 java.util.List allLineLocations()
          Returns the Location objects for each executable source line in this reference type.
 java.util.List allMethods()
          Returns a list containing each Method declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces.
 ClassLoaderReference classLoader()
          Gets the classloader object which loaded the class corresponding to this type.
 ClassObjectReference classObject()
          Returns the class object that corresponds to this type in the target VM.
 boolean equals(java.lang.Object obj)
          Compares the specified Object with this ReferenceType for equality.
 boolean failedToInitialize()
          Determines if initialization failed for this class.
 Field fieldByName(java.lang.String fieldName)
          Finds the visible Field with the given non-ambiguous name.
 java.util.List fields()
          Returns a list containing each Field declared in this type.
 Value getValue(Field field)
          Gets the Value of a given static Field in this type.
 java.util.Map getValues(java.util.List fields)
          Returns a map containing the Value of each static Field in the given list.
 int hashCode()
          Returns the hash code value for this ObjectReference.
 boolean isAbstract()
          Determines if this type was declared abstract.
 boolean isFinal()
          Determines if this type was declared final.
 boolean isInitialized()
          Determines if this type has been initialized.
 boolean isPrepared()
          Determines if this type has been prepared.
 boolean isStatic()
          Determines if this type was declared static.
 boolean isVerified()
          Determines if this type has been verified.
 java.util.List locationsOfLine(int lineNumber)
          Returns a List filled with all Location objects that map to the given line number.
 java.util.List methods()
          Returns a list containing each Method declared directly in this type.
 java.util.List methodsByName(java.lang.String name)
          Returns a List containing each visible Method that has the given name.
 java.util.List methodsByName(java.lang.String name, java.lang.String signature)
          Returns a List containing each visible Method that has the given name and signature.
 java.lang.String name()
          Gets the fully qualified name of this type.
 java.util.List nestedTypes()
          Returns a List containing each ReferenceType declared within this type.
 java.lang.String sourceName()
          Gets an identifing name for the source corresponding to the declaration of this type.
 java.util.List visibleFields()
          Returns a list containing each unhidden and unambiguous Field in this type.
 java.util.List visibleMethods()
          Returns a list containing each Method declared or inherited by this type.
 
Methods inherited from interface com.sun.jdi.Type
signature
 
Methods inherited from interface java.lang.Comparable
compareTo
 
Methods inherited from interface com.sun.jdi.Accessible
isPackagePrivate, isPrivate, isProtected, isPublic, modifiers
 
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
 

Method Detail

name

public java.lang.String name()
Gets the fully qualified name of this type. The returned name is formatted as it might appear in a Java langauge declaration for objects of this type.

For primitive classes the returned name is the name of the corresponding primitive type; for example, "int" is returned as the name of the class represented by java.lang.Integer#TYPE.

Specified by:
name in interface Type
Returns:
a string containing the type name.
Throws:
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

classLoader

public ClassLoaderReference classLoader()
Gets the classloader object which loaded the class corresponding to this type.
Returns:
a ClassLoaderReference which mirrors the classloader, or null if the class was loaded through the bootstrap class loader.
Throws:
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

sourceName

public java.lang.String sourceName()
                            throws AbsentInformationException
Gets an identifing name for the source corresponding to the declaration of this type. Interpretation of this string is the responsibility of the source repository mechanism.

In the reference implementation, the returned string is the unqualified name of the source file containing the declaration of this type.

Returns:
the string source file name
Throws:
AbsentInformationException - if the source name is not known
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

isStatic

public boolean isStatic()
Determines if this type was declared static. Only nested types, can be declared static, so false is returned for any package-level type, array type, or primitive class (for example, java.lang.Integer#TYPE).
Returns:
true if this type is static; false otherwise.
Throws:
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

isAbstract

public boolean isAbstract()
Determines if this type was declared abstract. Return value is undefined for arrays and for primitive classes (for example, java.lang.Integer#TYPE).
Returns:
true if this type is abstract; false otherwise.
Throws:
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

isFinal

public boolean isFinal()
Determines if this type was declared final. For ArrayType and for primitive classes, such as java.lang.Integer#TYPE, the return value is always true.
Returns:
true if this type is final; false otherwise.
Throws:
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

isPrepared

public boolean isPrepared()
Determines if this type has been prepared. See the JVM specification for a definiton of class preparation. Return value is undefined for arrays and for primitive classes (for example, java.lang.Integer#TYPE).
Returns:
true if this type is prepared; false otherwise.
Throws:
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

isVerified

public boolean isVerified()
Determines if this type has been verified. See the JVM specification for a definiton of class verification. Return value is undefined for arrays and for primitive classes (for example, java.lang.Integer#TYPE).
Returns:
true if this type is verified; false otherwise.
Throws:
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

isInitialized

public boolean isInitialized()
Determines if this type has been initialized. See the JVM specification for a definiton of class verification. For InterfaceType, this method always returns the same value as isPrepared(). Return value is undefined for arrays and for primitive classes (for example, java.lang.Integer#TYPE).
Returns:
true if this type is initialized; false otherwise.
Throws:
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

failedToInitialize

public boolean failedToInitialize()
Determines if initialization failed for this class. See the JVM specification for details on class initialization. Return value is undefined for arrays and for primitive classes (for example, java.lang.Integer#TYPE).
Returns:
true if initialization was attempted and failed; false otherwise.
Throws:
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

fields

public java.util.List fields()
Returns a list containing each Field declared in this type. Inherited fields are not included. Any synthetic fields created by the compiler are included in the list.
Returns:
a list Field objects; the list has length 0 if no fields exist.
Throws:
ClassNotPreparedException - if this class not yet been prepared.
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

visibleFields

public java.util.List visibleFields()
Returns a list containing each unhidden and unambiguous Field in this type. Each field that can be accessed from the class or its instances with its simple name is included. Fields that are ambiguously multiply inherited or fields that are hidden by fields with the same name in a more recently inherited class cannot be accessed by their simple names and are not included in the returned list. All other inherited fields are included. See JLS section 8.3 for details.
Returns:
a List of Field objects; the list has length 0 if no visible fields exist.
Throws:
ClassNotPreparedException - if this class not yet been prepared.
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

allFields

public java.util.List allFields()
Returns a list containing each Field declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces. All declared and inherited fields are included, regardless of whether they are hidden or multiply inherited.
Returns:
a List of Field objects; the list has length 0 if no fields exist.
Throws:
ClassNotPreparedException - if this class not yet been prepared.
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

fieldByName

public Field fieldByName(java.lang.String fieldName)
Finds the visible Field with the given non-ambiguous name. This method follows the inheritance rules specified in the JLS (8.3.3) to determine visibility.
Parameters:
a - String containing the name of desired field.
Returns:
a Field object which mirrors the found field, or null if there is no field with the given name or if the given name is ambiguous.
Throws:
ClassNotPreparedException - if this class not yet been prepared.
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

methods

public java.util.List methods()
Returns a list containing each Method declared directly in this type. Inherited methods are not included. Constructors, the initialization method if any, and any synthetic methods created by the compiler are included in the list.
Returns:
a list Method objects; the list has length 0 if no methods exist.
Throws:
ClassNotPreparedException - if this class not yet been prepared.
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

visibleMethods

public java.util.List visibleMethods()
Returns a list containing each Method declared or inherited by this type. Methods from superclasses or superinterfaces that that have been hidden or overridden are not included.

Note that despite this exclusion, multiple inherited methods with the same signature can be present in the returned list, but at most one can be a member of a ClassType. See JLS section 8.4.6 for details.

Returns:
a List of Method objects; the list has length 0 if no visible methods exist.
Throws:
ClassNotPreparedException - if this class not yet been prepared.
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

allMethods

public java.util.List allMethods()
Returns a list containing each Method declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces. All declared and inherited methods are included, regardless of whether they are hidden or overridden.
Returns:
a List of Method objects; the list has length 0 if no methods exist.
Throws:
ClassNotPreparedException - if this class not yet been prepared.
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

methodsByName

public java.util.List methodsByName(java.lang.String name)
Returns a List containing each visible Method that has the given name. This is most commonly used to find overloaded methods.

Overridden and hidden methods are not included. See JLS (8.4.6) for details.

Parameters:
name - the name of the method to find.
Returns:
a List of Method objects that match the given name; the list has length 0 if no matching methods are found.
Throws:
ClassNotPreparedException - if this class not yet been prepared.
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

methodsByName

public java.util.List methodsByName(java.lang.String name,
                                    java.lang.String signature)
Returns a List containing each visible Method that has the given name and signature. The signature string is the JNI signature for the target method: This method follows the inheritance rules specified in the JLS (8.4.6) to determine visibility.

At most one method in the list is a concrete method and a component of ClassType; any other methods in the list are abstract. Use ClassType.concreteMethodByName(java.lang.String, java.lang.String) to retrieve only the matching concrete method.

Parameters:
name - the name of the method to find.
signature - the signature of the method to find
Returns:
a List of Method objects that match the given name and signature; the list has length 0 if no matching methods are found.
Throws:
ClassNotPreparedException - if this class not yet been prepared.
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

nestedTypes

public java.util.List nestedTypes()
Returns a List containing each ReferenceType declared within this type. Both static nested types and non-static nested types (that is, inner types) are included. Local inner types (declared within a code block somewhere in this reference type) are also included in the returned list.
Returns:
a List of nested ReferenceType objects; the list has 0 length if there are no nested types.
Throws:
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

getValue

public Value getValue(Field field)
Gets the Value of a given static Field in this type. The Field must be valid for this type; that is, it must be declared in this type, a superclass, a superinterface, or an implemented interface.
Parameters:
sig - the field containing the requested value
Returns:
the Value of the instance field.
Throws:
java.lang.IllegalArgumentException - if the field is not valid for this object's class.
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

getValues

public java.util.Map getValues(java.util.List fields)
Returns a map containing the Value of each static Field in the given list. The Fields must be valid for this type; that is, they must be declared in this type, a superclass, a superinterface, or an implemented interface.
Parameters:
fields - a list of Field objects containing the requested values.
Returns:
a Map of the requested Field objects with their Value.
Throws:
java.lang.IllegalArgumentException - if any field is not valid for this object's class.
ObjectCollectedException - if this reference type has been unloaded and garbage collected.
VMMismatchException - if a Mirror argument and this mirror do not belong to the same VirtualMachine.

classObject

public ClassObjectReference classObject()
Returns the class object that corresponds to this type in the target VM. The VM creates class objects for every kind of ReferenceType: classes, interfaces, and array types.
Returns:
the ClassObjectReference for this reference type in the target VM.
Throws:
ObjectCollectedException - if this reference type has been unloaded and garbage collected.

allLineLocations

public java.util.List allLineLocations()
                                throws AbsentInformationException
Returns the Location objects for each executable source line in this reference type. Each location maps a source line to a range of code indices. The beginning of the range can be determined through Location.codeIndex(). The returned list may contain multiple locations for a particular line number, if the compiler and/or VM has mapped that line to two or more disjoint code index ranges. Note that it is possible for the same source line to represent different code index ranges in different methods.

If this reference type is an ArrayType, the returned list is always empty. If this reference type is an InterfaceType, the returned list will be non-empty only if the interface has executable code in its class initialization.

Returns:
a List of all source line Location objects.
Throws:
AbsentInformationException - if there is no line number information for this class and there are non-native, non-abstract executable members of this class.
ClassNotPreparedException - if this class not yet been prepared.
ObjectCollectedException - if this class has been unloaded and garbage collected.

locationsOfLine

public java.util.List locationsOfLine(int lineNumber)
                               throws AbsentInformationException
Returns a List filled with all Location objects that map to the given line number.

If this reference type is an ArrayType, the returned list is always empty. If this reference type is an InterfaceType, the returned list will be non-empty only if the interface has executable code in its class initialization at the specified line number.

Returns:
a List of all Location objects that map to the given line.
Throws:
AbsentInformationException - if there is no line number information for this class.
ClassNotPreparedException - if this class not yet been prepared.
ObjectCollectedException - if this class has been unloaded and garbage collected.
InvalidLineNumberException - if there is no executable code associated with the given line.

equals

public boolean equals(java.lang.Object obj)
Compares the specified Object with this ReferenceType for equality.
Returns:
true if the Object is a ReferenceType, if the ReferenceTypes belong to the same VM, and if they mirror classes which correspond to the same instance of java.lang.Class in that VM.
Throws:
ObjectCollectedException - if this reference type has been unloaded and garbage collected.
Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Returns the hash code value for this ObjectReference.
Returns:
the integer hash code
Throws:
ObjectCollectedException - if this reference type has been unloaded and garbage collected.
Overrides:
hashCode in class java.lang.Object

Java Debug Interface