1 /*
   2  * Copyright (c) 1998, 2011, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package com.sun.jdi;
  27 
  28 import java.util.List;
  29 import java.util.Map;
  30 
  31 /**
  32  * The type of an object in a target VM. ReferenceType encompasses
  33  * classes, interfaces, and array types as defined in
  34  * <cite>The Java&trade; Language Specification</cite>.
  35  * All ReferenceType objects belong to one of the following
  36  * subinterfaces:
  37  * {@link ClassType} for classes,
  38  * {@link InterfaceType} for interfaces, and
  39  * {@link ArrayType} for arrays.
  40  * Note that primitive classes (for example, the
  41  * {@link ClassObjectReference#reflectedType() reflected type} of
  42  * {@link java.lang.Integer#TYPE Integer.TYPE})
  43  * are represented as ClassType.
  44  * The VM creates Class objects for all three, so from the VM perspective,
  45  * each ReferenceType maps to a distinct Class object.
  46  * <p>
  47  * ReferenceTypes can
  48  * be obtained by querying a particular {@link ObjectReference} for its
  49  * type or by getting a list of all reference types from the
  50  * {@link VirtualMachine}.
  51  * <p>
  52  * ReferenceType provides access to static type information such as
  53  * methods and fields and provides access to dynamic type
  54  * information such as the corresponding Class object and the classloader.
  55  * <p>
  56  * Any method on <code>ReferenceType</code> which directly or
  57  * indirectly takes <code>ReferenceType</code> as an parameter may throw
  58  * {@link com.sun.jdi.VMDisconnectedException} if the target VM is
  59  * disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been or is
  60  * available to be read from the {@link com.sun.jdi.event.EventQueue}.
  61  * <p>
  62  * Any method on <code>ReferenceType</code> which directly or
  63  * indirectly takes <code>ReferenceType</code> as an parameter may throw
  64  * {@link com.sun.jdi.VMOutOfMemoryException} if the target VM has run out of memory.
  65  * <p>
  66  * Any method on <code>ReferenceType</code> or which directly or indirectly takes
  67  * <code>ReferenceType</code> as parameter may throw
  68  * {@link com.sun.jdi.ObjectCollectedException} if the mirrored type has been unloaded.
  69  *
  70  * @see ObjectReference
  71  * @see ObjectReference#referenceType
  72  * @see VirtualMachine
  73  * @see VirtualMachine#allClasses
  74  *
  75  * @author Robert Field
  76  * @author Gordon Hirsch
  77  * @author James McIlree
  78  * @since  1.3
  79  */
  80 @jdk.Supported
  81 public interface ReferenceType
  82     extends Type, Comparable<ReferenceType>, Accessible
  83 {
  84 
  85     /**
  86      * Gets the fully qualified name of this type. The returned name
  87      * is formatted as it might appear in a Java programming langauge
  88      * declaration for objects of this type.
  89      * <p>
  90      * For primitive classes
  91      * the returned name is the name of the corresponding primitive
  92      * type; for example, "int" is returned as the name of the class
  93      * represented by {@link java.lang.Integer#TYPE Integer.TYPE}.
  94      * @return a string containing the type name.
  95      */
  96     String name();
  97 
  98     /**
  99      * Gets the generic signature for this type if there is one.
 100      * Generic signatures are described in the
 101      * <cite>The Java&trade; Virtual Machine Specification</cite>.
 102      *
 103      * @return a string containing the generic signature, or <code>null</code>
 104      * if there is no generic signature.
 105      *
 106      * @since 1.5
 107      */
 108     String genericSignature();
 109 
 110     /**
 111      * Gets the classloader object which loaded the class corresponding
 112      * to this type.
 113      *
 114      * @return a {@link ClassLoaderReference} which mirrors the classloader,
 115      * or <code>null</code> if the class was loaded through the bootstrap class
 116      * loader.
 117      */
 118     ClassLoaderReference classLoader();
 119 
 120     /**
 121      * Gets an identifying name for the source corresponding to the
 122      * declaration of this type. Interpretation of this string is
 123      * the responsibility of the source repository mechanism.
 124      * <P>
 125      * The returned name is dependent on VM's default stratum
 126      * ({@link VirtualMachine#getDefaultStratum()}).
 127      * In the reference implementation, when using the base stratum,
 128      * the returned string is the
 129      * unqualified name of the source file containing the declaration
 130      * of this type.  In other strata the returned source name is
 131      * the first source name for that stratum.  Since other languages
 132      * may have more than one source name for a reference type,
 133      * the use of {@link Location#sourceName()} or
 134      * {@link #sourceNames(String)} is preferred.
 135      * <p>
 136      * For arrays ({@link ArrayType}) and primitive classes,
 137      * AbsentInformationException is always thrown.
 138      *
 139      * @return the string source file name
 140      * @throws AbsentInformationException if the source name is not
 141      * known
 142      */
 143     String sourceName() throws AbsentInformationException;
 144 
 145     /**
 146      * Gets the identifying names for all the source corresponding to the
 147      * declaration of this type. Interpretation of these names is
 148      * the responsibility of the source repository mechanism.
 149      * <P>
 150      * The returned names are for the specified stratum
 151      * (see {@link Location} for a description of strata).
 152      * In the reference implementation, when using the Java
 153      * programming language stratum,
 154      * the returned List contains one element: a String which is the
 155      * unqualified name of the source file containing the declaration
 156      * of this type.  In other strata the returned source names are
 157      * all the source names defined for that stratum.
 158      *
 159      * @param stratum The stratum to retrieve information from
 160      * or <code>null</code> for the declaring type's
 161      * default stratum.
 162      *
 163      * @return a List of String objects each representing a source name
 164      *
 165      * @throws AbsentInformationException if the source names are not
 166      * known.
 167      * <p>
 168      * For arrays ({@link ArrayType}) and primitive classes,
 169      * AbsentInformationException is always thrown.
 170      *
 171      * @since 1.4
 172      */
 173     List<String> sourceNames(String stratum) throws AbsentInformationException;
 174 
 175     /**
 176      * Gets the paths to the source corresponding to the
 177      * declaration of this type. Interpretation of these paths is
 178      * the responsibility of the source repository mechanism.
 179      * <P>
 180      * The returned paths are for the specified stratum
 181      * (see {@link Location} for a description of strata).
 182      * In the reference implementation, for strata which
 183      * do not explicitly specify source path (the Java
 184      * programming language stratum never does), the returned
 185      * strings are the {@link #sourceNames(String)} prefixed by
 186      * the package name of this ReferenceType
 187      * converted to a platform dependent path.
 188      * For example, on a Windows platform,
 189      * <CODE>java.lang.Thread</CODE>
 190      * would return a List containing one element:
 191      * <CODE>"java\lang\Thread.java"</CODE>.
 192      *
 193      * @param stratum The stratum to retrieve information from
 194      * or <code>null</code> for the declaring type's
 195      * default stratum.
 196      *
 197      * @return a List of String objects each representing a source path
 198      *
 199      * @throws AbsentInformationException if the source names are not
 200      * known.
 201      * <p>
 202      * For arrays ({@link ArrayType}) and primitive classes,
 203      * AbsentInformationException is always thrown.
 204      *
 205      * @since 1.4
 206      */
 207     List<String> sourcePaths(String stratum) throws AbsentInformationException;
 208 
 209     /**
 210      * Get the source debug extension of this type.
 211      * <p>
 212      * Not all target virtual machines support this operation.
 213      * Use
 214      * {@link VirtualMachine#canGetSourceDebugExtension() canGetSourceDebugExtension()}
 215      * to determine if the operation is supported.
 216      * @return as a string the source debug extension attribute
 217      * @throws AbsentInformationException if the extension is not
 218      * specified
 219      * @throws java.lang.UnsupportedOperationException if
 220      * the target virtual machine does not support this
 221      * operation - see
 222      * {@link VirtualMachine#canGetSourceDebugExtension() canGetSourceDebugExtension()},
 223      */
 224     String sourceDebugExtension() throws AbsentInformationException;
 225 
 226     /**
 227      * Determines if this type was declared static. Only nested types,
 228      * can be declared static, so <code>false</code> is returned
 229      * for any package-level type, array type, or primitive class.
 230      *
 231      * @return <code>true</code> if this type is static; false otherwise.
 232      */
 233     boolean isStatic();
 234 
 235     /**
 236      * Determines if this type was declared abstract.
 237      * <p>
 238      * For arrays ({@link ArrayType}) and primitive classes,
 239      * the return value is undefined.
 240      *
 241      * @return <code>true</code> if this type is abstract; false otherwise.
 242      */
 243     boolean isAbstract();
 244 
 245     /**
 246      * Determines if this type was declared final.
 247      * <p>
 248      * For arrays ({@link ArrayType}) and primitive classes,
 249      * the return value is always true.
 250      *
 251      * @return <code>true</code> if this type is final; false otherwise.
 252      */
 253     boolean isFinal();
 254 
 255     /**
 256      * Determines if this type has been prepared. See the JVM
 257      * specification for a definition of class preparation.
 258      * <p>
 259      * For arrays ({@link ArrayType}) and primitive classes,
 260      * the return value is undefined.
 261      *
 262      * @return <code>true</code> if this type is prepared; false otherwise.
 263      */
 264     boolean isPrepared();
 265 
 266     /**
 267      * Determines if this type has been verified. See the JVM
 268      * specification for a definition of class verification.
 269      * <p>
 270      * For arrays ({@link ArrayType}) and primitive classes,
 271      * the return value is undefined.
 272      *
 273      * @return <code>true</code> if this type is verified; false otherwise.
 274      */
 275     boolean isVerified();
 276 
 277     /**
 278      * Determines if this type has been initialized. See the JVM
 279      * specification for a definition of class verification.
 280      * For {@link InterfaceType}, this method always returns the
 281      * same value as {@link #isPrepared()}.
 282      * <p>
 283      * For arrays ({@link ArrayType}) and primitive classes,
 284      * the return value is undefined.
 285      *
 286      * @return <code>true</code> if this type is initialized; false otherwise.
 287      */
 288     boolean isInitialized();
 289 
 290     /**
 291      * Determines if initialization failed for this class. See the JVM
 292      * specification for details on class initialization.
 293      * <p>
 294      * For arrays ({@link ArrayType}) and primitive classes,
 295      * the return value is undefined.
 296      *
 297      * @return <code>true</code> if initialization was attempted and
 298      * failed; false otherwise.
 299      */
 300     boolean failedToInitialize();
 301 
 302     /**
 303      * Returns a list containing each {@link Field} declared in this type.
 304      * Inherited fields are not included. Any synthetic fields created
 305      * by the compiler are included in the list.
 306      * <p>
 307      * For arrays ({@link ArrayType}) and primitive classes, the returned
 308      * list is always empty.
 309      *
 310      * @return a list {@link Field} objects; the list has length 0
 311      * if no fields exist.
 312      * @throws ClassNotPreparedException if this class not yet been
 313      * prepared.
 314      */
 315     List<Field> fields();
 316 
 317     /**
 318      * Returns a list containing each unhidden and unambiguous {@link Field}
 319      * in this type.
 320      * Each field that can be accessed from the class
 321      * or its instances with its simple name is included. Fields that
 322      * are ambiguously multiply inherited or fields that are hidden by
 323      * fields with the same name in a more recently inherited class
 324      * cannot be accessed
 325      * by their simple names and are not included in the returned
 326      * list. All other inherited fields are included.
 327      * See JLS section 8.3 for details.
 328      * <p>
 329      * For arrays ({@link ArrayType}) and primitive classes, the returned
 330      * list is always empty.
 331      *
 332      * @return a List of {@link Field} objects; the list has length
 333      * 0 if no visible fields exist.
 334      * @throws ClassNotPreparedException if this class not yet been
 335      * prepared.
 336      */
 337     List<Field> visibleFields();
 338 
 339     /**
 340      * Returns a list containing each {@link Field} declared in this type,
 341      * and its superclasses, implemented interfaces, and/or superinterfaces.
 342      * All declared and inherited
 343      * fields are included, regardless of whether they are hidden or
 344      * multiply inherited.
 345      * <p>
 346      * For arrays ({@link ArrayType}) and primitive classes, the returned
 347      * list is always empty.
 348      *
 349      * @return a List of {@link Field} objects; the list has length
 350      * 0 if no fields exist.
 351      * @throws ClassNotPreparedException if this class not yet been
 352      * prepared.
 353      */
 354     List<Field> allFields();
 355 
 356     /**
 357      * Finds the visible {@link Field} with the given
 358      * non-ambiguous name. This method follows the
 359      * inheritance rules specified in the JLS (8.3.3) to determine
 360      * visibility.
 361      * <p>
 362      * For arrays ({@link ArrayType}) and primitive classes, the returned
 363      * value is always null.
 364      *
 365      * @param fieldName a String containing the name of desired field.
 366      * @return a {@link Field} object which mirrors the found field, or
 367      * null if there is no field with the given name or if the given
 368      * name is ambiguous.
 369      * @throws ClassNotPreparedException if this class not yet been
 370      * prepared.
 371      */
 372     Field fieldByName(String fieldName);
 373 
 374     /**
 375      * Returns a list containing each {@link Method} declared
 376      * directly in this type.
 377      * Inherited methods are not included. Constructors,
 378      * the initialization method if any, and any synthetic methods created
 379      * by the compiler are included in the list.
 380      * <p>
 381      * For arrays ({@link ArrayType}) and primitive classes, the returned
 382      * list is always empty.
 383      *
 384      * @return a list {@link Method} objects; the list has length 0
 385      * if no methods exist.
 386      * @throws ClassNotPreparedException if this class not yet been
 387      * prepared.
 388      */
 389     List<Method> methods();
 390 
 391     /**
 392      * Returns a list containing each {@link Method}
 393      * declared or inherited by this type. Methods from superclasses
 394      * or superinterfaces that that have been hidden or overridden
 395      * are not included.
 396      * <p>
 397      * Note that despite this exclusion, multiple inherited methods
 398      * with the same signature can be present in the returned list, but
 399      * at most one can be a member of a {@link ClassType}.
 400      * See JLS section 8.4.6 for details.
 401      * <p>
 402      * For arrays ({@link ArrayType}) and primitive classes, the returned
 403      * list is always empty.
 404      *
 405      * @return a List of {@link Method} objects; the list has length
 406      * 0 if no visible methods exist.
 407      * @throws ClassNotPreparedException if this class not yet been
 408      * prepared.
 409      */
 410     List<Method> visibleMethods();
 411 
 412     /**
 413      * Returns a list containing each {@link Method} declared in this type,
 414      * and its superclasses, implemented interfaces, and/or superinterfaces.
 415      * All declared and inherited
 416      * methods are included, regardless of whether they are hidden or
 417      * overridden.
 418      * <p>
 419      * For arrays ({@link ArrayType}) and primitive classes, the returned
 420      * list is always empty.
 421      *
 422      * @return a List of {@link Method} objects; the list has length
 423      * 0 if no methods exist.
 424      * @throws ClassNotPreparedException if this class not yet been
 425      * prepared.
 426      */
 427     List<Method> allMethods();
 428 
 429     /**
 430      * Returns a List containing each visible {@link Method} that
 431      * has the given name.  This is most commonly used to
 432      * find overloaded methods.
 433      * <p>
 434      * Overridden and hidden methods are not included.
 435      * See JLS (8.4.6) for details.
 436      * <p>
 437      * For arrays ({@link ArrayType}) and primitive classes, the returned
 438      * list is always empty.
 439      *
 440      * @param name the name of the method to find.
 441      * @return a List of {@link Method} objects that match the given
 442      * name; the list has length 0 if no matching methods are found.
 443      * @throws ClassNotPreparedException if this class not yet been
 444      * prepared.
 445      */
 446     List<Method> methodsByName(String name);
 447 
 448     /**
 449      * Returns a List containing each visible {@link Method} that
 450      * has the given name and signature.
 451      * The signature string is the
 452      * JNI signature for the target method:
 453      * <ul>
 454      * <li><code>()V</code>
 455      * <li><code>([Ljava/lang/String;)V</code>
 456      * <li><code>(IIII)Z</code>
 457      * </ul>
 458      * This method follows the inheritance rules specified
 459      * in the JLS (8.4.6) to determine visibility.
 460      * <p>
 461      * At most one method in the list is a concrete method and a
 462      * component of {@link ClassType}; any other methods in the list
 463      * are abstract. Use {@link ClassType#concreteMethodByName} to
 464      * retrieve only the matching concrete method.
 465      * <p>
 466      * For arrays ({@link ArrayType}) and primitive classes, the returned
 467      * list is always empty.
 468      *
 469      * @param name the name of the method to find.
 470      * @param signature the signature of the method to find
 471      * @return a List of {@link Method} objects that match the given
 472      * name and signature; the list has length 0 if no matching methods
 473      * are found.
 474      * @throws ClassNotPreparedException if this class not yet been
 475      * prepared.
 476      */
 477     List<Method> methodsByName(String name, String signature);
 478 
 479     /**
 480      * Returns a List containing {@link ReferenceType} objects that are
 481      * declared within this type and are currently loaded into the Virtual
 482      * Machine.  Both static nested types and non-static nested
 483      * types (that is, inner types) are included. Local inner types
 484      * (declared within a code block somewhere in this reference type) are
 485      * also included in the returned list.
 486      * <p>
 487      * For arrays ({@link ArrayType}) and primitive classes, the returned
 488      * list is always empty.
 489      *
 490      * @return a List of nested {@link ReferenceType} objects; the list
 491      * has 0 length if there are no nested types.
 492      */
 493     List<ReferenceType> nestedTypes();
 494 
 495     /**
 496      * Gets the {@link Value} of a given static {@link Field} in this type.
 497      * The Field must be valid for this type;
 498      * that is, it must be declared in this type, a superclass, a
 499      * superinterface, or an implemented interface.
 500      *
 501      * @param field the field containing the requested value
 502      * @return the {@link Value} of the instance field.
 503      * @throws java.lang.IllegalArgumentException if the field is not valid for
 504      * this object's class.
 505      */
 506     Value getValue(Field field);
 507 
 508     /**
 509      * Returns a map containing the {@link Value} of each
 510      * static {@link Field} in the given list.
 511      * The Fields must be valid for this type;
 512      * that is, they must be declared in this type, a superclass, a
 513      * superinterface, or an implemented interface.
 514      *
 515      * @param fields a list of {@link Field} objects containing the
 516      * requested values.
 517      * @return a Map of the requested {@link Field} objects with
 518      * their {@link Value}.
 519      * @throws java.lang.IllegalArgumentException if any field is not valid for
 520      * this object's class.
 521      * @throws VMMismatchException if a {@link Mirror} argument and this mirror
 522      * do not belong to the same {@link VirtualMachine}.
 523      */
 524     Map<Field,Value> getValues(List<? extends Field> fields);
 525 
 526     /**
 527      * Returns the class object that corresponds to this type in the
 528      * target VM. The VM creates class objects for every kind of
 529      * ReferenceType: classes, interfaces, and array types.
 530      * @return the {@link ClassObjectReference} for this reference type
 531      * in the target VM.
 532      */
 533     ClassObjectReference classObject();
 534 
 535     /**
 536      * Returns a list containing a {@link Location} object
 537      * for each executable source line in this reference type.
 538      * <P>
 539      * This method is equivalent to
 540      * <code>allLineLocations(vm.getDefaultStratum(),null)</code> -
 541      * see {@link #allLineLocations(String,String)}
 542      * for more information.
 543      *
 544      * @throws AbsentInformationException if there is no line
 545      * number information for this class and there are non-native,
 546      * non-abstract executable members of this class.
 547      *
 548      * @throws ClassNotPreparedException if this class not yet
 549      * been prepared.
 550      */
 551     List<Location> allLineLocations() throws AbsentInformationException;
 552 
 553     /**
 554      * Returns a list containing a {@link Location} object
 555      * for each executable source line in this reference type.
 556      * Each location maps a source line to a range of code
 557      * indices.
 558      * The beginning of the range can be determined through
 559      * {@link Location#codeIndex}.  The returned list may contain
 560      * multiple locations for a particular line number, if the
 561      * compiler and/or VM has mapped that line to two or more
 562      * disjoint code index ranges.  Note that it is possible for
 563      * the same source line to represent different code index
 564      * ranges in <i>different</i> methods.
 565      * <P>
 566      * For arrays ({@link ArrayType}) and primitive classes, the
 567      * returned list is always empty.  For interfaces ({@link
 568      * InterfaceType}), the returned list will be non-empty only
 569      * if the interface has executable code in its class
 570      * initialization.
 571      * <P>
 572      * Returned list is for the specified <i>stratum</i>
 573      * (see {@link Location} for a description of strata).
 574      *
 575      * @param stratum The stratum to retrieve information from
 576      * or <code>null</code> for the {@link #defaultStratum()}.
 577      *
 578      * @param sourceName Return locations only within this
 579      * source file or <code>null</code> to return locations.
 580      *
 581      * @return a List of all source line {@link Location} objects.
 582      *
 583      * @throws AbsentInformationException if there is no line
 584      * number information for this class and there are non-native,
 585      * non-abstract executable members of this class.
 586      * Or if <i>sourceName</i> is non-<code>null</code>
 587      * and source name information is not present.
 588      *
 589      * @throws ClassNotPreparedException if this class not yet
 590      * been prepared.
 591      *
 592      * @since 1.4
 593      */
 594     List<Location> allLineLocations(String stratum, String sourceName)
 595                              throws AbsentInformationException;
 596 
 597     /**
 598      * Returns a List containing all {@link Location} objects
 599      * that map to the given line number.
 600      * <P>
 601      * This method is equivalent to
 602      * <code>locationsOfLine(vm.getDefaultStratum(), null,
 603      * lineNumber)</code> -
 604      * see {@link
 605      * #locationsOfLine(java.lang.String,java.lang.String,int)}
 606      * for more information.
 607      *
 608      * @param lineNumber the line number
 609      *
 610      * @return a List of all {@link Location} objects that map to
 611      * the given line.
 612      *
 613      * @throws AbsentInformationException if there is no line
 614      * number information for this class.
 615      *
 616      * @throws ClassNotPreparedException if this class not yet
 617      * been prepared.
 618      *
 619      * @see VirtualMachine#getDefaultStratum()
 620      */
 621     List<Location> locationsOfLine(int lineNumber)
 622         throws AbsentInformationException;
 623 
 624     /**
 625      * Returns a List containing all {@link Location} objects
 626      * that map to the given line number.
 627      * <P>
 628      * For arrays ({@link ArrayType}) and primitive classes, the
 629      * returned list is always empty.
 630      * For interfaces ({@link InterfaceType}), the returned list
 631      * will be non-empty only if the interface has executable code
 632      * in its class initialization at the specified line number.
 633      * An empty list will be returned if there is no executable
 634      * code at the specified line number.
 635      * <p>
 636      * Returned list is for the specified <i>stratum</i>
 637      * (see {@link Location} for a description of strata).
 638      *
 639      * @param stratum the stratum to use for comparing line number
 640      *                and source name, or <code>null</code> to
 641      *                use the {@link #defaultStratum()}.
 642      *
 643      * @param sourceName the source name containing the line
 644      *                   number, or <code>null</code> to match
 645      *                   all source names
 646      *
 647      * @param lineNumber the line number
 648      *
 649      * @return a List of all {@link Location} objects that map
 650      *         to the given line.
 651      *
 652      * @throws AbsentInformationException if there is no line
 653      *         number information for this class.
 654      *         Or if <i>sourceName</i> is non-<code>null</code>
 655      *         and source name information is not present.
 656      *
 657      * @throws ClassNotPreparedException if this class not yet
 658      *         been prepared.
 659      *
 660      * @since 1.4
 661      */
 662     List<Location> locationsOfLine(String stratum,
 663                                    String sourceName,
 664                                    int lineNumber)
 665                      throws AbsentInformationException;
 666 
 667     /**
 668      * Return the available strata for this reference type.
 669      * <P>
 670      * See the {@link Location} for a description of strata.
 671      *
 672      * @return List of <CODE>java.lang.String</CODE>, each
 673      * representing a stratum
 674      *
 675      * @since 1.4
 676      */
 677     List<String> availableStrata();
 678 
 679     /**
 680      * Returns the default stratum for this reference type.
 681      * This value is specified in the class file and cannot
 682      * be set by the user.  If the class file does not
 683      * specify a default stratum the base stratum
 684      * (<code>"Java"</code>) will be returned.
 685      * <P>
 686      * See the {@link Location} for a description of strata.
 687      *
 688      * @since 1.4
 689      */
 690     String defaultStratum();
 691 
 692     /**
 693      * Returns instances of this ReferenceType.
 694      * Only instances that are reachable for the purposes of garbage collection
 695      * are returned.
 696      * <p>
 697      * Not all target virtual machines support this operation.
 698      * Use {@link VirtualMachine#canGetInstanceInfo()}
 699      * to determine if the operation is supported.
 700      *
 701      * @see VirtualMachine#instanceCounts(List)
 702      * @see ObjectReference#referringObjects(long)
 703      *
 704      * @param maxInstances the maximum number of instances to return.
 705      *        Must be non-negative.  If zero, all instances are returned.
 706      * @return a List of {@link ObjectReference} objects.  If there are
 707      * no instances of this ReferenceType, a zero-length list is returned.
 708      *
 709      * @throws java.lang.UnsupportedOperationException if
 710      * the target virtual machine does not support this
 711      * operation - see
 712      * {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()}
 713      * @throws java.lang.IllegalArgumentException if maxInstances is less
 714      *         than zero.
 715      * @since 1.6
 716      */
 717     List<ObjectReference> instances(long maxInstances);
 718 
 719     /**
 720      * Compares the specified Object with this ReferenceType for equality.
 721      *
 722      * @return  true if the Object is a {@link ReferenceType}, if the
 723      * ReferenceTypes belong to the same VM, and if they mirror classes
 724      * which correspond to the same instance of java.lang.Class in that VM.
 725      */
 726     boolean equals(Object obj);
 727 
 728     /**
 729      * Returns the hash code value for this ObjectReference.
 730      *
 731      * @return the integer hash code
 732      */
 733     int hashCode();
 734 
 735     /**
 736      * Returns the class major version number, as defined in the class file format
 737      * of the Java Virtual Machine Specification.
 738      *
 739      * For arrays ({@link ArrayType}) and primitive classes,
 740      * the returned major version number value is zero.
 741      *
 742      * Not all target virtual machines support this operation.
 743      * Use {@link VirtualMachine#canGetClassFileVersion()}
 744      * to determine if the operation is supported.
 745      *
 746      * @return the major version number of the class.
 747      *
 748      * @throws java.lang.UnsupportedOperationException if
 749      * the target virtual machine does not support this
 750      * operation - see
 751      * {@link VirtualMachine#canGetClassFileVersion() canGetClassFileVersion()}
 752      *
 753      * @since 1.6
 754      */
 755     int majorVersion();
 756 
 757 
 758     /**
 759      * Returns the class minor version number, as defined in the class file format
 760      * of the Java Virtual Machine Specification.
 761      *
 762      * For arrays ({@link ArrayType}) and primitive classes,
 763      * the returned minor version number value is zero.
 764      *
 765      * Not all target virtual machines support this operation.
 766      * Use {@link VirtualMachine#canGetClassFileVersion()}
 767      * to determine if the operation is supported.
 768      *
 769      * @return the minor version number of the class.
 770      *
 771      * @throws java.lang.UnsupportedOperationException if
 772      * the target virtual machine does not support this
 773      * operation - see
 774      * {@link VirtualMachine#canGetClassFileVersion() canGetClassFileVersion()}
 775      *
 776      * @since 1.6
 777      */
 778     int minorVersion();
 779 
 780     /**
 781      * Returns the number of entries in the constant pool plus one.
 782      * This corresponds to the constant_pool_count item of the Class File Format
 783      * in the Java Virtual Machine Specification.
 784      *
 785      * For arrays ({@link ArrayType}) and primitive classes,
 786      * the returned constant pool count value is zero.
 787      *
 788      * Not all target virtual machines support this operation.
 789      * Use {@link VirtualMachine#canGetConstantPool()}
 790      * to determine if the operation is supported.
 791      *
 792      * @return total number of constant pool entries for a class plus one.
 793      *
 794      * @throws java.lang.UnsupportedOperationException if
 795      * the target virtual machine does not support this
 796      * operation - see
 797      * {@link VirtualMachine#canGetConstantPool() canGetConstantPool()}
 798      *
 799      * @see #constantPool()
 800      * @since 1.6
 801      */
 802     int constantPoolCount();
 803 
 804     /**
 805      * Returns the raw bytes of the constant pool in the format of the
 806      * constant_pool item of the Class File Format in the Java Virtual
 807      * Machine Specification. The format of the constant pool may
 808      * differ between versions of the Class File Format, so, the
 809      * minor and major class version numbers should be checked for
 810      * compatibility.
 811      *
 812      * For arrays ({@link ArrayType}) and primitive classes,
 813      * a zero length byte array is returned.
 814      *
 815      * Not all target virtual machines support this operation.
 816      * Use {@link VirtualMachine#canGetConstantPool()}
 817      * to determine if the operation is supported.
 818      *
 819      * @return the raw bytes of constant pool.
 820      *
 821      * @throws java.lang.UnsupportedOperationException if
 822      * the target virtual machine does not support this
 823      * operation - see
 824      * {@link VirtualMachine#canGetConstantPool() canGetConstantPool()}
 825      *
 826      * @see #constantPoolCount()
 827      * @since 1.6
 828      */
 829      byte[] constantPool();
 830 
 831 }