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: * An object that currently exists in the target VM. An ObjectReference
033: * mirrors only the object itself and is not specific to any
034: * {@link Field} or {@link LocalVariable} to which it is currently
035: * assigned. An ObjectReference can
036: * have 0 or more references from field(s) and/or variable(s).
037: * <p>
038: * Any method on <code>ObjectReference</code> which directly or
039: * indirectly takes <code>ObjectReference</code> as an parameter may throw
040: * {@link com.sun.jdi.VMDisconnectedException} if the target VM is
041: * disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been or is
042: * available to be read from the {@link com.sun.jdi.event.EventQueue}.
043: * <p>
044: * Any method on <code>ObjectReference</code> which directly or
045: * indirectly takes <code>ObjectReference</code> as an parameter may throw
046: * {@link com.sun.jdi.VMOutOfMemoryException} if the target VM has run out of memory.
047: * <p>
048: * Any method on <code>ObjectReference</code> or which directly or indirectly takes
049: * <code>ObjectReference</code> as parameter may throw
050: * {@link com.sun.jdi.ObjectCollectedException} if the mirrored object has been
051: * garbage collected.
052: *
053: * @author Robert Field
054: * @author Gordon Hirsch
055: * @author James McIlree
056: * @since 1.3
057: */
058: public interface ObjectReference extends Value {
059: /**
060: * Gets the {@link ReferenceType} that mirrors the type
061: * of this object. The type may be a subclass or implementor of the
062: * declared type of any field or variable which currently holds it.
063: * For example, right after the following statement.
064: * <p>
065: * <code>Object obj = new String("Hello, world!");</code>
066: * <p>
067: * The ReferenceType of obj will mirror java.lang.String and not
068: * java.lang.Object.
069: * <p>
070: * The type of an object never changes, so this method will
071: * always return the same ReferenceType over the lifetime of the
072: * mirrored object.
073: * <p>
074: * The returned ReferenceType will be a {@link ClassType} or
075: * {@link ArrayType} and never an {@link InterfaceType}.
076: *
077: * @return the {@link ReferenceType} for this object.
078: */
079: ReferenceType referenceType();
080:
081: /**
082: * Gets the value of a given instance or static field in this object.
083: * The Field must be valid for this ObjectReference;
084: * that is, it must be from
085: * the mirrored object's class or a superclass of that class.
086: *
087: * @param sig the field containing the requested value
088: * @return the {@link Value} of the instance field.
089: * @throws java.lang.IllegalArgumentException if the field is not valid for
090: * this object's class.
091: */
092: Value getValue(Field sig);
093:
094: /**
095: * Gets the value of multiple instance and/or static fields in this object.
096: * The Fields must be valid for this ObjectReference;
097: * that is, they must be from
098: * the mirrored object's class or a superclass of that class.
099: *
100: * @param fields a list of {@link Field} objects containing the
101: * requested values.
102: * @return a Map of the requested {@link Field} objects with
103: * their {@link Value}.
104: * @throws java.lang.IllegalArgumentException if any field is not valid for
105: * this object's class.
106: */
107: Map<Field, Value> getValues(List<? extends Field> fields);
108:
109: /**
110: * Sets the value of a given instance or static field in this object.
111: * The {@link Field} must be valid for this ObjectReference; that is,
112: * it must be from the mirrored object's class or a superclass of that class.
113: * If static, the field must not be final.
114: * <p>
115: * Object values must be assignment compatible with the field type
116: * (This implies that the field type must be loaded through the
117: * enclosing class's class loader). Primitive values must be
118: * either assignment compatible with the field type or must be
119: * convertible to the field type without loss of information.
120: * See the <a href="http://java.sun.com/docs/books/jls/">
121: * Java<sup><font size=-2>TM</font></sup> Language Specification</a>.
122: * section
123: * <a href="http://java.sun.com/docs/books/jls/second_edition/html/conversions.doc.html#184206">5.2</a>
124: * for more information on assignment
125: * compatibility.
126: *
127: * @param field the field containing the requested value
128: * @param value the new value to assign
129: * @throws java.lang.IllegalArgumentException if the field is not valid for
130: * this object's class.
131: * @throws InvalidTypeException if the value's type does not match
132: * the field's type.
133: * @throws ClassNotLoadedException if 'value' is not null, and the field
134: * type has not yet been loaded through the appropriate class loader.
135: * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
136: */
137: void setValue(Field field, Value value)
138: throws InvalidTypeException, ClassNotLoadedException;
139:
140: /** Perform method invocation with only the invoking thread resumed */
141: static final int INVOKE_SINGLE_THREADED = 0x1;
142: /** Perform non-virtual method invocation */
143: static final int INVOKE_NONVIRTUAL = 0x2;
144:
145: /**
146: * Invokes the specified {@link Method} on this object in the
147: * target VM. The
148: * specified method can be defined in this object's class,
149: * in a superclass of this object's class, or in an interface
150: * implemented by this object. The method may be a static method
151: * or an instance method, but not a static initializer or constructor.
152: * Use {@link ClassType#newInstance} to create a new object and
153: * run its constructor.
154: * <p>
155: * The method invocation will occur in the specified thread.
156: * Method invocation can occur only if the specified thread
157: * has been suspended by an event which occurred in that thread.
158: * Method invocation is not supported
159: * when the target VM has been suspended through
160: * {@link VirtualMachine#suspend} or when the specified thread
161: * is suspended through {@link ThreadReference#suspend}.
162: * <p>
163: * The specified method is invoked with the arguments in the specified
164: * argument list. The method invocation is synchronous; this method
165: * does not return until the invoked method returns in the target VM.
166: * If the invoked method throws an exception, this method
167: * will throw an {@link InvocationException} which contains
168: * a mirror to the exception object thrown.
169: * <p>
170: * Object arguments must be assignment compatible with the argument type
171: * (This implies that the argument type must be loaded through the
172: * enclosing class's class loader). Primitive arguments must be
173: * either assignment compatible with the argument type or must be
174: * convertible to the argument type without loss of information.
175: * If the method being called accepts a variable number of arguments,
176: * then the last argument type is an array of some component type.
177: * The argument in the matching position can be omitted, or can be null,
178: * an array of the same component type, or an argument of the
179: * component type followed by any number of other arguments of the same
180: * type. If the argument is omitted, then a 0 length array of the
181: * component type is passed. The component type can be a primitive type.
182: * Autoboxing is not supported.
183: *
184: * See the <a href="http://java.sun.com/docs/books/jls/">
185: * Java Language Specification</a>.
186: * section
187: * <a href="http://java.sun.com/docs/books/jls/second_edition/html/conversions.doc.html#184206">5.2</a>
188: * for more information on assignment compatibility.
189: * <p>
190: * By default, the method is invoked using dynamic lookup as
191: * documented in the
192: * <a href="http://java.sun.com/docs/books/jls/">
193: * Java Language Specification</a>
194: * second edition, section
195: * <a href="http://java.sun.com/docs/books/jls/second_edition/html/expressions.doc.html#45606">15.12.4.4</a>;
196: * in particular, overriding based on the runtime type of the object
197: * mirrored by this {@link ObjectReference} will occur. This
198: * behavior can be changed by specifying the
199: * {@link #INVOKE_NONVIRTUAL} bit flag in the <code>options</code>
200: * argument. If this flag is set, the specified method is invoked
201: * whether or not it is overridden for this object's runtime type.
202: * The method, in this case, must not belong to an interface and
203: * must not be abstract. This option is useful for performing method
204: * invocations like those done with the <code>super</code> keyword in
205: * the Java programming language.
206: * <p>
207: * By default, all threads in the target VM are resumed while
208: * the method is being invoked if they were previously
209: * suspended by an event or by {@link VirtualMachine#suspend} or
210: * {@link ThreadReference#suspend}. This is done to prevent the deadlocks
211: * that will occur if any of the threads own monitors
212: * that will be needed by the invoked method.
213: * Note, however, that this implicit resume acts exactly like
214: * {@link ThreadReference#resume}, so if the thread's suspend
215: * count is greater than 1, it will remain in a suspended state
216: * during the invocation and thus a deadlock could still occur.
217: * By default, when the invocation completes,
218: * all threads in the target VM are suspended, regardless their state
219: * before the invocation.
220: * It is possible that
221: * breakpoints or other events might occur during the invocation.
222: * This can cause deadlocks as described above. It can also cause a deadlock
223: * if invokeMethod is called from the client's event handler thread. In this
224: * case, this thread will be waiting for the invokeMethod to complete and
225: * won't read the EventSet that comes in for the new event. If this
226: * new EventSet is SUSPEND_ALL, then a deadlock will occur because no
227: * one will resume the EventSet. To avoid this, all EventRequests should
228: * be disabled before doing the invokeMethod, or the invokeMethod should
229: * not be done from the client's event handler thread.
230: * <p>
231: * The resumption of other threads during the invocation can be prevented
232: * by specifying the {@link #INVOKE_SINGLE_THREADED}
233: * bit flag in the <code>options</code> argument; however,
234: * there is no protection against or recovery from the deadlocks
235: * described above, so this option should be used with great caution.
236: * Only the specified thread will be resumed (as described for all
237: * threads above). Upon completion of a single threaded invoke, the invoking thread
238: * will be suspended once again. Note that any threads started during
239: * the single threaded invocation will not be suspended when the
240: * invocation completes.
241: * <p>
242: * If the target VM is disconnected during the invoke (for example, through
243: * {@link VirtualMachine#dispose}) the method invocation continues.
244: *
245: * @param thread the thread in which to invoke.
246: * @param method the {@link Method} to invoke.
247: * @param arguments the list of {@link Value} arguments bound to the
248: * invoked method. Values from the list are assigned to arguments
249: * in the order they appear in the method signature.
250: * @param options the integer bit flag options.
251: * @return a {@link Value} mirror of the invoked method's return value.
252: * @throws java.lang.IllegalArgumentException if the method is not
253: * a member of this object's class, if the size of the argument list
254: * does not match the number of declared arguemnts for the method,
255: * if the method is a constructor or static intializer, or
256: * if {@link #INVOKE_NONVIRTUAL} is specified and the method is
257: * either abstract or an interface member.
258: * @throws {@link InvalidTypeException} if any argument in the
259: * argument list is not assignable to the corresponding method argument
260: * type.
261: * @throws ClassNotLoadedException if any argument type has not yet been loaded
262: * through the appropriate class loader.
263: * @throws IncompatibleThreadStateException if the specified thread has not
264: * been suspended by an event.
265: * @throws InvocationException if the method invocation resulted in
266: * an exception in the target VM.
267: * @throws InvalidTypeException If the arguments do not meet this requirement --
268: * Object arguments must be assignment compatible with the argument
269: * type. This implies that the argument type must be
270: * loaded through the enclosing class's class loader.
271: * Primitive arguments must be either assignment compatible with the
272: * argument type or must be convertible to the argument type without loss
273: * of information. See JLS section 5.2 for more information on assignment
274: * compatibility.
275: * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
276: */
277: Value invokeMethod(ThreadReference thread, Method method,
278: List<? extends Value> arguments, int options)
279: throws InvalidTypeException, ClassNotLoadedException,
280: IncompatibleThreadStateException, InvocationException;
281:
282: /**
283: * Prevents garbage collection for this object. By default all
284: * {@link ObjectReference} values returned by JDI may be collected
285: * at any time the target VM is running. A call to this method
286: * guarantees that the object will not be collected.
287: * {@link #enableCollection} can be used to allow collection once
288: * again.
289: * <p>
290: * Calls to this method are counted. Every call to this method
291: * requires a corresponding call to {@link #enableCollection} before
292: * garbage collection is re-enabled.
293: * <p>
294: * Note that while the target VM is suspended, no garbage collection
295: * will occur because all threads are suspended. The typical
296: * examination of variables, fields, and arrays during the suspension
297: * is safe without explicitly disabling garbage collection.
298: * <p>
299: * This method should be used sparingly, as it alters the
300: * pattern of garbage collection in the target VM and,
301: * consequently, may result in application behavior under the
302: * debugger that differs from its non-debugged behavior.
303: * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
304: * -see {@link VirtualMachine#canBeModified()}.
305: */
306: void disableCollection();
307:
308: /**
309: * Permits garbage collection for this object. By default all
310: * {@link ObjectReference} values returned by JDI may be collected
311: * at any time the target VM is running. A call to this method
312: * is necessary only if garbage collection was previously disabled
313: * with {@link #disableCollection}.
314: * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
315: * -see {@link VirtualMachine#canBeModified()}.
316: */
317: void enableCollection();
318:
319: /**
320: * Determines if this object has been garbage collected in the target
321: * VM.
322: *
323: * @return <code>true</code> if this {@link ObjectReference} has been collected;
324: * <code>false</code> otherwise.
325: * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
326: * -see {@link VirtualMachine#canBeModified()}.
327: */
328: boolean isCollected();
329:
330: /**
331: * Returns a unique identifier for this ObjectReference.
332: * It is guaranteed to be unique among all
333: * ObjectReferences from the same VM that have not yet been disposed.
334: * The guarantee applies as long
335: * as this ObjectReference has not yet been disposed.
336: *
337: * @return a long unique ID
338: */
339: long uniqueID();
340:
341: /**
342: * Returns a List containing a {@link ThreadReference} for
343: * each thread currently waiting for this object's monitor.
344: * See {@link ThreadReference#currentContendedMonitor} for
345: * information about when a thread is considered to be waiting
346: * for a monitor.
347: * <p>
348: * Not all target VMs support this operation. See
349: * VirtualMachine#canGetMonitorInfo to determine if the
350: * operation is supported.
351: *
352: * @return a List of {@link ThreadReference} objects. The list
353: * has zero length if no threads are waiting for the monitor.
354: * @throws java.lang.UnsupportedOperationException if the
355: * target VM does not support this operation.
356: * @throws IncompatibleThreadStateException if any
357: * waiting thread is not suspended
358: * in the target VM
359: */
360: List<ThreadReference> waitingThreads()
361: throws IncompatibleThreadStateException;
362:
363: /**
364: * Returns an {@link ThreadReference} for the thread, if any,
365: * which currently owns this object's monitor.
366: * See {@link ThreadReference#ownedMonitors} for a definition
367: * of ownership.
368: * <p>
369: * Not all target VMs support this operation. See
370: * VirtualMachine#canGetMonitorInfo to determine if the
371: * operation is supported.
372: *
373: * @return the {@link ThreadReference} which currently owns the
374: * monitor, or null if it is unowned.
375: *
376: * @throws java.lang.UnsupportedOperationException if the
377: * target VM does not support this operation.
378: * @throws IncompatibleThreadStateException if the owning thread is
379: * not suspended in the target VM
380: */
381: ThreadReference owningThread()
382: throws IncompatibleThreadStateException;
383:
384: /**
385: * Returns the number times this object's monitor has been
386: * entered by the current owning thread.
387: * See {@link ThreadReference#ownedMonitors} for a definition
388: * of ownership.
389: * <p>
390: * Not all target VMs support this operation. See
391: * VirtualMachine#canGetMonitorInfo to determine if the
392: * operation is supported.
393: *
394: * @see #owningThread
395: * @return the integer count of the number of entries.
396: *
397: * @throws java.lang.UnsupportedOperationException if the
398: * target VM does not support this operation.
399: * @throws IncompatibleThreadStateException if the owning thread is
400: * not suspended in the target VM
401: */
402: int entryCount() throws IncompatibleThreadStateException;
403:
404: /**
405: * Returns objects that directly reference this object.
406: * Only objects that are reachable for the purposes of garbage collection
407: * are returned. Note that an object can also be referenced in other ways,
408: * such as from a local variable in a stack frame, or from a JNI global
409: * reference. Such non-object referrers are not returned by this method.
410: * <p>
411: * Not all target virtual machines support this operation.
412: * Use {@link VirtualMachine#canGetInstanceInfo()}
413: * to determine if the operation is supported.
414: *
415: * @see VirtualMachine#instanceCounts(List)
416: * @see ReferenceType#instances(long)
417:
418: * @param maxReferrers The maximum number of referring objects to return.
419: * Must be non-negative. If zero, all referring
420: * objects are returned.
421: * @return a of List of {@link ObjectReference} objects. If there are
422: * no objects that reference this object, a zero-length list is returned..
423: * @throws java.lang.UnsupportedOperationException if
424: * the target virtual machine does not support this
425: * operation - see
426: * {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()}
427: * @throws java.lang.IllegalArgumentException if maxReferrers is less
428: * than zero.
429: * @since 1.6
430: */
431: List<ObjectReference> referringObjects(long maxReferrers);
432:
433: /**
434: * Compares the specified Object with this ObjectReference for equality.
435: *
436: * @return true if the Object is an ObjectReference, if the
437: * ObjectReferences belong to the same VM, and if applying the
438: * "==" operator on the mirrored objects in that VM evaluates to true.
439: */
440: boolean equals(Object obj);
441:
442: /**
443: * Returns the hash code value for this ObjectReference.
444: *
445: * @return the integer hash code
446: */
447: int hashCode();
448: }
|