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