Overview | Package | Class | Use | Tree | Index | Help
| Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 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
`List` | `allFields()` Returns a list containing each `Field` declared in this type, and its superclasses, implemented interfaces, and/or superinterfaces.
`List` | `allLineLocations()` Returns the `Location` objects 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.
`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(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 filled with 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 each `ReferenceType` declared within this type.
`String` | `sourceName()` Gets an identifing name for 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 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 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 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 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 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(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 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 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 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 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.

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

  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 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:
    `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 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.
    `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 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 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(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.
  Throws:
    `ObjectCollectedException` - if this reference type has been unloaded and garbage collected.

### hashCode

    public int hashCode()

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

Overview | Package | Class | Use | Tree | Index | Help
| Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD