IEvaluationEngine


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jdt.debug.eval;
12  
13   
14  import org.eclipse.debug.core.DebugException;
15  import org.eclipse.jdt.core.IJavaProject;
16  import org.eclipse.jdt.debug.core.IJavaDebugTarget;
17  import org.eclipse.jdt.debug.core.IJavaObject;
18  import org.eclipse.jdt.debug.core.IJavaStackFrame;
19  import org.eclipse.jdt.debug.core.IJavaThread;
20  
21  /**
22   * An evaluation engine performs an evaluation of a
23   * code snippet or expression in a specified thread of a debug target.
24   * An evaluation engine is associated with a specific
25   * debug target and Java project on creation.
26   * <p>
27   * Clients are not intended to implement this interface.
28   * </p>
29   * @see IEvaluationResult
30   * @see IEvaluationListener
31   * @since 2.0
32   */
33  
34  public interface IEvaluationEngine {
35      /**
36       * Asynchronously evaluates the given snippet in the context of
37       * the specified stack frame, reporting the result back to the given listener.
38       * The snippet is evaluated in the context of the Java
39       * project this evaluation engine was created on. If the
40       * snippet is determined to be a valid expression, the expression
41       * is evaluated in the thread associated with the given
42       * stack frame. The thread is resumed from the location at which it
43       * is currently suspended to perform the evaluation. When the evaluation
44       * completes, the thread will be suspended at this original location.
45       * The thread runs the evaluation with the given evaluation detail
46       * (@see IJavaThread#runEvaluation(IEvaluationRunnable, IProgressMonitor, int)).
47       * Compilation and runtime errors are reported in the evaluation result.
48       * 
49       * @param snippet code snippet to evaluate
50       * @param frame the stack frame context in which to run the
51       *   evaluation.
52       * @param listener the listener that will receive notification
53       *   when/if the evaluation completes
54       * @param evaluationDetail one of <code>DebugEvent.EVALUATION</code> or
55       *  <code>DebugEvent.EVALUATION_IMPLICIT</code>
56       * @param hitBreakpoints whether or not breakpoints should be honored
57       *  in the evaluation thread during the evaluation. If <code>false</code>,
58       *  breakpoints hit in the evaluation thread will be ignored.
59       * @exception DebugException if this method fails.  Reasons include:<ul>
60       * <li>Failure communicating with the VM.  The DebugException's
61       * status code contains the underlying exception responsible for
62       * the failure.</li>
63       * <li>The associated thread is not currently suspended</li>
64       * <li>The stack frame is not contained in the debug target
65       *   associated with this evaluation engine</li>
66       * <li>The associated thread is suspended in the middle of
67       *  an evaluation that has not completed. It is not possible
68       *  to perform nested evaluations</li>
69       * </ul>
70       */
71      public void evaluate(String   snippet, IJavaStackFrame frame, IEvaluationListener listener, int evaluationDetail, boolean hitBreakpoints) throws DebugException;
72      /**
73       * Asynchronously evaluates the given snippet in the context of
74       * the specified type, reporting the result back to the given listener.
75       * The snippet is evaluated in the context of the Java
76       * project this evaluation engine was created on. If the
77       * snippet is determined to be a valid expression, the expression
78       * is evaluated in the thread associated with the given
79       * stack frame. The thread is resumed from the location at which it
80       * is currently suspended to perform the evaluation. When the evaluation
81       * completes, the thread will be suspended at this original location.
82       * The thread runs the evaluation with the given evaluation detail
83       * (@see IJavaThread#runEvaluation(IEvaluationRunnable, IProgressMonitor, int)).
84       * Compilation and runtime errors are reported in the evaluation result.
85       * 
86       * @param snippet code snippet to evaluate
87       * @param thisContext the 'this' context for the evaluation
88       * @param thread the thread in which to run the evaluation,
89       *   which must be suspended
90       * @param listener the listener that will receive notification
91       *   when/if the evaluation completes
92       * @param evaluationDetail one of <code>DebugEvent.EVALUATION</code> or
93       *  <code>DebugEvent.EVALUATION_IMPLICIT</code>
94       * @param hitBreakpoints whether or not breakpoints should be honored
95       *  in the evaluation thread during the evaluation. If <code>false</code>,
96       *  breakpoints hit in the evaluation thread will be ignored.
97       * @exception DebugException if this method fails.  Reasons include:<ul>
98       * <li>Failure communicating with the VM.  The DebugException's
99       * status code contains the underlying exception responsible for
100      * the failure.</li>
101      * <li>The associated thread is not currently suspended</li>
102      * <li>The specified thread is not contained in the debug target
103      *   associated with this evaluation engine</li>
104      * <li>The associated thread is suspended in the middle of
105      *  an evaluation that has not completed. It is not possible
106      *  to perform nested evaluations</li>
107      * </ul>
108      */
109     public void evaluate(String   snippet, IJavaObject thisContext, IJavaThread thread, IEvaluationListener listener, int evaluationDetail, boolean hitBreakpoints) throws DebugException;
110 
111     /**
112      * Returns the Java project in which expressions are
113      * compiled.
114      * 
115      * @return Java project context
116      */
117     public IJavaProject getJavaProject();
118     
119     /**
120      * Returns the debug target for which evaluations
121      * are executed.
122      * 
123      * @return Java debug target
124      */
125     public IJavaDebugTarget getDebugTarget();
126     
127     /**
128      * Disposes this evaluation engine. This causes the evaluation engine
129      * to cleanup any resources (such as threads) that it maintains. Clients
130      * should call this method when they are finished performing evaluations
131      * with this engine.
132      * 
133      * This engine must not be used to perform evaluations after it has been disposed.
134      */
135     public void dispose();
136     
137 }
138 
139
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags