KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > resources > 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 JavaDoc;
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 JavaDoc MARKER = ResourcesPlugin.PI_RESOURCES + ".marker"; //$NON-NLS-1$
90

91     /**
92      * Task marker type.
93      *
94      * @see #getType()
95      */

96     public static final String JavaDoc TASK = ResourcesPlugin.PI_RESOURCES + ".taskmarker"; //$NON-NLS-1$
97

98     /**
99      * Problem marker type.
100      *
101      * @see #getType()
102      */

103     public static final String JavaDoc PROBLEM = ResourcesPlugin.PI_RESOURCES + ".problemmarker"; //$NON-NLS-1$
104

105     /**
106      * Text marker type.
107      *
108      * @see #getType()
109      */

110     public static final String JavaDoc TEXT = ResourcesPlugin.PI_RESOURCES + ".textmarker"; //$NON-NLS-1$
111

112     /**
113      * Bookmark marker type.
114      *
115      * @see #getType()
116      */

117     public static final String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getAttribute(String JavaDoc 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 JavaDoc 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 JavaDoc getAttribute(String JavaDoc attributeName, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc[] getAttributes(String JavaDoc[] 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc attributeName, Object JavaDoc 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 JavaDoc 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 JavaDoc[] attributeNames, Object JavaDoc[] 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 JavaDoc attributes) throws CoreException;
556 }
557
Popular Tags