replaced <code></code> with more concise {@code}
[idea/community.git] / platform / xdebugger-api / src / com / intellij / xdebugger / XDebugSession.java
1 /*
2  * Copyright 2000-2016 JetBrains s.r.o.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package com.intellij.xdebugger;
18
19 import com.intellij.execution.configurations.RunProfile;
20 import com.intellij.execution.ui.ConsoleView;
21 import com.intellij.execution.ui.RunContentDescriptor;
22 import com.intellij.execution.ui.RunnerLayoutUi;
23 import com.intellij.openapi.Disposable;
24 import com.intellij.openapi.actionSystem.DataKey;
25 import com.intellij.openapi.project.Project;
26 import com.intellij.openapi.ui.MessageType;
27 import com.intellij.xdebugger.breakpoints.XBreakpoint;
28 import com.intellij.xdebugger.breakpoints.XLineBreakpoint;
29 import com.intellij.xdebugger.frame.XExecutionStack;
30 import com.intellij.xdebugger.frame.XStackFrame;
31 import com.intellij.xdebugger.frame.XSuspendContext;
32 import com.intellij.xdebugger.stepping.XSmartStepIntoHandler;
33 import com.intellij.xdebugger.stepping.XSmartStepIntoVariant;
34 import org.jetbrains.annotations.NotNull;
35 import org.jetbrains.annotations.Nullable;
36
37 import javax.swing.*;
38 import javax.swing.event.HyperlinkListener;
39
40 /**
41  * Instances of this class are created by the debugging subsystem when {@link XDebuggerManager#startSession} or
42  * {@link XDebuggerManager#startSessionAndShowTab} method is called. It isn't supposed to be implemented by a plugin.
43  * <p/>
44  * Instance of this class can be obtained from {@link XDebugProcess#getSession()} method and used to control debugging process
45  *
46  * @author nik
47  */
48 public interface XDebugSession extends AbstractDebuggerSession {
49   DataKey<XDebugSession> DATA_KEY = DataKey.create("XDebugSessionTab.XDebugSession");
50
51   @NotNull
52   Project getProject();
53
54   @NotNull
55   XDebugProcess getDebugProcess();
56
57   boolean isSuspended();
58
59   @Nullable
60   XStackFrame getCurrentStackFrame();
61
62   XSuspendContext getSuspendContext();
63
64   /**
65    * Position from the current frame
66    * @return
67    */
68   @Nullable
69   XSourcePosition getCurrentPosition();
70
71   /**
72    * Position from the top frame
73    * @return
74    */
75   @Nullable
76   XSourcePosition getTopFramePosition();
77
78   void stepOver(boolean ignoreBreakpoints);
79
80   void stepInto();
81
82   void stepOut();
83
84   void forceStepInto();
85
86   void runToPosition(@NotNull XSourcePosition position, final boolean ignoreBreakpoints);
87
88   void pause();
89
90   void resume();
91
92   void showExecutionPoint();
93
94   void setCurrentStackFrame(@NotNull XExecutionStack executionStack, @NotNull XStackFrame frame, boolean isTopFrame);
95
96   /**
97    * Call this method to setup custom icon and/or error message (it will be shown in tooltip) for breakpoint
98    *
99    * @param breakpoint   breakpoint
100    * @param icon         icon ({@code null} if default icon should be used). You can use icons from {@link com.intellij.icons.AllIcons.Debugger}
101    * @param errorMessage an error message if breakpoint isn't successfully registered
102    */
103   void updateBreakpointPresentation(@NotNull XLineBreakpoint<?> breakpoint, @Nullable Icon icon, @Nullable String errorMessage);
104
105   /**
106    * Call this method when a breakpoint is reached if its condition ({@link XBreakpoint#getCondition()}) evaluates to {@code true}.
107    * <p/>
108    * <strong>The underlying debugging process should be suspended only if the method returns {@code true}. </strong>
109    *
110    * @param breakpoint             reached breakpoint
111    * @param evaluatedLogExpression value of {@link XBreakpoint#getLogExpression()} evaluated in the current context
112    * @param suspendContext         context
113    * @return {@code true} if the debug process should be suspended
114    */
115   boolean breakpointReached(@NotNull XBreakpoint<?> breakpoint,
116                             @Nullable String evaluatedLogExpression,
117                             @NotNull XSuspendContext suspendContext);
118
119   /**
120    * @deprecated use {@link #breakpointReached(XBreakpoint, String, XSuspendContext)} instead
121    */
122   boolean breakpointReached(@NotNull XBreakpoint<?> breakpoint, @NotNull XSuspendContext suspendContext);
123
124   /**
125    * Call this method when position is reached (e.g. after "Run to cursor" or "Step over" command)
126    *
127    * @param suspendContext context
128    */
129   void positionReached(@NotNull XSuspendContext suspendContext);
130
131   /**
132    * Call this method when session resumed because of some external event, e.g. from the debugger console
133    */
134   void sessionResumed();
135
136   void stop();
137
138   void setBreakpointMuted(boolean muted);
139
140   boolean areBreakpointsMuted();
141
142
143   void addSessionListener(@NotNull XDebugSessionListener listener, @NotNull Disposable parentDisposable);
144
145   void addSessionListener(@NotNull XDebugSessionListener listener);
146
147   void removeSessionListener(@NotNull XDebugSessionListener listener);
148
149   void reportError(@NotNull String message);
150
151   void reportMessage(@NotNull String message, @NotNull MessageType type);
152
153   void reportMessage(@NotNull String message, @NotNull MessageType type, @Nullable HyperlinkListener listener);
154
155   @NotNull
156   String getSessionName();
157
158   @NotNull
159   RunContentDescriptor getRunContentDescriptor();
160
161   @Nullable
162   RunProfile getRunProfile();
163
164   void setPauseActionSupported(boolean isSupported);
165
166   void rebuildViews();
167
168   <V extends XSmartStepIntoVariant> void smartStepInto(XSmartStepIntoHandler<V> handler, V variant);
169
170   void updateExecutionPosition();
171
172   void initBreakpoints();
173
174   ConsoleView getConsoleView();
175
176   RunnerLayoutUi getUI();
177 }