001: /*
002: * Copyright 1998-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.jdi;
027:
028: import java.util.List;
029: import java.util.Map;
030:
031: /**
032: * The type of an object in a target VM. ReferenceType encompasses
033: * classes, interfaces, and array types as defined in the
034: * <a href="http://java.sun.com/docs/books/jls/">
035: * Java<sup><font size=-2>TM</font></sup> Language Specification</a>.
036: * All ReferenceType objects belong to one of the following
037: * subinterfaces:
038: * {@link ClassType} for classes,
039: * {@link InterfaceType} for interfaces, and
040: * {@link ArrayType} for arrays.
041: * Note that primitive classes (for example, the
042: * {@link ClassObjectReference#reflectedType() reflected type} of
043: * {@link java.lang.Integer#TYPE Integer.TYPE})
044: * are represented as ClassType.
045: * The VM creates Class objects for all three, so from the VM perspective,
046: * each ReferenceType maps to a distinct Class object.
047: * <p>
048: * ReferenceTypes can
049: * be obtained by querying a particular {@link ObjectReference} for its
050: * type or by getting a list of all reference types from the
051: * {@link VirtualMachine}.
052: * <p>
053: * ReferenceType provides access to static type information such as
054: * methods and fields and provides access to dynamic type
055: * information such as the corresponding Class object and the classloader.
056: * <p>
057: * Any method on <code>ReferenceType</code> which directly or
058: * indirectly takes <code>ReferenceType</code> as an parameter may throw
059: * {@link com.sun.jdi.VMDisconnectedException} if the target VM is
060: * disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been or is
061: * available to be read from the {@link com.sun.jdi.event.EventQueue}.
062: * <p>
063: * Any method on <code>ReferenceType</code> which directly or
064: * indirectly takes <code>ReferenceType</code> as an parameter may throw
065: * {@link com.sun.jdi.VMOutOfMemoryException} if the target VM has run out of memory.
066: * <p>
067: * Any method on <code>ReferenceType</code> or which directly or indirectly takes
068: * <code>ReferenceType</code> as parameter may throw
069: * {@link com.sun.jdi.ObjectCollectedException} if the mirrored type has been unloaded.
070: *
071: * @see ObjectReference
072: * @see ObjectReference#referenceType
073: * @see VirtualMachine
074: * @see VirtualMachine#allClasses
075: *
076: * @author Robert Field
077: * @author Gordon Hirsch
078: * @author James McIlree
079: * @since 1.3
080: */
081: public interface ReferenceType extends Type, Comparable<ReferenceType>,
082: Accessible {
083:
084: /**
085: * Gets the fully qualified name of this type. The returned name
086: * is formatted as it might appear in a Java programming langauge
087: * declaration for objects of this type.
088: * <p>
089: * For primitive classes
090: * the returned name is the name of the corresponding primitive
091: * type; for example, "int" is returned as the name of the class
092: * represented by {@link java.lang.Integer#TYPE Integer.TYPE}.
093: * @return a string containing the type name.
094: */
095: String name();
096:
097: /**
098: * Gets the generic signature for this type if there is one.
099: * Generic signatures are described in the
100: * <a href="http://java.sun.com/docs/books/vmspec">
101: * "Java<sup><font size=-2>TM</font></sup>
102: * Virtual Machine Specification, 3rd Edition.</a>
103: *
104: * @return a string containing the generic signature, or <code>null</code>
105: * if there is no generic signature.
106: *
107: * @since 1.5
108: */
109: String genericSignature();
110:
111: /**
112: * Gets the classloader object which loaded the class corresponding
113: * to this type.
114: *
115: * @return a {@link ClassLoaderReference} which mirrors the classloader,
116: * or <code>null</code> if the class was loaded through the bootstrap class
117: * loader.
118: */
119: ClassLoaderReference classLoader();
120:
121: /**
122: * Gets an identifying name for the source corresponding to the
123: * declaration of this type. Interpretation of this string is
124: * the responsibility of the source repository mechanism.
125: * <P>
126: * The returned name is dependent on VM's default stratum
127: * ({@link VirtualMachine#getDefaultStratum()}).
128: * In the reference implementation, when using the base stratum,
129: * the returned string is the
130: * unqualified name of the source file containing the declaration
131: * of this type. In other strata the returned source name is
132: * the first source name for that stratum. Since other languages
133: * may have more than one source name for a reference type,
134: * the use of {@link Location#sourceName()} or
135: * {@link #sourceNames(String)} is preferred.
136: * <p>
137: * For arrays ({@link ArrayType}) and primitive classes,
138: * AbsentInformationException is always thrown.
139: *
140: * @return the string source file name
141: * @throws AbsentInformationException if the source name is not
142: * known
143: */
144: String sourceName() throws AbsentInformationException;
145:
146: /**
147: * Gets the identifying names for all the source corresponding to the
148: * declaration of this type. Interpretation of these names is
149: * the responsibility of the source repository mechanism.
150: * <P>
151: * The returned names are for the specified stratum
152: * (see {@link Location} for a description of strata).
153: * In the reference implementation, when using the Java
154: * programming language stratum,
155: * the returned List contains one element: a String which is the
156: * unqualified name of the source file containing the declaration
157: * of this type. In other strata the returned source names are
158: * all the source names defined for that stratum.
159: *
160: * @param stratum The stratum to retrieve information from
161: * or <code>null</code> for the declaring type's
162: * default stratum.
163: *
164: * @return a List of String objects each representing a source name
165: *
166: * @throws AbsentInformationException if the source names are not
167: * known.
168: * <p>
169: * For arrays ({@link ArrayType}) and primitive classes,
170: * AbsentInformationException is always thrown.
171: *
172: * @since 1.4
173: */
174: List<String> sourceNames(String stratum)
175: throws AbsentInformationException;
176:
177: /**
178: * Gets the paths to the source corresponding to the
179: * declaration of this type. Interpretation of these paths is
180: * the responsibility of the source repository mechanism.
181: * <P>
182: * The returned paths are for the specified stratum
183: * (see {@link Location} for a description of strata).
184: * In the reference implementation, for strata which
185: * do not explicitly specify source path (the Java
186: * programming language stratum never does), the returned
187: * strings are the {@link #sourceNames(String)} prefixed by
188: * the package name of this ReferenceType
189: * converted to a platform dependent path.
190: * For example, on a Windows platform,
191: * <CODE>java.lang.Thread</CODE>
192: * would return a List containing one element:
193: * <CODE>"java\lang\Thread.java"</CODE>.
194: *
195: * @param stratum The stratum to retrieve information from
196: * or <code>null</code> for the declaring type's
197: * default stratum.
198: *
199: * @return a List of String objects each representing a source path
200: *
201: * @throws AbsentInformationException if the source names are not
202: * known.
203: * <p>
204: * For arrays ({@link ArrayType}) and primitive classes,
205: * AbsentInformationException is always thrown.
206: *
207: * @since 1.4
208: */
209: List<String> sourcePaths(String stratum)
210: throws AbsentInformationException;
211:
212: /**
213: * Get the source debug extension of this type.
214: * <p>
215: * Not all target virtual machines support this operation.
216: * Use
217: * {@link VirtualMachine#canGetSourceDebugExtension() canGetSourceDebugExtension()}
218: * to determine if the operation is supported.
219: * @return as a string the source debug extension attribute
220: * @throws AbsentInformationException if the extension is not
221: * specified
222: * @throws java.lang.UnsupportedOperationException if
223: * the target virtual machine does not support this
224: * operation - see
225: * {@link VirtualMachine#canGetSourceDebugExtension() canGetSourceDebugExtension()},
226: */
227: String sourceDebugExtension() throws AbsentInformationException;
228:
229: /**
230: * Determines if this type was declared static. Only nested types,
231: * can be declared static, so <code>false</code> is returned
232: * for any package-level type, array type, or primitive class.
233: *
234: * @return <code>true</code> if this type is static; false otherwise.
235: */
236: boolean isStatic();
237:
238: /**
239: * Determines if this type was declared abstract.
240: * <p>
241: * For arrays ({@link ArrayType}) and primitive classes,
242: * the return value is undefined.
243: *
244: * @return <code>true</code> if this type is abstract; false otherwise.
245: */
246: boolean isAbstract();
247:
248: /**
249: * Determines if this type was declared final.
250: * <p>
251: * For arrays ({@link ArrayType}) and primitive classes,
252: * the return value is always true.
253: *
254: * @return <code>true</code> if this type is final; false otherwise.
255: */
256: boolean isFinal();
257:
258: /**
259: * Determines if this type has been prepared. See the JVM
260: * specification for a definition of class preparation.
261: * <p>
262: * For arrays ({@link ArrayType}) and primitive classes,
263: * the return value is undefined.
264: *
265: * @return <code>true</code> if this type is prepared; false otherwise.
266: */
267: boolean isPrepared();
268:
269: /**
270: * Determines if this type has been verified. See the JVM
271: * specification for a definition of class verification.
272: * <p>
273: * For arrays ({@link ArrayType}) and primitive classes,
274: * the return value is undefined.
275: *
276: * @return <code>true</code> if this type is verified; false otherwise.
277: */
278: boolean isVerified();
279:
280: /**
281: * Determines if this type has been initialized. See the JVM
282: * specification for a definition of class verification.
283: * For {@link InterfaceType}, this method always returns the
284: * same value as {@link #isPrepared()}.
285: * <p>
286: * For arrays ({@link ArrayType}) and primitive classes,
287: * the return value is undefined.
288: *
289: * @return <code>true</code> if this type is initialized; false otherwise.
290: */
291: boolean isInitialized();
292:
293: /**
294: * Determines if initialization failed for this class. See the JVM
295: * specification for details on class initialization.
296: * <p>
297: * For arrays ({@link ArrayType}) and primitive classes,
298: * the return value is undefined.
299: *
300: * @return <code>true</code> if initialization was attempted and
301: * failed; false otherwise.
302: */
303: boolean failedToInitialize();
304:
305: /**
306: * Returns a list containing each {@link Field} declared in this type.
307: * Inherited fields are not included. Any synthetic fields created
308: * by the compiler are included in the list.
309: * <p>
310: * For arrays ({@link ArrayType}) and primitive classes, the returned
311: * list is always empty.
312: *
313: * @return a list {@link Field} objects; the list has length 0
314: * if no fields exist.
315: * @throws ClassNotPreparedException if this class not yet been
316: * prepared.
317: */
318: List<Field> fields();
319:
320: /**
321: * Returns a list containing each unhidden and unambiguous {@link Field}
322: * in this type.
323: * Each field that can be accessed from the class
324: * or its instances with its simple name is included. Fields that
325: * are ambiguously multiply inherited or fields that are hidden by
326: * fields with the same name in a more recently inherited class
327: * cannot be accessed
328: * by their simple names and are not included in the returned
329: * list. All other inherited fields are included.
330: * See JLS section 8.3 for details.
331: * <p>
332: * For arrays ({@link ArrayType}) and primitive classes, the returned
333: * list is always empty.
334: *
335: * @return a List of {@link Field} objects; the list has length
336: * 0 if no visible fields exist.
337: * @throws ClassNotPreparedException if this class not yet been
338: * prepared.
339: */
340: List<Field> visibleFields();
341:
342: /**
343: * Returns a list containing each {@link Field} declared in this type,
344: * and its superclasses, implemented interfaces, and/or superinterfaces.
345: * All declared and inherited
346: * fields are included, regardless of whether they are hidden or
347: * multiply inherited.
348: * <p>
349: * For arrays ({@link ArrayType}) and primitive classes, the returned
350: * list is always empty.
351: *
352: * @return a List of {@link Field} objects; the list has length
353: * 0 if no fields exist.
354: * @throws ClassNotPreparedException if this class not yet been
355: * prepared.
356: */
357: List<Field> allFields();
358:
359: /**
360: * Finds the visible {@link Field} with the given
361: * non-ambiguous name. This method follows the
362: * inheritance rules specified in the JLS (8.3.3) to determine
363: * visibility.
364: * <p>
365: * For arrays ({@link ArrayType}) and primitive classes, the returned
366: * value is always null.
367: *
368: * @param fieldName a String containing the name of desired field.
369: * @return a {@link Field} object which mirrors the found field, or
370: * null if there is no field with the given name or if the given
371: * name is ambiguous.
372: * @throws ClassNotPreparedException if this class not yet been
373: * prepared.
374: */
375: Field fieldByName(String fieldName);
376:
377: /**
378: * Returns a list containing each {@link Method} declared
379: * directly in this type.
380: * Inherited methods are not included. Constructors,
381: * the initialization method if any, and any synthetic methods created
382: * by the compiler are included in the list.
383: * <p>
384: * For arrays ({@link ArrayType}) and primitive classes, the returned
385: * list is always empty.
386: *
387: * @return a list {@link Method} objects; the list has length 0
388: * if no methods exist.
389: * @throws ClassNotPreparedException if this class not yet been
390: * prepared.
391: */
392: List<Method> methods();
393:
394: /**
395: * Returns a list containing each {@link Method}
396: * declared or inherited by this type. Methods from superclasses
397: * or superinterfaces that that have been hidden or overridden
398: * are not included.
399: * <p>
400: * Note that despite this exclusion, multiple inherited methods
401: * with the same signature can be present in the returned list, but
402: * at most one can be a member of a {@link ClassType}.
403: * See JLS section 8.4.6 for details.
404: * <p>
405: * For arrays ({@link ArrayType}) and primitive classes, the returned
406: * list is always empty.
407: *
408: * @return a List of {@link Method} objects; the list has length
409: * 0 if no visible methods exist.
410: * @throws ClassNotPreparedException if this class not yet been
411: * prepared.
412: */
413: List<Method> visibleMethods();
414:
415: /**
416: * Returns a list containing each {@link Method} declared in this type,
417: * and its superclasses, implemented interfaces, and/or superinterfaces.
418: * All declared and inherited
419: * methods are included, regardless of whether they are hidden or
420: * overridden.
421: * <p>
422: * For arrays ({@link ArrayType}) and primitive classes, the returned
423: * list is always empty.
424: *
425: * @return a List of {@link Method} objects; the list has length
426: * 0 if no methods exist.
427: * @throws ClassNotPreparedException if this class not yet been
428: * prepared.
429: */
430: List<Method> allMethods();
431:
432: /**
433: * Returns a List containing each visible {@link Method} that
434: * has the given name. This is most commonly used to
435: * find overloaded methods.
436: * <p>
437: * Overridden and hidden methods are not included.
438: * See JLS (8.4.6) for details.
439: * <p>
440: * For arrays ({@link ArrayType}) and primitive classes, the returned
441: * list is always empty.
442: *
443: * @param name the name of the method to find.
444: * @return a List of {@link Method} objects that match the given
445: * name; the list has length 0 if no matching methods are found.
446: * @throws ClassNotPreparedException if this class not yet been
447: * prepared.
448: */
449: List<Method> methodsByName(String name);
450:
451: /**
452: * Returns a List containing each visible {@link Method} that
453: * has the given name and signature.
454: * The signature string is the
455: * JNI signature for the target method:
456: * <ul>
457: * <li><code>()V</code>
458: * <li><code>([Ljava/lang/String;)V</code>
459: * <li><code>(IIII)Z</code>
460: * </ul>
461: * This method follows the inheritance rules specified
462: * in the JLS (8.4.6) to determine visibility.
463: * <p>
464: * At most one method in the list is a concrete method and a
465: * component of {@link ClassType}; any other methods in the list
466: * are abstract. Use {@link ClassType#concreteMethodByName} to
467: * retrieve only the matching concrete method.
468: * <p>
469: * For arrays ({@link ArrayType}) and primitive classes, the returned
470: * list is always empty.
471: *
472: * @param name the name of the method to find.
473: * @param signature the signature of the method to find
474: * @return a List of {@link Method} objects that match the given
475: * name and signature; the list has length 0 if no matching methods
476: * are found.
477: * @throws ClassNotPreparedException if this class not yet been
478: * prepared.
479: */
480: List<Method> methodsByName(String name, String signature);
481:
482: /**
483: * Returns a List containing {@link ReferenceType} objects that are
484: * declared within this type and are currently loaded into the Virtual
485: * Machine. Both static nested types and non-static nested
486: * types (that is, inner types) are included. Local inner types
487: * (declared within a code block somewhere in this reference type) are
488: * also included in the returned list.
489: * <p>
490: * For arrays ({@link ArrayType}) and primitive classes, the returned
491: * list is always empty.
492: *
493: * @return a List of nested {@link ReferenceType} objects; the list
494: * has 0 length if there are no nested types.
495: */
496: List<ReferenceType> nestedTypes();
497:
498: /**
499: * Gets the {@link Value} of a given static {@link Field} in this type.
500: * The Field must be valid for this type;
501: * that is, it must be declared in this type, a superclass, a
502: * superinterface, or an implemented interface.
503: *
504: * @param field the field containing the requested value
505: * @return the {@link Value} of the instance field.
506: * @throws java.lang.IllegalArgumentException if the field is not valid for
507: * this object's class.
508: */
509: Value getValue(Field field);
510:
511: /**
512: * Returns a map containing the {@link Value} of each
513: * static {@link Field} in the given list.
514: * The Fields must be valid for this type;
515: * that is, they must be declared in this type, a superclass, a
516: * superinterface, or an implemented interface.
517: *
518: * @param fields a list of {@link Field} objects containing the
519: * requested values.
520: * @return a Map of the requested {@link Field} objects with
521: * their {@link Value}.
522: * @throws java.lang.IllegalArgumentException if any field is not valid for
523: * this object's class.
524: * @throws VMMismatchException if a {@link Mirror} argument and this mirror
525: * do not belong to the same {@link VirtualMachine}.
526: */
527: Map<Field, Value> getValues(List<? extends Field> fields);
528:
529: /**
530: * Returns the class object that corresponds to this type in the
531: * target VM. The VM creates class objects for every kind of
532: * ReferenceType: classes, interfaces, and array types.
533: * @return the {@link ClassObjectReference} for this reference type
534: * in the target VM.
535: */
536: ClassObjectReference classObject();
537:
538: /**
539: * Returns a list containing a {@link Location} object
540: * for each executable source line in this reference type.
541: * <P>
542: * This method is equivalent to
543: * <code>allLineLocations(vm.getDefaultStratum(),null)</code> -
544: * see {@link #allLineLocations(String,String)}
545: * for more information.
546: *
547: * @throws AbsentInformationException if there is no line
548: * number information for this class and there are non-native,
549: * non-abstract executable members of this class.
550: *
551: * @throws ClassNotPreparedException if this class not yet
552: * been prepared.
553: */
554: List<Location> allLineLocations() throws AbsentInformationException;
555:
556: /**
557: * Returns a list containing a {@link Location} object
558: * for each executable source line in this reference type.
559: * Each location maps a source line to a range of code
560: * indices.
561: * The beginning of the range can be determined through
562: * {@link Location#codeIndex}. The returned list may contain
563: * multiple locations for a particular line number, if the
564: * compiler and/or VM has mapped that line to two or more
565: * disjoint code index ranges. Note that it is possible for
566: * the same source line to represent different code index
567: * ranges in <i>different</i> methods.
568: * <P>
569: * For arrays ({@link ArrayType}) and primitive classes, the
570: * returned list is always empty. For interfaces ({@link
571: * InterfaceType}), the returned list will be non-empty only
572: * if the interface has executable code in its class
573: * initialization.
574: * <P>
575: * Returned list is for the specified <i>stratum</i>
576: * (see {@link Location} for a description of strata).
577: *
578: * @param stratum The stratum to retrieve information from
579: * or <code>null</code> for the {@link #defaultStratum()}.
580: *
581: * @param sourceName Return locations only within this
582: * source file or <code>null</code> to return locations.
583: *
584: * @return a List of all source line {@link Location} objects.
585: *
586: * @throws AbsentInformationException if there is no line
587: * number information for this class and there are non-native,
588: * non-abstract executable members of this class.
589: * Or if <i>sourceName</i> is non-<code>null</code>
590: * and source name information is not present.
591: *
592: * @throws ClassNotPreparedException if this class not yet
593: * been prepared.
594: *
595: * @since 1.4
596: */
597: List<Location> allLineLocations(String stratum, String sourceName)
598: throws AbsentInformationException;
599:
600: /**
601: * Returns a List containing all {@link Location} objects
602: * that map to the given line number.
603: * <P>
604: * This method is equivalent to
605: * <code>locationsOfLine(vm.getDefaultStratum(), null,
606: * lineNumber)</code> -
607: * see {@link
608: * #locationsOfLine(java.lang.String,java.lang.String,int)}
609: * for more information.
610: *
611: * @param lineNumber the line number
612: *
613: * @return a List of all {@link Location} objects that map to
614: * the given line.
615: *
616: * @throws AbsentInformationException if there is no line
617: * number information for this class.
618: *
619: * @throws ClassNotPreparedException if this class not yet
620: * been prepared.
621: *
622: * @see VirtualMachine#getDefaultStratum()
623: */
624: List<Location> locationsOfLine(int lineNumber)
625: throws AbsentInformationException;
626:
627: /**
628: * Returns a List containing all {@link Location} objects
629: * that map to the given line number.
630: * <P>
631: * For arrays ({@link ArrayType}) and primitive classes, the
632: * returned list is always empty.
633: * For interfaces ({@link InterfaceType}), the returned list
634: * will be non-empty only if the interface has executable code
635: * in its class initialization at the specified line number.
636: * An empty list will be returned if there is no executable
637: * code at the specified line number.
638: * <p>
639: * Returned list is for the specified <i>stratum</i>
640: * (see {@link Location} for a description of strata).
641: *
642: * @param stratum the stratum to use for comparing line number
643: * and source name, or <code>null</code> to
644: * use the {@link #defaultStratum()}.
645: *
646: * @param sourceName the source name containing the line
647: * number, or <code>null</code> to match
648: * all source names
649: *
650: * @param lineNumber the line number
651: *
652: * @return a List of all {@link Location} objects that map
653: * to the given line.
654: *
655: * @throws AbsentInformationException if there is no line
656: * number information for this class.
657: * Or if <i>sourceName</i> is non-<code>null</code>
658: * and source name information is not present.
659: *
660: * @throws ClassNotPreparedException if this class not yet
661: * been prepared.
662: *
663: * @since 1.4
664: */
665: List<Location> locationsOfLine(String stratum, String sourceName,
666: int lineNumber) throws AbsentInformationException;
667:
668: /**
669: * Return the available strata for this reference type.
670: * <P>
671: * See the {@link Location} for a description of strata.
672: *
673: * @return List of <CODE>java.lang.String</CODE>, each
674: * representing a stratum
675: *
676: * @since 1.4
677: */
678: List<String> availableStrata();
679:
680: /**
681: * Returns the default stratum for this reference type.
682: * This value is specified in the class file and cannot
683: * be set by the user. If the class file does not
684: * specify a default stratum the base stratum
685: * (<code>"Java"</code>) will be returned.
686: * <P>
687: * See the {@link Location} for a description of strata.
688: *
689: * @since 1.4
690: */
691: String defaultStratum();
692:
693: /**
694: * Returns instances of this ReferenceType.
695: * Only instances that are reachable for the purposes of garbage collection
696: * are returned.
697: * <p>
698: * Not all target virtual machines support this operation.
699: * Use {@link VirtualMachine#canGetInstanceInfo()}
700: * to determine if the operation is supported.
701: *
702: * @see VirtualMachine#instanceCounts(List)
703: * @see ObjectReference#referringObjects(long)
704: *
705: * @param maxInstances the maximum number of instances to return.
706: * Must be non-negative. If zero, all instances are returned.
707: * @return a List of {@link ObjectReference} objects. If there are
708: * no instances of this ReferenceType, a zero-length list is returned.
709: *
710: * @throws java.lang.UnsupportedOperationException if
711: * the target virtual machine does not support this
712: * operation - see
713: * {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()}
714: * @throws java.lang.IllegalArgumentException if maxInstances is less
715: * than zero.
716: * @since 1.6
717: */
718: List<ObjectReference> instances(long maxInstances);
719:
720: /**
721: * Compares the specified Object with this ReferenceType for equality.
722: *
723: * @return true if the Object is a {@link ReferenceType}, if the
724: * ReferenceTypes belong to the same VM, and if they mirror classes
725: * which correspond to the same instance of java.lang.Class in that VM.
726: */
727: boolean equals(Object obj);
728:
729: /**
730: * Returns the hash code value for this ObjectReference.
731: *
732: * @return the integer hash code
733: */
734: int hashCode();
735:
736: /**
737: * Returns the class major version number, as defined in the class file format
738: * of the Java Virtual Machine Specification.
739: *
740: * For arrays ({@link ArrayType}) and primitive classes,
741: * the returned major version number value is zero.
742: *
743: * Not all target virtual machines support this operation.
744: * Use {@link VirtualMachine#canGetClassFileVersion()}
745: * to determine if the operation is supported.
746: *
747: * @return the major version number of the class.
748: *
749: * @throws java.lang.UnsupportedOperationException if
750: * the target virtual machine does not support this
751: * operation - see
752: * {@link VirtualMachine#canGetClassFileVersion() canGetClassFileVersion()}
753: *
754: * @since 1.6
755: */
756: int majorVersion();
757:
758: /**
759: * Returns the class minor 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 minor 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 minor 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 minorVersion();
779:
780: /**
781: * Returns the number of entries in the constant pool plus one.
782: * This corresponds to the constant_pool_count item of the Class File Format
783: * in the Java Virtual Machine Specification.
784: *
785: * For arrays ({@link ArrayType}) and primitive classes,
786: * the returned constant pool count value is zero.
787: *
788: * Not all target virtual machines support this operation.
789: * Use {@link VirtualMachine#canGetConstantPool()}
790: * to determine if the operation is supported.
791: *
792: * @return total number of constant pool entries for a class plus one.
793: *
794: * @throws java.lang.UnsupportedOperationException if
795: * the target virtual machine does not support this
796: * operation - see
797: * {@link VirtualMachine#canGetConstantPool() canGetConstantPool()}
798: *
799: * @see #constantPool()
800: * @since 1.6
801: */
802: int constantPoolCount();
803:
804: /**
805: * Returns the raw bytes of the constant pool in the format of the
806: * constant_pool item of the Class File Format in the Java Virtual
807: * Machine Specification. The format of the constant pool may
808: * differ between versions of the Class File Format, so, the
809: * minor and major class version numbers should be checked for
810: * compatibility.
811: *
812: * For arrays ({@link ArrayType}) and primitive classes,
813: * a zero length byte array is returned.
814: *
815: * Not all target virtual machines support this operation.
816: * Use {@link VirtualMachine#canGetConstantPool()}
817: * to determine if the operation is supported.
818: *
819: * @return the raw bytes of constant pool.
820: *
821: * @throws java.lang.UnsupportedOperationException if
822: * the target virtual machine does not support this
823: * operation - see
824: * {@link VirtualMachine#canGetConstantPool() canGetConstantPool()}
825: *
826: * @see #constantPoolCount()
827: * @since 1.6
828: */
829: byte[] constantPool();
830:
831: }
|