IBreakpoint


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.debug.core.model;
12  
13  
14  import org.eclipse.core.resources.IMarker;
15  import org.eclipse.core.runtime.CoreException;
16  import org.eclipse.core.runtime.IAdaptable;
17  import org.eclipse.debug.core.DebugPlugin;
18  
19  /**
20   * A breakpoint is capable of suspending the execution of a
21   * program at a specific location when a program is running
22   * in debug mode. Each breakpoint has an associated marker which
23   * stores and persists all attributes associated with a breakpoint.
24   * <p>
25   * A breakpoint is defined in two parts:
26   * <ol>
27   * <li>By an extension of kind <code>"org.eclipse.debug.core.breakpoints"</code></li>
28   * <li>By a marker definition that corresponds to the above breakpoint extension</li>
29   * </ol>
30   * <p>
31   * For example, following is a definition of corresponding breakpoint
32   * and breakpoint marker definitions. Note that the <code>markerType</code>
33   * attribute defined by the breakpoint extension corresponds to the 
34   * type of the marker definition.
35   * <pre>
36   * &lt;extension point="org.eclipse.debug.core.breakpoints"&gt;
37   *   &lt;breakpoint 
38   *      id="com.example.Breakpoint"
39   *      class="com.example.Breakpoint"
40   *      markerType="com.example.BreakpointMarker"&gt;
41   *   &lt;/breakpoint&gt;
42   * &lt;/extension&gt;
43   * &lt;extension point="org.eclipse.core.resources.markers"&gt;
44   *   &lt;marker 
45   *      id="com.example.BreakpointMarker"
46   *      super type="org.eclipse.debug.core.breakpointMarker"
47   *      attribute name ="exampleAttribute"&gt;
48   *   &lt;/marker&gt;
49   * &lt;/extension&gt;
50   * </pre>
51   * <p>
52   * The breakpoint manager instantiates persisted breakpoints by
53   * traversing all markers that are a subtype of
54   * <code>"org.eclipse.debug.core.breakpointMarker"</code>, and 
55   * instantiating the class defined by the <code>class</code> attribute
56   * on the associated breakpoint extension. The method <code>setMarker</code>
57   * is then called to associate a marker with the breakpoint.
58   * </p>
59   * <p>
60   * Breakpoints may or may not be registered with the breakpoint manager, and
61   * are persisted and restored as such. Since marker definitions only allow
62   * all or none of a specific marker type to be persisted, breakpoints define
63   * a <code>PERSISTED</code> attribute for selective persistence of breakpoints
64   * of the same type.
65   * </p>
66   * 
67   * @since 2.0
68   */
69  
70  public interface IBreakpoint extends IAdaptable {
71      
72      /**
73       * Root breakpoint marker type  
74       * (value <code>"org.eclipse.debug.core.breakpointMarker"</code>).
75       */
76      public static final String   BREAKPOINT_MARKER = DebugPlugin.getUniqueIdentifier() + ".breakpointMarker"; //$NON-NLS-1$
77      
78      /**
79       * Line breakpoint marker type
80       * (value <code>"org.eclipse.debug.core.lineBreakpoint"</code>).
81       */
82      public static final String   LINE_BREAKPOINT_MARKER = DebugPlugin.getUniqueIdentifier() + ".lineBreakpointMarker"; //$NON-NLS-1$
83              
84      /**
85       * Enabled breakpoint marker attribute (value <code>"org.eclipse.debug.core.enabled"</code>).
86       * The attribute is a <code>boolean</code> corresponding to the
87       * enabled state of a breakpoint.
88       *
89       * @see org.eclipse.core.resources.IMarker#getAttribute(String, boolean)
90       */
91      public static final String   ENABLED= "org.eclipse.debug.core.enabled"; //$NON-NLS-1$
92      
93      /**
94       * Debug model identifier breakpoint marker attribute (value <code>"org.eclipse.debug.core.id"</code>).
95       * The attribute is a <code>String</code> corresponding to the
96       * identifier of the debug model a breakpoint is associated with.
97       */
98      public static final String   ID= "org.eclipse.debug.core.id"; //$NON-NLS-1$
99      
100     /**
101      * Registered breakpoint marker attribute (value <code>"org.eclipse.debug.core.registered"</code>).
102      * The attribute is a <code>boolean</code> corresponding to
103      * whether a breakpoint has been registered with the breakpoint manager.
104      *
105      * @see org.eclipse.core.resources.IMarker#getAttribute(String, boolean)
106      */
107     public static final String   REGISTERED= "org.eclipse.debug.core.registered"; //$NON-NLS-1$   
108     
109     /**
110      * Persisted breakpoint marker attribute (value <code>"org.eclipse.debug.core.persisted"</code>).
111      * The attribute is a <code>boolean</code> corresponding to
112      * whether a breakpoint is to be persisted across workspace
113      * invocations.
114      *
115      * @see org.eclipse.core.resources.IMarker#getAttribute(String, boolean)
116      */
117     public static final String   PERSISTED= "org.eclipse.debug.core.persisted"; //$NON-NLS-1$
118     
119     /**
120      * Deletes this breakpoint's underlying marker, and removes
121      * this breakpoint from the breakpoint manager.
122      *
123      * @exception CoreException if unable to delete this breakpoint's
124      *  underlying marker
125      */
126     public void delete() throws CoreException;
127     
128     /**
129      * Returns the marker associated with this breakpoint, or
130      * <code>null</code> if no marker is associated with this breakpoint.
131      * 
132      * @return associated marker, or <code>null</code> if there is
133      *  no associated marker.
134      */
135     public IMarker getMarker();
136     /**
137      * Sets the marker associated with this breakpoint. This method is
138      * called once at breakpoint creation.
139      * 
140      * @param marker the marker to associate with this breakpoint
141      * @exception CoreException if an error occurs accessing the marker
142      */
143     public void setMarker(IMarker marker) throws CoreException;
144     /**
145      * Returns the identifier of the debug model this breakpoint is
146      * associated with.
147      * 
148      * @return the identifier of the debug model this breakpoint is
149      *  associated with
150      */
151     public String   getModelIdentifier();
152     /**
153      * Returns whether this breakpoint is enabled
154      * 
155      * @return whether this breakpoint is enabled
156      * @exception CoreException if unable to access the associated
157      *  attribute from this breakpoint's underlying marker
158      */
159     public boolean isEnabled() throws CoreException;
160     /**
161      * Sets the enabled state of this breakpoint. This has no effect
162      * if the current enabled state is the same as specified by the
163      * enabled parameter.
164      * 
165      * @param enabled  whether this breakpoint should be enabled
166      * @exception CoreException if unable to set the associated attribute on
167      *  this breakpoint's underlying marker.
168      */
169     public void setEnabled(boolean enabled) throws CoreException;
170     
171     /**
172      * Returns whether this breakpoint is currently registered with
173      * the breakpoint manager.
174      * 
175      * @return whether this breakpoint is currently registered with
176      *  the breakpoint manager
177      * @exception CoreException if unable to access the associated 
178      *  attribute on this breakpoint's underlying marker
179      */
180     public boolean isRegistered() throws CoreException;
181     
182     /**
183      * Sets whether this breakpoint is currently registered with the
184      * breakpoint manager. 
185      * 
186      * @param registered whether this breakpoint is registered with the
187      *   breakpoint manager
188      * @exception CoreException if unable to set the associated attribute
189      *  on this breakpoint's underlying marker.
190      */
191     public void setRegistered(boolean registered) throws CoreException;
192     
193     /**
194      * Returns whether this breakpoint is to be persisted across
195      * workspace invocations, or when a project is closed and re-opened.
196      * Since marker definitions only allow all/none of a specific type
197      * of marker to be persisted (rather than selected markers of a
198      * specific type), breakpoints define this functionality.
199      * 
200      * @return whether this breakpoint is to be persisted
201      * @exception CoreException if unable to access the associated attribute
202      *  on this breakpoint's underlying marker
203      */
204     public boolean isPersisted() throws CoreException;
205     
206     /**
207      * Sets whether this breakpoint is to be persisted across
208      * workspace invocations, or when a project is closed and re-opened.
209      * Has no effect if this breakpoint's marker definition is defined as not
210      * persisted. Sets the underlying <code>TRANSIENT</code> attribute on this
211      * breakpoint's marker to <code>true</code>.
212      * 
213      * @param registered whether this breakpoint is to be persisted across
214      * workspace invocations
215      * @exception CoreException if unable to set the associated attribute on
216      *  this breakpoint's underlying marker.
217      */
218     public void setPersisted(boolean registered) throws CoreException;
219     
220 }
221 
222 
223
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags