/* * Copyright (c) 1998, 2011, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package com.sun.jdi; import java.util.List; import java.util.Map; /** * The type of an object in a target VM. ReferenceType encompasses * classes, interfaces, and array types as defined in * The Java™ Language Specification. * All ReferenceType objects belong to one of the following * subinterfaces: * {@link ClassType} for classes, * {@link InterfaceType} for interfaces, and * {@link ArrayType} for arrays. * Note that primitive classes (for example, the * {@link ClassObjectReference#reflectedType() reflected type} of * {@link java.lang.Integer#TYPE 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 {@link ObjectReference} for its * type or by getting a list of all reference types from the * {@link 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
* {@link com.sun.jdi.VMDisconnectedException} if the target VM is
* disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been or is
* available to be read from the {@link com.sun.jdi.event.EventQueue}.
*
* Any method on ReferenceType
which directly or
* indirectly takes ReferenceType
as an parameter may throw
* {@link com.sun.jdi.VMOutOfMemoryException} if the target VM has run out of memory.
*
* Any method on
* 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 {@link java.lang.Integer#TYPE Integer.TYPE}.
* @return a string containing the type name.
*/
String name();
/**
* Gets the generic signature for this type if there is one.
* Generic signatures are described in the
* The Java™ Virtual Machine Specification.
*
* @return a string containing the generic signature, or
* The returned name is dependent on VM's default stratum
* ({@link 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 {@link Location#sourceName()} or
* {@link #sourceNames(String)} is preferred.
*
* For arrays ({@link ArrayType}) and primitive classes,
* AbsentInformationException is always thrown.
*
* @return the string source file name
* @throws AbsentInformationException if the source name is not
* known
*/
String sourceName() 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 {@link 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.
*
* @param stratum The stratum to retrieve information from
* or
* For arrays ({@link ArrayType}) and primitive classes,
* AbsentInformationException is always thrown.
*
* @since 1.4
*/
List
* The returned paths are for the specified stratum
* (see {@link 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 {@link #sourceNames(String)} prefixed by
* the package name of this ReferenceType
* converted to a platform dependent path.
* For example, on a Windows platform,
*
* For arrays ({@link ArrayType}) and primitive classes,
* AbsentInformationException is always thrown.
*
* @since 1.4
*/
List
* Not all target virtual machines support this operation.
* Use
* {@link VirtualMachine#canGetSourceDebugExtension() canGetSourceDebugExtension()}
* to determine if the operation is supported.
* @return as a string the source debug extension attribute
* @throws AbsentInformationException if the extension is not
* specified
* @throws java.lang.UnsupportedOperationException if
* the target virtual machine does not support this
* operation - see
* {@link VirtualMachine#canGetSourceDebugExtension() canGetSourceDebugExtension()},
*/
String sourceDebugExtension() throws AbsentInformationException;
/**
* Determines if this type was declared static. Only nested types,
* can be declared static, so
* For arrays ({@link ArrayType}) and primitive classes,
* the return value is undefined.
*
* @return
* For arrays ({@link ArrayType}) and primitive classes,
* the return value is always true.
*
* @return
* For arrays ({@link ArrayType}) and primitive classes,
* the return value is undefined.
*
* @return
* For arrays ({@link ArrayType}) and primitive classes,
* the return value is undefined.
*
* @return
* For arrays ({@link ArrayType}) and primitive classes,
* the return value is undefined.
*
* @return
* For arrays ({@link ArrayType}) and primitive classes,
* the return value is undefined.
*
* @return
* For arrays ({@link ArrayType}) and primitive classes, the returned
* list is always empty.
*
* @return a list {@link Field} objects; the list has length 0
* if no fields exist.
* @throws ClassNotPreparedException if this class not yet been
* prepared.
*/
List
* For arrays ({@link ArrayType}) and primitive classes, the returned
* list is always empty.
*
* @return a List of {@link Field} objects; the list has length
* 0 if no visible fields exist.
* @throws ClassNotPreparedException if this class not yet been
* prepared.
*/
List
* For arrays ({@link ArrayType}) and primitive classes, the returned
* list is always empty.
*
* @return a List of {@link Field} objects; the list has length
* 0 if no fields exist.
* @throws ClassNotPreparedException if this class not yet been
* prepared.
*/
List
* For arrays ({@link ArrayType}) and primitive classes, the returned
* value is always null.
*
* @param fieldName a String containing the name of desired field.
* @return a {@link 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.
*/
Field fieldByName(String fieldName);
/**
* Returns a list containing each {@link 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 ({@link ArrayType}) and primitive classes, the returned
* list is always empty.
*
* @return a list {@link Method} objects; the list has length 0
* if no methods exist.
* @throws ClassNotPreparedException if this class not yet been
* prepared.
*/
List
* 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 {@link ClassType}.
* See JLS section 8.4.6 for details.
*
* For arrays ({@link ArrayType}) and primitive classes, the returned
* list is always empty.
*
* @return a List of {@link Method} objects; the list has length
* 0 if no visible methods exist.
* @throws ClassNotPreparedException if this class not yet been
* prepared.
*/
List
* For arrays ({@link ArrayType}) and primitive classes, the returned
* list is always empty.
*
* @return a List of {@link Method} objects; the list has length
* 0 if no methods exist.
* @throws ClassNotPreparedException if this class not yet been
* prepared.
*/
List
* Overridden and hidden methods are not included.
* See JLS (8.4.6) for details.
*
* For arrays ({@link ArrayType}) and primitive classes, the returned
* list is always empty.
*
* @param name the name of the method to find.
* @return a List of {@link 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.
*/
List
* At most one method in the list is a concrete method and a
* component of {@link ClassType}; any other methods in the list
* are abstract. Use {@link ClassType#concreteMethodByName} to
* retrieve only the matching concrete method.
*
* For arrays ({@link ArrayType}) and primitive classes, the returned
* list is always empty.
*
* @param name the name of the method to find.
* @param signature the signature of the method to find
* @return a List of {@link 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.
*/
List
* For arrays ({@link ArrayType}) and primitive classes, the returned
* list is always empty.
*
* @return a List of nested {@link ReferenceType} objects; the list
* has 0 length if there are no nested types.
*/
List
* This method is equivalent to
*
* For arrays ({@link ArrayType}) and primitive classes, the
* returned list is always empty. For interfaces ({@link
* 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 {@link Location} for a description of strata).
*
* @param stratum The stratum to retrieve information from
* or
* This method is equivalent to
*
* For arrays ({@link ArrayType}) and primitive classes, the
* returned list is always empty.
* For interfaces ({@link 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 {@link Location} for a description of strata).
*
* @param stratum the stratum to use for comparing line number
* and source name, or
* See the {@link Location} for a description of strata.
*
* @return List of
* See the {@link Location} for a description of strata.
*
* @since 1.4
*/
String defaultStratum();
/**
* Returns instances of this ReferenceType.
* Only instances that are reachable for the purposes of garbage collection
* are returned.
*
* Not all target virtual machines support this operation.
* Use {@link VirtualMachine#canGetInstanceInfo()}
* to determine if the operation is supported.
*
* @see VirtualMachine#instanceCounts(List)
* @see ObjectReference#referringObjects(long)
*
* @param maxInstances the maximum number of instances to return.
* Must be non-negative. If zero, all instances are returned.
* @return a List of {@link ObjectReference} objects. If there are
* no instances of this ReferenceType, a zero-length list is returned.
*
* @throws java.lang.UnsupportedOperationException if
* the target virtual machine does not support this
* operation - see
* {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()}
* @throws java.lang.IllegalArgumentException if maxInstances is less
* than zero.
* @since 1.6
*/
ListReferenceType
or which directly or indirectly takes
* ReferenceType
as parameter may throw
* {@link com.sun.jdi.ObjectCollectedException} if the mirrored type has been unloaded.
*
* @see ObjectReference
* @see ObjectReference#referenceType
* @see VirtualMachine
* @see VirtualMachine#allClasses
*
* @author Robert Field
* @author Gordon Hirsch
* @author James McIlree
* @since 1.3
*/
@jdk.Supported
public interface ReferenceType
extends Type, Comparablenull
* if there is no generic signature.
*
* @since 1.5
*/
String genericSignature();
/**
* Gets the classloader object which loaded the class corresponding
* to this type.
*
* @return a {@link ClassLoaderReference} which mirrors the classloader,
* or null
if the class was loaded through the bootstrap class
* loader.
*/
ClassLoaderReference classLoader();
/**
* 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.
* null
for the declaring type's
* default stratum.
*
* @return a List of String objects each representing a source name
*
* @throws AbsentInformationException if the source names are not
* known.
* java.lang.Thread
* would return a List containing one element:
* "java\lang\Thread.java"
.
*
* @param stratum The stratum to retrieve information from
* or null
for the declaring type's
* default stratum.
*
* @return a List of String objects each representing a source path
*
* @throws AbsentInformationException if the source names are not
* known.
* false
is returned
* for any package-level type, array type, or primitive class.
*
* @return true
if this type is static; false otherwise.
*/
boolean isStatic();
/**
* Determines if this type was declared abstract.
* true
if this type is abstract; false otherwise.
*/
boolean isAbstract();
/**
* Determines if this type was declared final.
* true
if this type is final; false otherwise.
*/
boolean isFinal();
/**
* Determines if this type has been prepared. See the JVM
* specification for a definition of class preparation.
* true
if this type is prepared; false otherwise.
*/
boolean isPrepared();
/**
* Determines if this type has been verified. See the JVM
* specification for a definition of class verification.
* true
if this type is verified; false otherwise.
*/
boolean isVerified();
/**
* Determines if this type has been initialized. See the JVM
* specification for a definition of class verification.
* For {@link InterfaceType}, this method always returns the
* same value as {@link #isPrepared()}.
* true
if this type is initialized; false otherwise.
*/
boolean isInitialized();
/**
* Determines if initialization failed for this class. See the JVM
* specification for details on class initialization.
* true
if initialization was attempted and
* failed; false otherwise.
*/
boolean failedToInitialize();
/**
* Returns a list containing each {@link Field} declared in this type.
* Inherited fields are not included. Any synthetic fields created
* by the compiler are included in the list.
*
*
* This method follows the inheritance rules specified
* in the JLS (8.4.6) to determine visibility.
* ()V
* ([Ljava/lang/String;)V
* (IIII)Z
* allLineLocations(vm.getDefaultStratum(),null)
-
* see {@link #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.
*
* @throws ClassNotPreparedException if this class not yet
* been prepared.
*/
Listnull
for the {@link #defaultStratum()}.
*
* @param sourceName Return locations only within this
* source file or null
to return locations.
*
* @return a List of all source line {@link 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.
*
* @throws ClassNotPreparedException if this class not yet
* been prepared.
*
* @since 1.4
*/
ListlocationsOfLine(vm.getDefaultStratum(), null,
* lineNumber)
-
* see {@link
* #locationsOfLine(java.lang.String,java.lang.String,int)}
* for more information.
*
* @param lineNumber the line number
*
* @return a List of all {@link Location} objects that map to
* the given line.
*
* @throws AbsentInformationException if there is no line
* number information for this class.
*
* @throws ClassNotPreparedException if this class not yet
* been prepared.
*
* @see VirtualMachine#getDefaultStratum()
*/
Listnull
to
* use the {@link #defaultStratum()}.
*
* @param sourceName the source name containing the line
* number, or null
to match
* all source names
*
* @param lineNumber the line number
*
* @return a List of all {@link 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.
*
* @throws ClassNotPreparedException if this class not yet
* been prepared.
*
* @since 1.4
*/
Listjava.lang.String
, each
* representing a stratum
*
* @since 1.4
*/
List"Java"
) will be returned.
*