001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.debug.core;
011:
012: import org.eclipse.debug.core.DebugException;
013:
014: /**
015: * A value referencing an object on a target VM.
016: * <p>
017: * Clients are not intended to implement this interface.
018: * </p>
019: * @see IJavaValue
020: * @since 2.0
021: */
022: public interface IJavaObject extends IJavaValue {
023:
024: /**
025: * Returns the result of sending the specified message to this object
026: * with the given arguments in the specified thread. The given
027: * thread is resumed to perform the method invocation. The thread will suspend
028: * in its original location when the method invocation is complete. This
029: * method does not return until the method invocation is complete.
030: * Invoking a method in the target VM can result in breakpoints being
031: * hit, infinite loops, and deadlock.
032: *
033: * @param selector the selector of the method to be invoked
034: * @param signature the JNI style signature of the method to be invoked
035: * @param args the arguments of the method, which can be
036: * <code>null</code> or empty if there are none
037: * @param thread the thread in which to invoke the method
038: * @param superSend <code>true</code> if the method lookup should
039: * begin in this object's superclass
040: * @return the result of invoking the method
041: * @exception DebugException if this method fails. Reasons include:<ul>
042: * <li>Failure communicating with the VM. The DebugException's
043: * status code contains the underlying exception responsible for
044: * the failure.</li>
045: * <li>This object does not implement the specified method</li>
046: * <li>An exception occurs while invoking the specified method</li>
047: * <li>The given thread is already performing a message send,
048: * (status code <code>IJavaThread.ERR_NESTED_METHOD_INVOCATION</code>)</li>
049: * <li>The given thread is not currently suspended
050: * (status code <code>IJavaThread.ERR_THREAD_NOT_SUSPENDED</code>)</li>
051: * <li>The given thread was explicitly suspended
052: * (status code <code>IJavaThread.ERR_INCOMPATIBLE_THREAD_STATE</code>)</li>
053: * </ul>
054: */
055: public IJavaValue sendMessage(String selector, String signature,
056: IJavaValue[] args, IJavaThread thread, boolean super Send)
057: throws DebugException;
058:
059: /**
060: * Returns the result of sending the specified message on the specified declaring type
061: * to this object with the given arguments in the specified thread. The given
062: * thread is resumed to perform the method invocation. The thread will suspend
063: * in its original location when the method invocation is complete. This
064: * method does not return until the method invocation is complete.
065: * Invoking a method in the target VM can result in breakpoints being
066: * hit, infinite loops, and deadlock.
067: *
068: * @param selector the selector of the method to be invoked
069: * @param signature the JNI style signature of the method to be invoked
070: * @param args the arguments of the method, which can be
071: * <code>null</code> or empty if there are none
072: * @param thread the thread in which to invoke the method
073: * @param typeSignature the signature of the type in which the method
074: * is defined or <code>null</code> if the method should be invoked normally using
075: * polymorphism
076: * @return the result of invoking the method
077: * @exception DebugException if this method fails. Reasons include:<ul>
078: * <li>Failure communicating with the VM. The DebugException's
079: * status code contains the underlying exception responsible for
080: * the failure.</li>
081: * <li>This object does not implement the specified method</li>
082: * <li>An exception occurs while invoking the specified method</li>
083: * <li>The given thread is already performing a message send,
084: * (status code <code>IJavaThread.ERR_NESTED_METHOD_INVOCATION</code>)</li>
085: * <li>The given thread is not currently suspended
086: * (status code <code>IJavaThread.ERR_THREAD_NOT_SUSPENDED</code>)</li>
087: * <li>The given thread was explicitly suspended
088: * (status code <code>IJavaThread.ERR_INCOMPATIBLE_THREAD_STATE</code>)</li>
089: * </ul>
090: * @since 2.0.1
091: */
092: public IJavaValue sendMessage(String selector, String signature,
093: IJavaValue[] args, IJavaThread thread, String typeSignature)
094: throws DebugException;
095:
096: /**
097: * Returns a variable representing the field in this object
098: * with the given name, or <code>null</code> if there is no
099: * field with the given name, or the name is ambiguous.
100: *
101: * @param name field name
102: * @param superField whether or not to get the field in the superclass
103: * of this objects.
104: * @return the variable representing the field, or <code>null</code>
105: * @exception DebugException if this method fails. Reasons include:
106: * <ul><li>Failure communicating with the VM. The DebugException's
107: * status code contains the underlying exception responsible for
108: * the failure.</li>
109: */
110: public IJavaFieldVariable getField(String name, boolean super Field)
111: throws DebugException;
112:
113: /**
114: * Returns a variable representing the field in this object
115: * with the given name declared in the type with the given
116: * signature, or <code>null</code> if there is no
117: * field with the given name, or the name is ambiguous.
118: *
119: * @param name field name
120: * @param typeSignature the signature of the type in which the field
121: * is defined
122: * @return the variable representing the field, or <code>null</code>
123: * @exception DebugException if this method fails. Reasons include:
124: * <ul><li>Failure communicating with the VM. The DebugException's
125: * status code contains the underlying exception responsible for
126: * the failure.</li>
127: */
128: public IJavaFieldVariable getField(String name, String typeSignature)
129: throws DebugException;
130:
131: /**
132: * Returns the threads waiting for the monitor associated to this object, or
133: * <code>null</code> if no thread is waiting for the monitor.
134: *
135: * @return the thread waiting for the monitor, or <code>null</code>.
136: * @exception DebugException if this method fails. Reasons include:
137: * <ul><li>The VM is not able to retrieve the monitor information</li>
138: * <li>Failure communicating with the VM. The DebugException's
139: * status code contains the underlying exception responsible for
140: * the failure.</li></ul>
141: * @since 3.1
142: */
143: public IJavaThread[] getWaitingThreads() throws DebugException;
144:
145: /**
146: * Returns the threads which owns for the monitor associated to this object, or
147: * <code>null</code> if no thread owns the monitor.
148: *
149: * @return the thread which owns the monitor, or <code>null</code>.
150: * @exception DebugException if this method fails. Reasons include:
151: * <ul><li>The VM is not able to retrieve the monitor information</li>
152: * <li>Failure communicating with the VM. The DebugException's
153: * status code contains the underlying exception responsible for
154: * the failure.</li></ul>
155: * @since 3.1
156: */
157: public IJavaThread getOwningThread() throws DebugException;
158:
159: /**
160: * Returns objects that directly reference this object.
161: *
162: * @param max the maximum number of references to retrieve or 0 for all references
163: * @return objects that directly reference this object
164: * @throws DebugException
165: * @since 3.3
166: */
167: public IJavaObject[] getReferringObjects(long max)
168: throws DebugException;
169:
170: /**
171: * Permits this object to be garbage collected. Has no effect if this
172: * VM does not support enabling/disabling of garbage collection of
173: * specific objects.
174: *
175: * @throws CoreException if request fails
176: * @see IJavaDebugTarget
177: * @since 3.4
178: */
179: public void enableCollection() throws DebugException;
180:
181: /**
182: * Prevents this object from being garbage collected. Has no effect if this
183: * VM does not support enabling/disabling of garbage collection of specific
184: * objects.
185: *
186: * @throws CoreException if request fails
187: * @see IJavaDebugTarget
188: * @since 3.4
189: */
190: public void disableCollection() throws DebugException;
191:
192: /**
193: * Returns the unique id for this object.
194: *
195: * @return unique id or -1 if this value is <code>null</code>
196: * @throws DebugException
197: * @since 3.4
198: */
199: public long getUniqueId() throws DebugException;
200:
201: }
|