IBreakpointManager


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 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.debug.core;
12  
13  
14  import org.eclipse.core.resources.IMarker;
15  import org.eclipse.core.runtime.CoreException;
16  import org.eclipse.debug.core.model.IBreakpoint;
17  
18  /**
19   * The breakpoint manager manages the collection of breakpoints
20   * in the workspace. A breakpoint suspends the execution of a
21   * program being debugged. The kinds of breakpoints supported by each
22   * debug architecture and the information required to create those
23   * breakpoints is defined by each debug architecture.
24   * Breakpoint creation is a client responsibility.
25   * <p>
26   * Clients interested in breakpoint change notification may
27   * register with the breakpoint manager - see
28   * <code>IBreakpointListener</code> and <code>IBreakpointsListener</code>
29   * </p>
30   * <p>
31   * This interface is not intended to be implemented by clients.
32   * </p>
33   * @see org.eclipse.debug.core.IBreakpointListener
34   * @see org.eclipse.debug.core.IBreakpointsListener
35   */
36  public interface IBreakpointManager {
37      /**
38       * Adds the given breakpoint to the collection of registered breakpoints
39       * in the workspace and notifies all registered listeners. This has no effect
40       * if the given breakpoint is already registered.
41       *
42       * @param breakpoint the breakpoint to add
43       *
44       * @exception CoreException if adding fails. Reasons include:<ul>
45       * <li>CONFIGURATION_INVALID - the required <code>MODEL_IDENTIFIER</code> attribute
46       *  is not set on the breakpoint marker.</li>
47       * <li>A <code>CoreException</code> occurred while verifying the <code>MODEL_IDENTIFIER</code>
48       *  attribute.</li>
49       * </ul>
50       * @since 2.0
51       */
52      public void addBreakpoint(IBreakpoint breakpoint) throws CoreException;
53      
54      /**
55       * Adds the given breakpoints to the collection of registered breakpoints
56       * in the workspace and notifies all registered listeners. Has no effect
57       * on breakpoints that are already registered.
58       *
59       * @param breakpoints the breakpoints to add
60       *
61       * @exception CoreException if adding fails. Reasons include:<ul>
62       * <li>CONFIGURATION_INVALID - the required <code>MODEL_IDENTIFIER</code> attribute
63       *  is not set on a breakpoint marker.</li>
64       * <li>A <code>CoreException</code> occurred while verifying a <code>MODEL_IDENTIFIER</code>
65       *  attribute.</li>
66       * </ul>
67       * @since 2.1
68       */
69      public void addBreakpoints(IBreakpoint[] breakpoints) throws CoreException; 
70      
71      /**
72       * Returns the breakpoint associated with the given marker or
73       * <code>null</code> if no such breakpoint exists
74       * 
75       * @param marker the marker
76       * @return the breakpoint associated with the marker
77       *  or <code>null</code> if none exists
78       * @since 2.0
79       */
80      public IBreakpoint getBreakpoint(IMarker marker);   
81      
82      /**
83       * Returns a collection of all registered breakpoints.
84       * Returns an empty array if no breakpoints are registered.
85       *
86       * @return an array of breakpoints
87       * @since 2.0
88       */
89      public IBreakpoint[] getBreakpoints();
90      
91      /**
92       * Returns whether there are any registered breakpoints.
93       * 
94       * @return whether there are any registered breakpoints
95       * @since 2.0
96       */
97      public boolean hasBreakpoints();
98      
99      /**
100      * Returns a collection of all breakpoints registered for the
101      * given debug model. Answers an empty array if no breakpoints are registered
102      * for the given debug model.
103      *
104      * @param modelIdentifier identifier of a debug model plug-in
105      * @return an array of breakpoints
106      * @since 2.0
107      */
108     public IBreakpoint[] getBreakpoints(String   modelIdentifier);
109         
110     /**
111      * Returns whether the given breakpoint is currently
112      * registered with this breakpoint manager.
113      *
114      * @param breakpoint a breakpoint
115      * @return whether the breakpoint is registered
116      * @since 2.0
117      */
118     public boolean isRegistered(IBreakpoint breakpoint);
119     
120     /**
121      * Notifies all registered listeners that the given
122      * breakpoint has changed. Has no effect if the given
123      * breakpoint is not currently registered.
124      * 
125      * This method is intended to be used when a breakpoint
126      * attribute is changed that does not alter the breakpoint's
127      * underlying marker, that is, when notification will not occur
128      * via the marker delta mechanism.
129      * 
130      * @param breakpoint the breakpoint that has changed.
131      * @since 2.0
132      */
133     public void fireBreakpointChanged(IBreakpoint breakpoint);
134     
135     /**
136      * Removes the given breakpoint from the breakpoint manager, deletes
137      * the marker associated with the breakpoint if the <code>delete</code> flag
138      * is <code>true</code>, and notifies all registered
139      * listeners. Has no effect if the given breakpoint is not currently
140      * registered.
141      *
142      * @param breakpoint the breakpoint to remove
143      * @param delete whether to delete the marker associated with the
144      *  breakpoint
145      * @exception CoreException if an exception occurs while deleting the
146      *  underlying marker.
147      * @since 2.0
148      */
149     public void removeBreakpoint(IBreakpoint breakpoint, boolean delete) throws CoreException;
150     
151     /**
152      * Removes the given breakpoints from the breakpoint manager, deletes
153      * the markers associated with the breakpoints if the <code>delete</code> flag
154      * is <code>true</code>, and notifies all registered
155      * listeners. Has no effect on breakpoints not currently
156      * registered.
157      *
158      * @param breakpoints the breakpoints to remove
159      * @param delete whether to delete the markers associated with the
160      *  breakpoints
161      * @exception CoreException if an exception occurs while deleting an
162      *  underlying marker.
163      * @since 2.1
164      */
165     public void removeBreakpoints(IBreakpoint[] breakpoints, boolean delete) throws CoreException;  
166 
167     /**
168      * Adds the given listener to the collection of registered breakpoint listeners.
169      * Has no effect if an identical listener is already registered.
170      *
171      * @param listener the listener to add
172      */
173     public void addBreakpointListener(IBreakpointListener listener);
174 
175     /**
176      * Removes the given listener from the collection of registered breakpoint listeners.
177      * Has no effect if an identical listener is not already registered.
178      *
179      * @param listener the listener to remove   
180      */
181     public void removeBreakpointListener(IBreakpointListener listener);
182     
183     /**
184      * Adds the given listener to the collection of registered breakpoint listeners.
185      * Has no effect if an identical listener is already registered.
186      *
187      * @param listener the listener to add
188      * @since 2.1
189      */
190     public void addBreakpointListener(IBreakpointsListener listener);
191 
192     /**
193      * Removes the given listener from the collection of registered breakpoint listeners.
194      * Has no effect if an identical listener is not already registered.
195      *
196      * @param listener the listener to remove   
197      * @since 2.1
198      */
199     public void removeBreakpointListener(IBreakpointsListener listener);
200     
201     /**
202      * Adds the given listener to the collection of registered breakpoint manager
203      * listeners. Has no effect if an identical listener is already registered.
204      * 
205      * @param listener the listener to add
206      * @since 3.0
207      */
208     public void addBreakpointManagerListener(IBreakpointManagerListener listener);
209     
210     /**
211      * Removes the given listener from the collection of registered breakpoint manager
212      * listeners. Has no effect if an identical listener is not already registered.
213      * 
214      * @param listener the listener to remove
215      * @since 3.0
216      */
217     public void removeBreakpointManagerListener(IBreakpointManagerListener listener);
218     
219     /**
220      * Returns whether or not this breakpoint manager is enabled.
221      * When a breakpoint manager is enabled, all breakpoints
222      * should be honored. When it is disabled, breakpoints should
223      * not be honored, regardless of each breakpoint's enabled state.
224      * 
225      * @return whether or not this breakpoint manager is enabled
226      * @since 3.0
227      */
228     public boolean isEnabled();
229     
230     /**
231      * Sets the enabled state of this breakpoint manager. When
232      * enabled, breakpoints should be honored. When disabled, all
233      * breakpoints should be ignored.
234      * 
235      * @param enabled whether this breakpoint manager should be
236      *  enabled
237      * @since 3.0
238      */
239     public void setEnabled(boolean enabled);
240 
241     /**
242      * Returns the name (user readable String) of the given
243      * breakpoint's type or <code>null</code> if none has been
244      * specified.
245      * 
246      * @param breakpoint the breakpoint
247      * @return the name of the given breakpoint's type or <code>null</code>
248      * @since 3.1
249      */
250     public String   getTypeName(IBreakpoint breakpoint);
251     
252 }
253 
254 
255
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags