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