ObjectReferenceImpl

Prevents garbage collection for this object. By default all ObjectReference values returned by JDI may be collected at any time the target VM is running. A call to this method guarantees that the object will not be collected. enableCollection() can be used to allow collection once again.

Calls to this method are counted. Every call to this method requires a corresponding call to enableCollection() before garbage collection is re-enabled.

Note that while the target VM is suspended, no garbage collection will occur because all threads are suspended. The typical examination of variables, fields, and arrays during the suspension is safe without explicitly disabling garbage collection.

This method should be used sparingly, as it alters the pattern of garbage collection in the target VM and, consequently, may result in application behavior under the debugger that differs from its non-debugged behavior.

Permits garbage collection for this object. By default all ObjectReference values returned by JDI may be collected at any time the target VM is running. A call to this method is necessary only if garbage collection was previously disabled with disableCollection().

Returns the number times this object's monitor has been entered by the current owning thread. See ownedMonitors() for a definition of ownership.

Not all target VMs support this operation. See VirtualMachine#canGetMonitorInfo to determine if the operation is supported.

Indicates whether some other object is "equal to" this one.

The equals method implements an equivalence relation on non-null object references:

• It is reflexive: for any non-null reference value x, x.equals(x) should return true.
• It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
• It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
• It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
• For any non-null reference value x, x.equals(null) should return false.

The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference values x and y, this method returns true if and only if x and y refer to the same object (x == y has the value true).

Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.

Gets the value of a given instance or static field in this object. The Field must be valid for this ObjectReference; that is, it must be from the mirrored object's class or a superclass of that class.

Gets the value of multiple instance and/or static fields in this object. The Fields must be valid for this ObjectReference; that is, they must be from the mirrored object's class or a superclass of that class.

Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable.

The general contract of hashCode is:

• Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
• If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
• It is not required that if two objects are unequal according to the equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the Java^TM programming language.)

Invokes the specified Method on this object in the target VM. The specified method can be defined in this object's class, in a superclass of this object's class, or in an interface implemented by this object. The method may be a static method or an instance method, but not a static initializer or constructor. Use newInstance(ThreadReference, Method, List, int) to create a new object and run its constructor.

The method invocation will occur in the specified thread. Method invocation can occur only if the specified thread has been suspended by an event which occurred in that thread. Method invocation is not supported when the target VM has been suspended through suspend() or when the specified thread is suspended through suspend().

The specified method is invoked with the arguments in the specified argument list. The method invocation is synchronous; this method does not return until the invoked method returns in the target VM. If the invoked method throws an exception, this method will throw an InvocationException which contains a mirror to the exception object thrown.

Object arguments must be assignment compatible with the argument type (This implies that the argument type must be loaded through the enclosing class's class loader). Primitive arguments must be either assignment compatible with the argument type or must be convertible to the argument type without loss of information. If the method being called accepts a variable number of arguments, then the last argument type is an array of some component type. The argument in the matching position can be omitted, or can be null, an array of the same component type, or an argument of the component type followed by any number of other arguments of the same type. If the argument is omitted, then a 0 length array of the component type is passed. The component type can be a primitive type. Autoboxing is not supported. See the Java Language Specification. section 5.2 for more information on assignment compatibility.

By default, the method is invoked using dynamic lookup as documented in the Java Language Specification second edition, section 15.12.4.4; in particular, overriding based on the runtime type of the object mirrored by this ObjectReference will occur. This behavior can be changed by specifying the INVOKE_NONVIRTUAL bit flag in the options argument. If this flag is set, the specified method is invoked whether or not it is overridden for this object's runtime type. The method, in this case, must not belong to an interface and must not be abstract. This option is useful for performing method invocations like those done with the super keyword in the Java programming language.

By default, all threads in the target VM are resumed while the method is being invoked if they were previously suspended by an event or by suspend() or suspend(). This is done to prevent the deadlocks that will occur if any of the threads own monitors that will be needed by the invoked method. Note, however, that this implicit resume acts exactly like resume(), so if the thread's suspend count is greater than 1, it will remain in a suspended state during the invocation and thus a deadlock could still occur. By default, when the invocation completes, all threads in the target VM are suspended, regardless their state before the invocation. It is possible that breakpoints or other events might occur during the invocation. This can cause deadlocks as described above. It can also cause a deadlock if invokeMethod is called from the client's event handler thread. In this case, this thread will be waiting for the invokeMethod to complete and won't read the EventSet that comes in for the new event. If this new EventSet is SUSPEND_ALL, then a deadlock will occur because no one will resume the EventSet. To avoid this, all EventRequests should be disabled before doing the invokeMethod, or the invokeMethod should not be done from the client's event handler thread.

The resumption of other threads during the invocation can be prevented by specifying the INVOKE_SINGLE_THREADED bit flag in the options argument; however, there is no protection against or recovery from the deadlocks described above, so this option should be used with great caution. Only the specified thread will be resumed (as described for all threads above). Upon completion of a single threaded invoke, the invoking thread will be suspended once again. Note that any threads started during the single threaded invocation will not be suspended when the invocation completes.

If the target VM is disconnected during the invoke (for example, through dispose()) the method invocation continues.

Determines if this object has been garbage collected in the target VM.

Returns an ThreadReference for the thread, if any, which currently owns this object's monitor. See ownedMonitors() for a definition of ownership.

Not all target VMs support this operation. See VirtualMachine#canGetMonitorInfo to determine if the operation is supported.

Gets the ReferenceType that mirrors the type of this object. The type may be a subclass or implementor of the declared type of any field or variable which currently holds it. For example, right after the following statement.

Object obj = new String("Hello, world!");

The ReferenceType of obj will mirror java.lang.String and not java.lang.Object.

The type of an object never changes, so this method will always return the same ReferenceType over the lifetime of the mirrored object.

The returned ReferenceType will be a ClassType or ArrayType and never an InterfaceType.

Returns objects that directly reference this object. Only objects that are reachable for the purposes of garbage collection are returned. Note that an object can also be referenced in other ways, such as from a local variable in a stack frame, or from a JNI global reference. Such non-object referrers are not returned by this method.

Not all target virtual machines support this operation. Use canGetInstanceInfo() to determine if the operation is supported.

Sets the value of a given instance or static field in this object. The Field must be valid for this ObjectReference; that is, it must be from the mirrored object's class or a superclass of that class. If static, the field must not be final.

Object values must be assignment compatible with the field type (This implies that the field type must be loaded through the enclosing class's class loader). Primitive values must be either assignment compatible with the field type or must be convertible to the field type without loss of information. See the Java^TM Language Specification. section 5.2 for more information on assignment compatibility.

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Returns the run-time type of this value.

Returns a unique identifier for this ObjectReference. It is guaranteed to be unique among all ObjectReferences from the same VM that have not yet been disposed. The guarantee applies as long as this ObjectReference has not yet been disposed.

Gets the VirtualMachine to which this Mirror belongs. A Mirror must be associated with a VirtualMachine to have any meaning.

Returns a List containing a ThreadReference for each thread currently waiting for this object's monitor. See currentContendedMonitor() for information about when a thread is considered to be waiting for a monitor.

Not all target VMs support this operation. See VirtualMachine#canGetMonitorInfo to determine if the operation is supported.