IMarker


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 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.core.resources;
12  
13  import java.util.Map  ;
14  import org.eclipse.core.runtime.CoreException;
15  import org.eclipse.core.runtime.IAdaptable;
16  
17  /**
18   * Markers are a general mechanism for associating notes and meta-data with
19   * resources.
20   * <p>
21   * Markers themselves are handles in the same way as <code>IResources</code>
22   * are handles.  Instances of <code>IMarker</code> do not hold the attributes
23   * themselves but rather uniquely refer to the attribute container.  As such,
24   * their state may change underneath the handle with no warning to the holder
25   * of the handle.
26   * </p>
27   * The Resources plug-in provides a general framework for 
28   * defining and manipulating markers and provides several standard marker types.
29   * </p>
30   * <p>
31   * Each marker has:<ul>
32   * <li> a type string, specifying its type (e.g. 
33   *      <code>"org.eclipse.core.resources.taskmarker"</code>), </li>
34   * <li> an identifier which is unique (relative to a particular resource)</li>
35   * </ul>
36   * Specific types of markers may carry additional information.
37   * </p>
38   * <p>
39   * The resources plug-in defines five standard types:
40   * <ul>
41   * <li><code>org.eclipse.core.resources.marker</code></li>
42   * <li><code>org.eclipse.core.resources.taskmarker</code></li>
43   * <li><code>org.eclipse.core.resources.problemmarker</code></li>
44   * <li><code>org.eclipse.core.resources.bookmark</code></li>
45   * <li><code>org.eclipse.core.resources.textmarker</code></li>
46   * </ul>
47   * The plug-in also provides an extension point (
48   * <code>org.eclipse.core.resources.markers</code>) into which other
49   * plug-ins can install marker type declaration extensions.
50   * </p>
51   * <p>
52   * Marker types are declared within a multiple inheritance type system.
53   * New markers are defined in the <code>plugin.xml</code> file of the
54   * declaring plug-in.  A valid declaration contains elements as defined by
55   * the extension point DTD:
56   * <ul>
57   * <li><i>type</i> - the unique name of the marker type</li>
58   * <li><i>super</i> - the list of marker types of which this marker is to be considered a sub-type</li>
59   * <li><i>attributes</i> - the list of standard attributes which may be present on this type of marker</li>
60   * <li><i>persistent</i> - whether markers of this type should be persisted by the platform</li>
61   * </li>
62   * </p>
63   * <p>All markers declared as <code>persistent</code> are saved when the
64   * workspace is saved, except those explicitly set as transient (the
65   * <code>TRANSIENT</code> attribute is set as <code>true</code>). A plug-in
66   * which defines a persistent marker is not directly involved in saving and
67   * restoring the marker. Markers are not under version and configuration
68   * management, and cannot be shared via VCM repositories.
69   * </p>
70   * <p>
71   * This interface is not intended to be implemented by developers.
72   * </p>
73   * <p>
74   * Markers implement the <code>IAdaptable</code> interface;
75   * extensions are managed by the platform's adapter manager.
76   * </p>
77   */
78  public interface IMarker extends IAdaptable {
79  
80      /*====================================================================
81       * Marker types:
82       *====================================================================*/
83  
84      /** 
85       * Base marker type. 
86       *
87       * @see #getType()
88       */
89      public static final String   MARKER = ResourcesPlugin.PI_RESOURCES + ".marker"; //$NON-NLS-1$
90  
91      /** 
92       * Task marker type. 
93       *
94       * @see #getType()
95       */
96      public static final String   TASK = ResourcesPlugin.PI_RESOURCES + ".taskmarker"; //$NON-NLS-1$
97  
98      /** 
99       * Problem marker type. 
100      *
101      * @see #getType()
102      */
103     public static final String   PROBLEM = ResourcesPlugin.PI_RESOURCES + ".problemmarker"; //$NON-NLS-1$
104 
105     /** 
106      * Text marker type. 
107      *
108      * @see #getType()
109      */
110     public static final String   TEXT = ResourcesPlugin.PI_RESOURCES + ".textmarker"; //$NON-NLS-1$
111 
112     /** 
113      * Bookmark marker type. 
114      *
115      * @see #getType()
116      */
117     public static final String   BOOKMARK = ResourcesPlugin.PI_RESOURCES + ".bookmark"; //$NON-NLS-1$
118 
119     /*====================================================================
120      * Marker attributes:
121      *====================================================================*/
122 
123     /** 
124      * Severity marker attribute.  A number from the set of error, warning and info
125      * severities defined by the platform.
126      *
127      * @see #SEVERITY_ERROR
128      * @see #SEVERITY_WARNING
129      * @see #SEVERITY_INFO
130      * @see #getAttribute(String, int)
131      */
132     public static final String   SEVERITY = "severity"; //$NON-NLS-1$
133 
134     /** 
135      * Message marker attribute.  A localized string describing the nature
136      * of the marker (e.g., a name for a bookmark or task).  The content
137      * and form of this attribute is not specified or interpreted by the platform.
138      *
139      * @see #getAttribute(String, String)
140      */
141     public static final String   MESSAGE = "message"; //$NON-NLS-1$
142 
143     /** 
144      * Location marker attribute.  The location is a human-readable (localized) string which
145      * can be used to distinguish between markers on a resource.  As such it 
146      * should be concise and aimed at users.  The content and 
147      * form of this attribute is not specified or interpreted by the platform.
148      *
149      * @see #getAttribute(String, String)
150      */
151     public static final String   LOCATION = "location"; //$NON-NLS-1$
152 
153     /** 
154      * Priority marker attribute.  A number from the set of high, normal and low 
155      * priorities defined by the platform.
156      * 
157      * @see #PRIORITY_HIGH
158      * @see #PRIORITY_NORMAL
159      * @see #PRIORITY_LOW
160      * @see #getAttribute(String, int)
161      */
162     public static final String   PRIORITY = "priority"; //$NON-NLS-1$
163 
164     /** 
165      * Done marker attribute.  A boolean value indicating whether 
166      * the marker (e.g., a task) is considered done.  
167      *
168      * @see #getAttribute(String, String)
169      */
170     public static final String   DONE = "done"; //$NON-NLS-1$
171 
172     /** 
173      * Character start marker attribute.  An integer value indicating where a text
174      * marker starts.  This attribute is zero-relative and inclusive.
175      *
176      * @see #getAttribute(String, String)
177      */
178     public static final String   CHAR_START = "charStart"; //$NON-NLS-1$
179 
180     /** 
181      * Character end marker attribute.  An integer value indicating where a text
182      * marker ends.  This attribute is zero-relative and exclusive.
183      *
184      * @see #getAttribute(String, String)
185      */
186     public static final String   CHAR_END = "charEnd"; //$NON-NLS-1$
187 
188     /** 
189      * Line number marker attribute.  An integer value indicating the line number
190      * for a text marker.  This attribute is 1-relative.
191      *
192      * @see #getAttribute(String, String)
193      */
194     public static final String   LINE_NUMBER = "lineNumber"; //$NON-NLS-1$
195 
196     /** 
197      * Transient marker attribute.  A boolean value indicating whether the
198      * marker (e. g., a task) is considered transient even if its type is
199      * declared as persistent. 
200      *
201      * @see #getAttribute(String, String)
202      * @since 2.1 
203      */
204     public static final String   TRANSIENT = "transient"; //$NON-NLS-1$
205 
206     /** 
207      * User editable marker attribute.  A boolean value indicating whether a
208      * user should be able to manually change the marker (e.g. a task). The
209      * default is <code>true</code>. Note that the value of this attribute
210      * is to be used by the UI as a suggestion and its value will NOT be
211      * interpreted by Core in any manner and will not be enforced by Core 
212      * when performing any operations on markers.
213      *
214      * @see #getAttribute(String, String)
215      * @since 2.1 
216      */
217     public static final String   USER_EDITABLE = "userEditable"; //$NON-NLS-1$
218 
219     /**
220      * Source id attribute.  A string attribute that can be used by tools that
221      * generate markers to indicate the source of the marker. Use of this attribute is
222      * optional and its format or existence is not enforced.  This attribute is
223      * intended to improve serviceability by providing a value that product support
224      * personnel or automated tools can use to determine appropriate help and
225      * resolutions for markers.
226      * 
227      * @see #getAttribute(String, String)
228      * @since 3.3
229      */
230     public static final String   SOURCE_ID = "sourceId"; //$NON-NLS-1$
231 
232     /*====================================================================
233      * Marker attributes values:
234      *====================================================================*/
235 
236     /** 
237      * High priority constant (value 2).
238      *
239      * @see #getAttribute(String, int)
240      */
241     public static final int PRIORITY_HIGH = 2;
242 
243     /** 
244      * Normal priority constant (value 1).
245      *
246      * @see #getAttribute(String, int)
247      */
248     public static final int PRIORITY_NORMAL = 1;
249 
250     /** 
251      * Low priority constant (value 0).
252      *
253      * @see #getAttribute(String, int)
254      */
255     public static final int PRIORITY_LOW = 0;
256 
257     /** 
258      * Error severity constant (value 2) indicating an error state.
259      *
260      * @see #getAttribute(String, int)
261      */
262     public static final int SEVERITY_ERROR = 2;
263 
264     /** 
265      * Warning severity constant (value 1) indicating a warning.
266      *
267      * @see #getAttribute(String, int)
268      */
269     public static final int SEVERITY_WARNING = 1;
270 
271     /** 
272      * Info severity constant (value 0) indicating information only.
273      *
274      * @see #getAttribute(String, int)
275      */
276     public static final int SEVERITY_INFO = 0;
277 
278     /**
279      * Deletes this marker from its associated resource.  This method has no
280      * effect if this marker does not exist.
281      *
282      * @exception CoreException if this marker could not be deleted. Reasons include:
283      * <ul>
284      * <li> Resource changes are disallowed during certain types of resource change 
285      *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
286      * </ul>
287      * @see IResourceRuleFactory#markerRule(IResource)
288      */
289     public void delete() throws CoreException;
290 
291     /**
292      * Tests this marker for equality with the given object.
293      * Two markers are equal if their id and resource are both equal.
294      * 
295      * @param object the other object
296      * @return an indication of whether the objects are equal
297      */
298     public boolean equals(Object   object);
299 
300     /**
301      * Returns whether this marker exists in the workspace.  A marker
302      * exists if its resource exists and has a marker with the marker's id.
303      *
304      * @return <code>true</code> if this marker exists, otherwise
305      *    <code>false</code>
306      */
307     public boolean exists();
308 
309     /**
310      * Returns the attribute with the given name.  The result is an instance of one
311      * of the following classes: <code>String</code>, <code>Integer</code>, 
312      * or <code>Boolean</code>.
313      * Returns <code>null</code> if the attribute is undefined.
314      *
315      * @param attributeName the name of the attribute
316      * @return the value, or <code>null</code> if the attribute is undefined.
317      * @exception CoreException if this method fails. Reasons include:
318      * <ul>
319      * <li> This marker does not exist.</li>
320      * </ul>
321      */
322     public Object   getAttribute(String   attributeName) throws CoreException;
323 
324     /**
325      * Returns the integer-valued attribute with the given name.  
326      * Returns the given default value if the attribute is undefined.
327      * or the marker does not exist or is not an integer value.
328      *
329      * @param attributeName the name of the attribute
330      * @param defaultValue the value to use if no value is found
331      * @return the value or the default value if no value was found.
332      */
333     public int getAttribute(String   attributeName, int defaultValue);
334 
335     /**
336      * Returns the string-valued attribute with the given name.  
337      * Returns the given default value if the attribute is undefined
338      * or the marker does not exist or is not a string value.
339      *
340      * @param attributeName the name of the attribute
341      * @param defaultValue the value to use if no value is found
342      * @return the value or the default value if no value was found.
343      */
344     public String   getAttribute(String   attributeName, String   defaultValue);
345 
346     /**
347      * Returns the boolean-valued attribute with the given name.  
348      * Returns the given default value if the attribute is undefined
349      * or the marker does not exist or is not a boolean value.
350      *
351      * @param attributeName the name of the attribute
352      * @param defaultValue the value to use if no value is found
353      * @return the value or the default value if no value was found.
354      */
355     public boolean getAttribute(String   attributeName, boolean defaultValue);
356 
357     /**
358      * Returns a map with all the attributes for the marker.
359      * If the marker has no attributes then <code>null</code> is returned.
360      *
361      * @return a map of attribute keys and values (key type : <code>String</code> 
362      *      value type : <code>String</code>, <code>Integer</code>, or 
363      *      <code>Boolean</code>) or <code>null</code>.
364      * @exception CoreException if this method fails. Reasons include:
365      * <ul>
366      * <li> This marker does not exist.</li>
367      * </ul>
368      */
369     public Map   getAttributes() throws CoreException;
370 
371     /**
372      * Returns the attributes with the given names.  The result is an an array 
373      * whose elements correspond to the elements of the given attribute name
374      * array.  Each element is <code>null</code> or an instance of one
375      * of the following classes: <code>String</code>, <code>Integer</code>, 
376      * or <code>Boolean</code>.
377      *
378      * @param attributeNames the names of the attributes
379      * @return the values of the given attributes.
380      * @exception CoreException if this method fails. Reasons include:
381      * <ul>
382      * <li> This marker does not exist.</li>
383      * </ul>
384      */
385     public Object  [] getAttributes(String  [] attributeNames) throws CoreException;
386 
387     /**
388      * Returns the time at which this marker was created.
389      *
390      * @return the difference, measured in milliseconds, between the time at which
391      *    this marker was created and midnight, January 1, 1970 UTC, or <code>0L</code>
392      *    if the creation time is not known (this can occur in workspaces created using v2.0 or earlier).
393      * @exception CoreException if this method fails. Reasons include:
394      * <ul>
395      * <li> This marker does not exist.</li>
396      * </ul>
397      * @since 2.1
398      */
399     public long getCreationTime() throws CoreException;
400 
401     /**
402      * Returns the id of the marker.  The id of a marker is unique
403      * relative to the resource with which the marker is associated.
404      * Marker ids are not globally unique.
405      *
406      * @return the id of the marker
407      * @see IResource#findMarker(long)
408      */
409     public long getId();
410 
411     /**
412      * Returns the resource with which this marker is associated. 
413      *
414      * @return the resource with which this marker is associated
415      */
416     public IResource getResource();
417 
418     /**
419      * Returns the type of this marker. The returned marker type will not be 
420      * <code>null</code>.
421      *
422      * @return the type of this marker
423      * @exception CoreException if this method fails. Reasons include:
424      * <ul>
425      * <li> This marker does not exist.</li>
426      * </ul>
427      */
428     public String   getType() throws CoreException;
429 
430     /**
431      * Returns whether the type of this marker is considered to be a sub-type of
432      * the given marker type. 
433      *
434      * @return boolean <code>true</code>if the marker's type
435      *      is the same as (or a sub-type of) the given type.
436      * @exception CoreException if this method fails. Reasons include:
437      * <ul>
438      * <li> This marker does not exist.</li>
439      * </ul>
440      */
441     public boolean isSubtypeOf(String   superType) throws CoreException;
442 
443     /**
444      * Sets the integer-valued attribute with the given name.  
445      * <p>
446      * This method changes resources; these changes will be reported
447      * in a subsequent resource change event, including an indication 
448      * that this marker has been modified.
449      * </p>
450      *
451      * @param attributeName the name of the attribute
452      * @param value the value
453      * @exception CoreException if this method fails. Reasons include:
454      * <ul>
455      * <li> This marker does not exist.</li>
456      * <li> Resource changes are disallowed during certain types of resource change 
457      *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
458      * </ul>
459      * @see IResourceRuleFactory#markerRule(IResource)
460      */
461     public void setAttribute(String   attributeName, int value) throws CoreException;
462 
463     /**
464      * Sets the attribute with the given name.  The value must be <code>null</code> or 
465      * an instance of one of the following classes: 
466      * <code>String</code>, <code>Integer</code>, or <code>Boolean</code>.
467      * If the value is <code>null</code>, the attribute is considered to be undefined.
468      * <p>
469      * This method changes resources; these changes will be reported
470      * in a subsequent resource change event, including an indication 
471      * that this marker has been modified.
472      * </p>
473      *
474      * @param attributeName the name of the attribute
475      * @param value the value, or <code>null</code> if the attribute is to be undefined
476      * @exception CoreException if this method fails. Reasons include:
477      * <ul>
478      * <li> This marker does not exist.</li>
479      * <li> Resource changes are disallowed during certain types of resource change 
480      *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
481      * </ul>
482      * @see IResourceRuleFactory#markerRule(IResource)
483      */
484     public void setAttribute(String   attributeName, Object   value) throws CoreException;
485 
486     /**
487      * Sets the boolean-valued attribute with the given name.  
488      * <p>
489      * This method changes resources; these changes will be reported
490      * in a subsequent resource change event, including an indication 
491      * that this marker has been modified.
492      * </p>
493      *
494      * @param attributeName the name of the attribute
495      * @param value the value
496      * @exception CoreException if this method fails. Reasons include:
497      * <ul>
498      * <li> This marker does not exist.</li>
499      * <li> Resource changes are disallowed during certain types of resource change 
500      *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
501      * </ul>
502      * @see IResourceRuleFactory#markerRule(IResource)
503      */
504     public void setAttribute(String   attributeName, boolean value) throws CoreException;
505 
506     /**
507      * Sets the given attribute key-value pairs on this marker.
508      * The values must be <code>null</code> or an instance of 
509      * one of the following classes: <code>String</code>, 
510      * <code>Integer</code>, or <code>Boolean</code>.
511      * If a value is <code>null</code>, the new value of the 
512      * attribute is considered to be undefined.
513      * <p>
514      * This method changes resources; these changes will be reported
515      * in a subsequent resource change event, including an indication 
516      * that this marker has been modified.
517      * </p>
518      *
519      * @param attributeNames an array of attribute names
520      * @param values an array of attribute values
521      * @exception CoreException if this method fails. Reasons include:
522      * <ul>
523      * <li> This marker does not exist.</li>
524      * <li> Resource changes are disallowed during certain types of resource change 
525      *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
526      * </ul>
527      * @see IResourceRuleFactory#markerRule(IResource)
528      */
529     public void setAttributes(String  [] attributeNames, Object  [] values) throws CoreException;
530 
531     /**
532      * Sets the attributes for this marker to be the ones contained in the
533      * given table. The values must be an instance of one of the following classes: 
534      * <code>String</code>, <code>Integer</code>, or <code>Boolean</code>.
535      * Attributes previously set on the marker but not included in the given map
536      * are considered to be removals. Setting the given map to be <code>null</code>
537      * is equivalent to removing all marker attributes.
538      * <p>
539      * This method changes resources; these changes will be reported
540      * in a subsequent resource change event, including an indication 
541      * that this marker has been modified.
542      * </p>
543      *
544      * @param attributes a map of attribute names to attribute values 
545      *      (key type : <code>String</code> value type : <code>String</code>, 
546      *      <code>Integer</code>, or <code>Boolean</code>) or <code>null</code>
547      * @exception CoreException if this method fails. Reasons include:
548      * <ul>
549      * <li> This marker does not exist.</li>
550      * <li> Resource changes are disallowed during certain types of resource change 
551      *       event notification. See <code>IResourceChangeEvent</code> for more details.</li>
552      * </ul>
553      * @see IResourceRuleFactory#markerRule(IResource)
554      */
555     public void setAttributes(Map   attributes) throws CoreException;
556 }
557
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags