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