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