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 * 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™ 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 }