1 /*
   2  * Copyright (c) 1998, 2017, 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&trade; 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&trade; 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&trade; 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 have an implementation, either in a class
 197      * or an interface. This option is useful for performing method invocations
 198      * like those done with the <code>super</code> keyword in the Java programming
 199      * 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 arguments for the method,
 249      * if the method is a constructor or static initializer, or
 250      * if {@link #INVOKE_NONVIRTUAL} is specified and the method is
 251      * abstract.
 252      * @throws ClassNotLoadedException if any argument type has not yet been loaded
 253      * through the appropriate class loader.
 254      * @throws IncompatibleThreadStateException if the specified thread has not
 255      * been suspended by an event.
 256      * @throws InvocationException if the method invocation resulted in
 257      * an exception in the target VM.
 258      * @throws InvalidTypeException If the arguments do not meet this requirement --
 259      *         Object arguments must be assignment compatible with the argument
 260      *         type.  This implies that the argument type must be
 261      *         loaded through the enclosing class's class loader.
 262      *         Primitive arguments must be either assignment compatible with the
 263      *         argument type or must be convertible to the argument type without loss
 264      *         of information. See JLS section 5.2 for more information on assignment
 265      *         compatibility.
 266      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
 267      */
 268     Value invokeMethod(ThreadReference thread, Method method,
 269                        List<? extends Value> arguments, int options)
 270                                    throws InvalidTypeException,
 271                                           ClassNotLoadedException,
 272                                           IncompatibleThreadStateException,
 273                                           InvocationException;
 274 
 275     /**
 276      * Prevents garbage collection for this object. By default all
 277      * {@link ObjectReference} values returned by JDI may be collected
 278      * at any time the target VM is running. A call to this method
 279      * guarantees that the object will not be collected.
 280      * {@link #enableCollection} can be used to allow collection once
 281      * again.
 282      * <p>
 283      * Calls to this method are counted. Every call to this method
 284      * requires a corresponding call to {@link #enableCollection} before
 285      * garbage collection is re-enabled.
 286      * <p>
 287      * Note that while the target VM is suspended, no garbage collection
 288      * will occur because all threads are suspended. The typical
 289      * examination of variables, fields, and arrays during the suspension
 290      * is safe without explicitly disabling garbage collection.
 291      * <p>
 292      * This method should be used sparingly, as it alters the
 293      * pattern of garbage collection in the target VM and,
 294      * consequently, may result in application behavior under the
 295      * debugger that differs from its non-debugged behavior.
 296      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
 297      * -see {@link VirtualMachine#canBeModified()}.
 298      */
 299     void disableCollection();
 300 
 301     /**
 302      * Permits garbage collection for this object. By default all
 303      * {@link ObjectReference} values returned by JDI may be collected
 304      * at any time the target VM is running. A call to this method
 305      * is necessary only if garbage collection was previously disabled
 306      * with {@link #disableCollection}.
 307      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
 308      * -see {@link VirtualMachine#canBeModified()}.
 309      */
 310     void enableCollection();
 311 
 312     /**
 313      * Determines if this object has been garbage collected in the target
 314      * VM.
 315      *
 316      * @return <code>true</code> if this {@link ObjectReference} has been collected;
 317      * <code>false</code> otherwise.
 318      * @throws VMCannotBeModifiedException if the VirtualMachine is read-only
 319      * -see {@link VirtualMachine#canBeModified()}.
 320      */
 321     boolean isCollected();
 322 
 323     /**
 324      * Returns a unique identifier for this ObjectReference.
 325      * It is guaranteed to be unique among all
 326      * ObjectReferences from the same VM that have not yet been disposed.
 327      * The guarantee applies as long
 328      * as this ObjectReference has not yet been disposed.
 329      *
 330      * @return a long unique ID
 331      */
 332     long uniqueID();
 333 
 334     /**
 335      * Returns a List containing a {@link ThreadReference} for
 336      * each thread currently waiting for this object's monitor.
 337      * See {@link ThreadReference#currentContendedMonitor} for
 338      * information about when a thread is considered to be waiting
 339      * for a monitor.
 340      * <p>
 341      * Not all target VMs support this operation. See
 342      * VirtualMachine#canGetMonitorInfo to determine if the
 343      * operation is supported.
 344      *
 345      * @return a List of {@link ThreadReference} objects. The list
 346      * has zero length if no threads are waiting for the monitor.
 347      * @throws java.lang.UnsupportedOperationException if the
 348      * target VM does not support this operation.
 349      * @throws IncompatibleThreadStateException if any
 350      * waiting thread is not suspended
 351      * in the target VM
 352      */
 353     List<ThreadReference> waitingThreads()
 354         throws IncompatibleThreadStateException;
 355 
 356     /**
 357      * Returns an {@link ThreadReference} for the thread, if any,
 358      * which currently owns this object's monitor.
 359      * See {@link ThreadReference#ownedMonitors} for a definition
 360      * of ownership.
 361      * <p>
 362      * Not all target VMs support this operation. See
 363      * VirtualMachine#canGetMonitorInfo to determine if the
 364      * operation is supported.
 365      *
 366      * @return the {@link ThreadReference} which currently owns the
 367      * monitor, or null if it is unowned.
 368      *
 369      * @throws java.lang.UnsupportedOperationException if the
 370      * target VM does not support this operation.
 371      * @throws IncompatibleThreadStateException if the owning thread is
 372      * not suspended in the target VM
 373      */
 374     ThreadReference owningThread() throws IncompatibleThreadStateException;
 375 
 376     /**
 377      * Returns the number times this object's monitor has been
 378      * entered by the current owning thread.
 379      * See {@link ThreadReference#ownedMonitors} for a definition
 380      * of ownership.
 381      * <p>
 382      * Not all target VMs support this operation. See
 383      * VirtualMachine#canGetMonitorInfo to determine if the
 384      * operation is supported.
 385      *
 386      * @see #owningThread
 387      * @return the integer count of the number of entries.
 388      *
 389      * @throws java.lang.UnsupportedOperationException if the
 390      * target VM does not support this operation.
 391      * @throws IncompatibleThreadStateException if the owning thread is
 392      * not suspended in the target VM
 393      */
 394     int entryCount() throws IncompatibleThreadStateException;
 395 
 396     /**
 397      * Returns objects that directly reference this object.
 398      * Only objects that are reachable for the purposes of garbage collection
 399      * are returned.  Note that an object can also be referenced in other ways,
 400      * such as from a local variable in a stack frame, or from a JNI global
 401      * reference.  Such non-object referrers are not returned by this method.
 402      * <p>
 403      * Not all target virtual machines support this operation.
 404      * Use {@link VirtualMachine#canGetInstanceInfo()}
 405      * to determine if the operation is supported.
 406      *
 407      * @see VirtualMachine#instanceCounts(List)
 408      * @see ReferenceType#instances(long)
 409 
 410      * @param maxReferrers  The maximum number of referring objects to return.
 411      *                      Must be non-negative.  If zero, all referring
 412      *                      objects are returned.
 413      * @return a of List of {@link ObjectReference} objects. If there are
 414      *  no objects that reference this object, a zero-length list is returned..
 415      * @throws java.lang.UnsupportedOperationException if
 416      * the target virtual machine does not support this
 417      * operation - see
 418      * {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()}
 419      * @throws java.lang.IllegalArgumentException if maxReferrers is less
 420      *         than zero.
 421      * @since 1.6
 422      */
 423     List<ObjectReference> referringObjects(long maxReferrers);
 424 
 425 
 426     /**
 427      * Compares the specified Object with this ObjectReference for equality.
 428      *
 429      * @return  true if the Object is an ObjectReference, if the
 430      * ObjectReferences belong to the same VM, and if applying the
 431      * "==" operator on the mirrored objects in that VM evaluates to true.
 432      */
 433     boolean equals(Object obj);
 434 
 435     /**
 436      * Returns the hash code value for this ObjectReference.
 437      *
 438      * @return the integer hash code
 439      */
 440     int hashCode();
 441 }