com.sun.jdi
Interface ReferenceType

All Superinterfaces:

Accessible, Comparable, Mirror, Type

All Known Subinterfaces:

ArrayType, ClassType, InterfaceType

public interface ReferenceType

extends Type, Comparable, Accessible

The type of an object in a target VM. ReferenceType encompasses classes, interfaces, and array types as defined in the Java^TM Language Specification. All ReferenceType objects belong to one of the following subinterfaces: ClassType for classes, InterfaceType for interfaces, and ArrayType for arrays. Note that primitive classes (for example, the reflected type of Integer.TYPE) are represented as ClassType. 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.

Any method on ReferenceType which directly or indirectly takes ReferenceType as an parameter may throw VMDisconnectedException if the target VM is disconnected and the VMDisconnectEvent has been or is available to be read from the EventQueue.

Any method on ReferenceType which directly or indirectly takes ReferenceType as an parameter may throw VMOutOfMemoryException if the target VM has run out of memory.

Any method on ReferenceType or which directly or indirectly takes ReferenceType as parameter may throw ObjectCollectedException if the mirrored type has been unloaded.

Since:

1.3

See Also:

ObjectReference, ObjectReference.referenceType(), VirtualMachine, VirtualMachine.allClasses()

Method Summary

List	allFields() Returns a list containing each Field declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces.
List	allLineLocations() Returns a list containing a Location object for each executable source line in this reference type.
List	allLineLocations(String stratum, String sourceName) Returns a list containing a Location object for each executable source line in this reference type.
List	allMethods() Returns a list containing each Method declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces.
List	availableStrata() Return the available strata for this reference type.
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.
String	defaultStratum() Returns the default stratum for this reference type.
boolean	equals(Object obj) Compares the specified Object with this ReferenceType for equality.
boolean	failedToInitialize() Determines if initialization failed for this class.
Field	fieldByName(String fieldName) Finds the visible Field with the given non-ambiguous name.
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.
Map	getValues(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.
List	locationsOfLine(int lineNumber) Returns a List containing all Location objects that map to the given line number.
List	locationsOfLine(String stratum, String sourceName, int lineNumber) Returns a List containing all Location objects that map to the given line number.
List	methods() Returns a list containing each Method declared directly in this type.
List	methodsByName(String name) Returns a List containing each visible Method that has the given name.
List	methodsByName(String name, String signature) Returns a List containing each visible Method that has the given name and signature.
String	name() Gets the fully qualified name of this type.
List	nestedTypes() Returns a List containing ReferenceType objects that are declared within this type and are currently loaded into the Virtual Machine.
String	sourceDebugExtension() Get the source debug extension of this type.
String	sourceName() Gets an identifying name for the source corresponding to the declaration of this type.
List	sourceNames(String stratum) Gets the identifying names for all the source corresponding to the declaration of this type.
List	sourcePaths(String stratum) Gets the paths to the source corresponding to the declaration of this type.
List	visibleFields() Returns a list containing each unhidden and unambiguous Field in this type.
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 com.sun.jdi.Mirror

toString, virtualMachine

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface com.sun.jdi.Accessible

isPackagePrivate, isPrivate, isProtected, isPublic, modifiers

Method Detail

name

public String name()

Gets the fully qualified name of this type. The returned name is formatted as it might appear in a Java programming 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 Integer.TYPE.

Specified by:

name in interface Type

Returns:

a string containing the type name.

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.

sourceName

public String sourceName()
                  throws AbsentInformationException

Gets an identifying name for the source corresponding to the declaration of this type. Interpretation of this string is the responsibility of the source repository mechanism.

The returned name is dependent on VM's default stratum (VirtualMachine.getDefaultStratum()). In the reference implementation, when using the base stratum, the returned string is the unqualified name of the source file containing the declaration of this type. In other strata the returned source name is the first source name for that stratum. Since other languages may have more than one source name for a reference type, the use of Location.sourceName() or sourceNames(String) is preferred.

For arrays (ArrayType) and primitive classes, AbsentInformationException is always thrown.

Returns:

the string source file name

Throws:

AbsentInformationException - if the source name is not known

sourceNames

public List sourceNames(String stratum)
                 throws AbsentInformationException

Gets the identifying names for all the source corresponding to the declaration of this type. Interpretation of these names is the responsibility of the source repository mechanism.

The returned names are for the specified stratum (see Location for a description of strata). In the reference implementation, when using the Java programming language stratum, the returned List contains one element: a String which is the unqualified name of the source file containing the declaration of this type. In other strata the returned source names are all the source names defined for that stratum.

Parameters:

stratum - The stratum to retrieve information from or null for the declaring type's default stratum.

Returns:

a List of String objects each representing a source name

Throws:

AbsentInformationException - if the source names are not known.

For arrays (ArrayType) and primitive classes, AbsentInformationException is always thrown.

Since:

1.4

sourcePaths

public List sourcePaths(String stratum)
                 throws AbsentInformationException

Gets the paths to the source corresponding to the declaration of this type. Interpretation of these paths is the responsibility of the source repository mechanism.

The returned paths are for the specified stratum (see Location for a description of strata). In the reference implementation, for strata which do not explicitly specify source path (the Java programming language stratum never does), the returned strings are the sourceNames(String) prefixed by the package name of this ReferenceType converted to a platform dependent path. For example, on a Windows platform, java.lang.Thread would return a List containing one element: "java\lang\Thread.java".

Parameters:

stratum - The stratum to retrieve information from or null for the declaring type's default stratum.

Returns:

a List of String objects each representing a source path

Throws:

AbsentInformationException - if the source names are not known.

For arrays (ArrayType) and primitive classes, AbsentInformationException is always thrown.

Since:

1.4

sourceDebugExtension

public String sourceDebugExtension()
                            throws AbsentInformationException

Get the source debug extension of this type.

Not all target virtual machines support this operation. Use canGetSourceDebugExtension() to determine if the operation is supported.

Returns:

as a string the source debug extension attribute

Throws:

AbsentInformationException - if the extension is not specified

UnsupportedOperationException - if the target virtual machine does not support this operation - see canGetSourceDebugExtension(),

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.

Returns:

true if this type is static; false otherwise.

isAbstract

public boolean isAbstract()

Determines if this type was declared abstract.

For arrays (ArrayType) and primitive classes, the return value is undefined.

Returns:

true if this type is abstract; false otherwise.

isFinal

public boolean isFinal()

Determines if this type was declared final.

For arrays (ArrayType) and primitive classes, the return value is always true.

Returns:

true if this type is final; false otherwise.

isPrepared

public boolean isPrepared()

Determines if this type has been prepared. See the JVM specification for a definition of class preparation.

For arrays (ArrayType) and primitive classes, the return value is undefined.

Returns:

true if this type is prepared; false otherwise.

isVerified

public boolean isVerified()

Determines if this type has been verified. See the JVM specification for a definition of class verification.

For arrays (ArrayType) and primitive classes, the return value is undefined.

Returns:

true if this type is verified; false otherwise.

isInitialized

public boolean isInitialized()

Determines if this type has been initialized. See the JVM specification for a definition of class verification. For InterfaceType, this method always returns the same value as isPrepared().

For arrays (ArrayType) and primitive classes, the return value is undefined.

Returns:

true if this type is initialized; false otherwise.

failedToInitialize

public boolean failedToInitialize()

Determines if initialization failed for this class. See the JVM specification for details on class initialization.

For arrays (ArrayType) and primitive classes, the return value is undefined.

Returns:

true if initialization was attempted and failed; false otherwise.

fields

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

For arrays (ArrayType) and primitive classes, the returned list is always empty.

Returns:

a list Field objects; the list has length 0 if no fields exist.

Throws:

ClassNotPreparedException - if this class not yet been prepared.

visibleFields

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

For arrays (ArrayType) and primitive classes, the returned list is always empty.

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.

allFields

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

For arrays (ArrayType) and primitive classes, the returned list is always empty.

Returns:

a List of Field objects; the list has length 0 if no fields exist.

Throws:

ClassNotPreparedException - if this class not yet been prepared.

fieldByName

public Field fieldByName(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.

For arrays (ArrayType) and primitive classes, the returned value is always null.

Parameters:

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

methods

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

For arrays (ArrayType) and primitive classes, the returned list is always empty.

Returns:

a list Method objects; the list has length 0 if no methods exist.

Throws:

ClassNotPreparedException - if this class not yet been prepared.

visibleMethods

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

For arrays (ArrayType) and primitive classes, the returned list is always empty.

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.

allMethods

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

For arrays (ArrayType) and primitive classes, the returned list is always empty.

Returns:

a List of Method objects; the list has length 0 if no methods exist.

Throws:

ClassNotPreparedException - if this class not yet been prepared.

methodsByName

public List methodsByName(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.

For arrays (ArrayType) and primitive classes, the returned list is always empty.

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.

methodsByName

public List methodsByName(String name,
                          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:

• ()V
• ([Ljava/lang/String;)V
• (IIII)Z

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.

For arrays (ArrayType) and primitive classes, the returned list is always empty.

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.

nestedTypes

public List nestedTypes()

Returns a List containing ReferenceType objects that are declared within this type and are currently loaded into the Virtual Machine. 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.

For arrays (ArrayType) and primitive classes, the returned list is always empty.

Returns:

a List of nested ReferenceType objects; the list has 0 length if there are no nested types.

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:

field - the field containing the requested value

Returns:

the Value of the instance field.

Throws:

IllegalArgumentException - if the field is not valid for this object's class.

getValues

public Map getValues(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:

IllegalArgumentException - if any field is not valid for this object's class.

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.

allLineLocations

public List allLineLocations()
                      throws AbsentInformationException

Returns a list containing a Location object for each executable source line in this reference type.

This method is equivalent to allLineLocations(vm.getDefaultStratum(),null) - see allLineLocations(String,String) for more information.

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.

allLineLocations

public List allLineLocations(String stratum,
                             String sourceName)
                      throws AbsentInformationException

Returns a list containing a Location object 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.

For arrays (ArrayType) and primitive classes, the returned list is always empty. For interfaces (InterfaceType), the returned list will be non-empty only if the interface has executable code in its class initialization.

Returned list is for the specified stratum (see Location for a description of strata).

Parameters:

stratum - The stratum to retrieve information from or null for the defaultStratum().

sourceName - Return locations only within this source file or null to return locations.

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. Or if sourceName is non-null and source name information is not present.

ClassNotPreparedException - if this class not yet been prepared.

Since:

1.4

locationsOfLine

public List locationsOfLine(int lineNumber)
                     throws AbsentInformationException

Returns a List containing all Location objects that map to the given line number.

This method is equivalent to locationsOfLine(vm.getDefaultStratum(), null, lineNumber) - see locationsOfLine(java.lang.String,java.lang.String,int) for more information.

Parameters:

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

See Also:

VirtualMachine.getDefaultStratum()

locationsOfLine

public List locationsOfLine(String stratum,
                            String sourceName,
                            int lineNumber)
                     throws AbsentInformationException

Returns a List containing all Location objects that map to the given line number.

For arrays (ArrayType) and primitive classes, the returned list is always empty. For interfaces (InterfaceType), the returned list will be non-empty only if the interface has executable code in its class initialization at the specified line number. An empty list will be returned if there is no executable code at the specified line number.

Returned list is for the specified stratum (see Location for a description of strata).

Parameters:

stratum - the stratum to use for comparing line number and source name, or null to use the defaultStratum().

sourceName - the source name containing the line number, or null to match all source names

lineNumber - the 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. Or if sourceName is non-null and source name information is not present.

ClassNotPreparedException - if this class not yet been prepared.

Since:

1.4

availableStrata

public List availableStrata()

Return the available strata for this reference type.

See the Location for a description of strata.

Returns:

List of java.lang.String, each representing a stratum

Since:

1.4

defaultStratum

public String defaultStratum()

Returns the default stratum for this reference type. This value is specified in the class file and cannot be set by the user. If the class file does not specify a default stratum the base stratum ("Java") will be returned.

See the Location for a description of strata.

Since:

1.4

equals

public boolean equals(Object obj)

Compares the specified Object with this ReferenceType for equality.

Overrides:

equals in class Object

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.

hashCode

public int hashCode()

Returns the hash code value for this ObjectReference.

Overrides:

hashCode in class Object

Returns:

the integer hash code