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 /**
32 * The type of an object in a target VM. ReferenceType encompasses
33 * classes, interfaces, and array types as defined in
34 * <cite>The Java™ Language Specification</cite>.
35 * All ReferenceType objects belong to one of the following
36 * subinterfaces:
37 * {@link ClassType} for classes,
38 * {@link InterfaceType} for interfaces, and
39 * {@link ArrayType} for arrays.
40 * Note that primitive classes (for example, the
41 * {@link ClassObjectReference#reflectedType() reflected type} of
42 * {@link java.lang.Integer#TYPE Integer.TYPE})
43 * are represented as ClassType.
44 * The VM creates Class objects for all three, so from the VM perspective,
45 * each ReferenceType maps to a distinct Class object.
46 * <p>
47 * ReferenceTypes can
48 * be obtained by querying a particular {@link ObjectReference} for its
49 * type or by getting a list of all reference types from the
50 * {@link VirtualMachine}.
51 * <p>
52 * ReferenceType provides access to static type information such as
53 * methods and fields and provides access to dynamic type
54 * information such as the corresponding Class object and the classloader.
55 * <p>
56 * Any method on <code>ReferenceType</code> which directly or
57 * indirectly takes <code>ReferenceType</code> as an parameter may throw
58 * {@link com.sun.jdi.VMDisconnectedException} if the target VM is
59 * disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been or is
60 * available to be read from the {@link com.sun.jdi.event.EventQueue}.
61 * <p>
62 * Any method on <code>ReferenceType</code> which directly or
63 * indirectly takes <code>ReferenceType</code> as an parameter may throw
64 * {@link com.sun.jdi.VMOutOfMemoryException} if the target VM has run out of memory.
65 * <p>
66 * Any method on <code>ReferenceType</code> or which directly or indirectly takes
67 * <code>ReferenceType</code> as parameter may throw
68 * {@link com.sun.jdi.ObjectCollectedException} if the mirrored type has been unloaded.
69 *
70 * @see ObjectReference
71 * @see ObjectReference#referenceType
72 * @see VirtualMachine
73 * @see VirtualMachine#allClasses
74 *
75 * @author Robert Field
76 * @author Gordon Hirsch
77 * @author James McIlree
78 * @since 1.3
79 */
80 public interface ReferenceType
81 extends Type, Comparable<ReferenceType>, Accessible {
82
83 /**
84 * Gets the fully qualified name of this type. The returned name
85 * is formatted as it might appear in a Java programming langauge
86 * declaration for objects of this type.
87 * <p>
88 * For primitive classes
89 * the returned name is the name of the corresponding primitive
90 * type; for example, "int" is returned as the name of the class
91 * represented by {@link java.lang.Integer#TYPE Integer.TYPE}.
92 * @return a string containing the type name.
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 /**
781 * Returns the class minor version number, as defined in the class file format
782 * of the Java Virtual Machine Specification.
783 *
784 * For arrays ({@link ArrayType}) and primitive classes,
785 * the returned minor version number value is zero.
786 *
787 * Not all target virtual machines support this operation.
788 * Use {@link VirtualMachine#canGetClassFileVersion()}
789 * to determine if the operation is supported.
790 *
791 * @return the minor version number of the class.
792 *
793 * @throws java.lang.UnsupportedOperationException if
794 * the target virtual machine does not support this
795 * operation - see
796 * {@link VirtualMachine#canGetClassFileVersion() canGetClassFileVersion()}
797 *
798 * @since 1.6
799 */
800 int minorVersion();
801
802 /**
803 * Returns the number of entries in the constant pool plus one.
804 * This corresponds to the constant_pool_count item of the Class File Format
805 * in the Java Virtual Machine Specification.
806 *
807 * For arrays ({@link ArrayType}) and primitive classes,
808 * the returned constant pool count value is zero.
809 *
810 * Not all target virtual machines support this operation.
811 * Use {@link VirtualMachine#canGetConstantPool()}
812 * to determine if the operation is supported.
813 *
814 * @return total number of constant pool entries for a class plus one.
815 *
816 * @throws java.lang.UnsupportedOperationException if
817 * the target virtual machine does not support this
818 * operation - see
819 * {@link VirtualMachine#canGetConstantPool() canGetConstantPool()}
820 *
821 * @see #constantPool()
822 * @since 1.6
823 */
824 int constantPoolCount();
825
826 /**
827 * Returns the raw bytes of the constant pool in the format of the
828 * constant_pool item of the Class File Format in the Java Virtual
829 * Machine Specification. The format of the constant pool may
830 * differ between versions of the Class File Format, so, the
831 * minor and major class version numbers should be checked for
832 * compatibility.
833 *
834 * For arrays ({@link ArrayType}) and primitive classes,
835 * a zero length byte array is returned.
836 *
837 * Not all target virtual machines support this operation.
838 * Use {@link VirtualMachine#canGetConstantPool()}
839 * to determine if the operation is supported.
840 *
841 * @return the raw bytes of constant pool.
842 *
843 * @throws java.lang.UnsupportedOperationException if
844 * the target virtual machine does not support this
845 * operation - see
846 * {@link VirtualMachine#canGetConstantPool() canGetConstantPool()}
847 *
848 * @see #constantPoolCount()
849 * @since 1.6
850 */
851 byte[] constantPool();
852 }