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