1 /*
2 * Copyright (c) 1998, 2026, 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 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.8 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.8) 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.8) 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 * <div class="preview-block">
523 * <div class="preview-comment">
524 * If preview features are enabled, this method does not prevent a
525 * strictly-initialized field from being read before it has been initialized.
526 * </div>
527 * </div>
528 * @param field the field containing the requested value
529 * @return the {@link Value} of the instance field.
530 * @throws java.lang.IllegalArgumentException if the field is not valid for
531 * this object's class.
532 */
533 Value getValue(Field field);
534
535 /**
536 * Returns a map containing the {@link Value} of each
537 * static {@link Field} in the given list.
538 * The Fields must be valid for this type;
539 * that is, they must be declared in this type, a superclass, a
540 * superinterface, or an implemented interface.
541 * <div class="preview-block">
542 * <div class="preview-comment">
543 * If preview features are enabled, this method does not prevent a
544 * strictly-initialized field from being read before it has been initialized.
545 * </div>
546 * </div>
547 *
548 * @param fields a list of {@link Field} objects containing the
549 * requested values.
550 * @return a Map of the requested {@link Field} objects with
551 * their {@link Value}.
552 * @throws java.lang.IllegalArgumentException if any field is not valid for
553 * this object's class.
554 * @throws VMMismatchException if a {@link Mirror} argument and this mirror
555 * do not belong to the same {@link VirtualMachine}.
556 */
557 Map<Field,Value> getValues(List<? extends Field> fields);
558
559 /**
560 * Returns the class object that corresponds to this type in the
561 * target VM. The VM creates class objects for every kind of
562 * ReferenceType: classes, interfaces, and array types.
563 * @return the {@link ClassObjectReference} for this reference type
564 * in the target VM.
565 */
566 ClassObjectReference classObject();
567
568 /**
569 * Returns a list containing a {@link Location} object
570 * for each executable source line in this reference type.
571 * <P>
572 * This method is equivalent to
573 * <code>allLineLocations(vm.getDefaultStratum(),null)</code> -
574 * see {@link #allLineLocations(String,String)}
575 * for more information.
576 *
577 * @throws AbsentInformationException if there is no line
578 * number information for this class and there are non-native,
579 * non-abstract executable members of this class.
580 *
581 * @throws ClassNotPreparedException if this class not yet
582 * been prepared.
583 */
584 List<Location> allLineLocations() throws AbsentInformationException;
585
586 /**
587 * Returns a list containing a {@link Location} object
588 * for each executable source line in this reference type.
589 * Each location maps a source line to a range of code
590 * indices.
591 * The beginning of the range can be determined through
592 * {@link Location#codeIndex}. The returned list may contain
593 * multiple locations for a particular line number, if the
594 * compiler and/or VM has mapped that line to two or more
595 * disjoint code index ranges. Note that it is possible for
596 * the same source line to represent different code index
597 * ranges in <i>different</i> methods.
598 * <P>
599 * For arrays ({@link ArrayType}) and primitive classes, the
600 * returned list is always empty. For interfaces ({@link
601 * InterfaceType}), the returned list will be non-empty only
602 * if the interface has executable code in its class
603 * initialization.
604 * <P>
605 * Returned list is for the specified <i>stratum</i>
606 * (see {@link Location} for a description of strata).
607 *
608 * @param stratum The stratum to retrieve information from
609 * or <code>null</code> for the {@link #defaultStratum()}.
610 *
611 * @param sourceName Return locations only within this
612 * source file or <code>null</code> to return locations.
613 *
614 * @return a List of all source line {@link Location} objects.
615 *
616 * @throws AbsentInformationException if there is no line
617 * number information for this class and there are non-native,
618 * non-abstract executable members of this class.
619 * Or if <i>sourceName</i> is non-<code>null</code>
620 * and source name information is not present.
621 *
622 * @throws ClassNotPreparedException if this class not yet
623 * been prepared.
624 *
625 * @since 1.4
626 */
627 List<Location> allLineLocations(String stratum, String sourceName)
628 throws AbsentInformationException;
629
630 /**
631 * Returns a List containing all {@link Location} objects
632 * that map to the given line number.
633 * <P>
634 * This method is equivalent to
635 * <code>locationsOfLine(vm.getDefaultStratum(), null,
636 * lineNumber)</code> -
637 * see {@link
638 * #locationsOfLine(java.lang.String,java.lang.String,int)}
639 * for more information.
640 *
641 * @param lineNumber the line number
642 *
643 * @return a List of all {@link Location} objects that map to
644 * the given line.
645 *
646 * @throws AbsentInformationException if there is no line
647 * number information for this class.
648 *
649 * @throws ClassNotPreparedException if this class not yet
650 * been prepared.
651 *
652 * @see VirtualMachine#getDefaultStratum()
653 */
654 List<Location> locationsOfLine(int lineNumber)
655 throws AbsentInformationException;
656
657 /**
658 * Returns a List containing all {@link Location} objects
659 * that map to the given line number.
660 * <P>
661 * For arrays ({@link ArrayType}) and primitive classes, the
662 * returned list is always empty.
663 * For interfaces ({@link InterfaceType}), the returned list
664 * will be non-empty only if the interface has executable code
665 * in its class initialization at the specified line number.
666 * An empty list will be returned if there is no executable
667 * code at the specified line number.
668 * <p>
669 * Returned list is for the specified <i>stratum</i>
670 * (see {@link Location} for a description of strata).
671 *
672 * @param stratum the stratum to use for comparing line number
673 * and source name, or <code>null</code> to
674 * use the {@link #defaultStratum()}.
675 *
676 * @param sourceName the source name containing the line
677 * number, or <code>null</code> to match
678 * all source names
679 *
680 * @param lineNumber the line number
681 *
682 * @return a List of all {@link Location} objects that map
683 * to the given line.
684 *
685 * @throws AbsentInformationException if there is no line
686 * number information for this class.
687 * Or if <i>sourceName</i> is non-<code>null</code>
688 * and source name information is not present.
689 *
690 * @throws ClassNotPreparedException if this class not yet
691 * been prepared.
692 *
693 * @since 1.4
694 */
695 List<Location> locationsOfLine(String stratum,
696 String sourceName,
697 int lineNumber)
698 throws AbsentInformationException;
699
700 /**
701 * Return the available strata for this reference type.
702 * <P>
703 * See the {@link Location} for a description of strata.
704 *
705 * @return List of <CODE>java.lang.String</CODE>, each
706 * representing a stratum
707 *
708 * @since 1.4
709 */
710 List<String> availableStrata();
711
712 /**
713 * Returns the default stratum for this reference type.
714 * This value is specified in the class file and cannot
715 * be set by the user. If the class file does not
716 * specify a default stratum the base stratum
717 * (<code>"Java"</code>) will be returned.
718 * <P>
719 * See the {@link Location} for a description of strata.
720 *
721 * @since 1.4
722 */
723 String defaultStratum();
724
725 /**
726 * Returns instances of this ReferenceType.
727 * Only instances that are reachable for the purposes of garbage collection
728 * are returned.
729 * <p>
730 * Not all target virtual machines support this operation.
731 * Use {@link VirtualMachine#canGetInstanceInfo()}
732 * to determine if the operation is supported.
733 *
734 * @see VirtualMachine#instanceCounts(List)
735 * @see ObjectReference#referringObjects(long)
736 *
737 * @param maxInstances the maximum number of instances to return.
738 * Must be non-negative. If zero, all instances are returned.
739 * @return a List of {@link ObjectReference} objects. If there are
740 * no instances of this ReferenceType, a zero-length list is returned.
741 *
742 * @throws java.lang.UnsupportedOperationException if
743 * the target virtual machine does not support this
744 * operation - see
745 * {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()}
746 * @throws java.lang.IllegalArgumentException if maxInstances is less
747 * than zero.
748 * @since 1.6
749 */
750 List<ObjectReference> instances(long maxInstances);
751
752 /**
753 * Compares the specified Object with this ReferenceType for equality.
754 *
755 * @return true if the Object is a {@link ReferenceType}, if the
756 * ReferenceTypes belong to the same VM, and if they mirror classes
757 * which correspond to the same instance of java.lang.Class in that VM.
758 */
759 boolean equals(Object obj);
760
761 /**
762 * Returns the hash code value for this ObjectReference.
763 *
764 * @return the integer hash code
765 */
766 int hashCode();
767
768 /**
769 * Returns the class major version number, as defined in the class file format
770 * of the Java Virtual Machine Specification.
771 *
772 * For arrays ({@link ArrayType}) and primitive classes,
773 * the returned major version number value is zero.
774 *
775 * Not all target virtual machines support this operation.
776 * Use {@link VirtualMachine#canGetClassFileVersion()}
777 * to determine if the operation is supported.
778 *
779 * @return the major version number of the class.
780 *
781 * @throws java.lang.UnsupportedOperationException if
782 * the target virtual machine does not support this
783 * operation - see
784 * {@link VirtualMachine#canGetClassFileVersion() canGetClassFileVersion()}
785 *
786 * @since 1.6
787 */
788 int majorVersion();
789
790 /**
791 * Returns the class minor version number, as defined in the class file format
792 * of the Java Virtual Machine Specification.
793 *
794 * For arrays ({@link ArrayType}) and primitive classes,
795 * the returned minor version number value is zero.
796 *
797 * Not all target virtual machines support this operation.
798 * Use {@link VirtualMachine#canGetClassFileVersion()}
799 * to determine if the operation is supported.
800 *
801 * @return the minor version number of the class.
802 *
803 * @throws java.lang.UnsupportedOperationException if
804 * the target virtual machine does not support this
805 * operation - see
806 * {@link VirtualMachine#canGetClassFileVersion() canGetClassFileVersion()}
807 *
808 * @since 1.6
809 */
810 int minorVersion();
811
812 /**
813 * Returns the number of entries in the constant pool plus one.
814 * This corresponds to the constant_pool_count item of the Class File Format
815 * in the Java Virtual Machine Specification.
816 *
817 * For arrays ({@link ArrayType}) and primitive classes,
818 * the returned constant pool count value is zero.
819 *
820 * Not all target virtual machines support this operation.
821 * Use {@link VirtualMachine#canGetConstantPool()}
822 * to determine if the operation is supported.
823 *
824 * @return total number of constant pool entries for a class plus one.
825 *
826 * @throws java.lang.UnsupportedOperationException if
827 * the target virtual machine does not support this
828 * operation - see
829 * {@link VirtualMachine#canGetConstantPool() canGetConstantPool()}
830 *
831 * @see #constantPool()
832 * @since 1.6
833 */
834 int constantPoolCount();
835
836 /**
837 * Returns the raw bytes of the constant pool in the format of the
838 * constant_pool item of the Class File Format in the Java Virtual
839 * Machine Specification. The format of the constant pool may
840 * differ between versions of the Class File Format, so, the
841 * minor and major class version numbers should be checked for
842 * compatibility.
843 *
844 * For arrays ({@link ArrayType}) and primitive classes,
845 * a zero length byte array is returned.
846 *
847 * Not all target virtual machines support this operation.
848 * Use {@link VirtualMachine#canGetConstantPool()}
849 * to determine if the operation is supported.
850 *
851 * @return the raw bytes of constant pool.
852 *
853 * @throws java.lang.UnsupportedOperationException if
854 * the target virtual machine does not support this
855 * operation - see
856 * {@link VirtualMachine#canGetConstantPool() canGetConstantPool()}
857 *
858 * @see #constantPoolCount()
859 * @since 1.6
860 */
861 byte[] constantPool();
862 }