org.eclipse.core.resources

Interface IMarker

All Superinterfaces:

IAdaptable

public interface IMarker
extends IAdaptable

Markers are a general mechanism for associating notes and meta-data with resources.

Markers themselves are handles in the same way as IResources are handles. Instances of IMarker do not hold the attributes themselves but rather uniquely refer to the attribute container. As such, their state may change underneath the handle with no warning to the holder of the handle.

The Resources plug-in provides a general framework for defining and manipulating markers and provides several standard marker types.

Each marker has:

• a type string, specifying its type (e.g. "org.eclipse.core.resources.taskmarker"),
• an identifier which is unique (relative to a particular resource)

Specific types of markers may carry additional information.

The resources plug-in defines five standard types:

• org.eclipse.core.resources.marker
• org.eclipse.core.resources.taskmarker
• org.eclipse.core.resources.problemmarker
• org.eclipse.core.resources.bookmark
• org.eclipse.core.resources.textmarker

The plug-in also provides an extension point ( org.eclipse.core.resources.markers) into which other plug-ins can install marker type declaration extensions.

Marker types are declared within a multiple inheritance type system. New markers are defined in the plugin.xml file of the declaring plug-in. A valid declaration contains elements as defined by the extension point DTD:

• type - the unique name of the marker type
• super - the list of marker types of which this marker is to be considered a sub-type
• attributes - the list of standard attributes which may be present on this type of marker
• persistent - whether markers of this type should be persisted by the platform

All markers declared as persistent are saved when the workspace is saved, except those explicitly set as transient (the TRANSIENT attribute is set as true). A plug-in which defines a persistent marker is not directly involved in saving and restoring the marker. Markers are not under version and configuration management, and cannot be shared via VCM repositories.

Markers implement the IAdaptable interface; extensions are managed by the platform's adapter manager.

Restriction:

This interface is not intended to be implemented by clients.

Restriction:

This interface is not intended to be extended by clients.

Field Summary

Fields

Modifier and Type	Field and Description
static String	BOOKMARK Bookmark marker type.
static String	CHAR_END Character end marker attribute.
static String	CHAR_START Character start marker attribute.
static String	DONE Done marker attribute.
static String	LINE_NUMBER Line number marker attribute.
static String	LOCATION Location marker attribute.
static String	MARKER Base marker type.
static String	MESSAGE Message marker attribute.
static String	PRIORITY Priority marker attribute.
static int	PRIORITY_HIGH High priority constant (value 2).
static int	PRIORITY_LOW Low priority constant (value 0).
static int	PRIORITY_NORMAL Normal priority constant (value 1).
static String	PROBLEM Problem marker type.
static String	SEVERITY Severity marker attribute.
static int	SEVERITY_ERROR Error severity constant (value 2) indicating an error state.
static int	SEVERITY_INFO Info severity constant (value 0) indicating information only.
static int	SEVERITY_WARNING Warning severity constant (value 1) indicating a warning.
static String	SOURCE_ID Source id attribute.
static String	TASK Task marker type.
static String	TEXT Text marker type.
static String	TRANSIENT Transient marker attribute.
static String	USER_EDITABLE User editable marker attribute.

Method Summary

Modifier and Type	Method and Description
void	delete() Deletes this marker from its associated resource.
boolean	equals(Object object) Tests this marker for equality with the given object.
boolean	exists() Returns whether this marker exists in the workspace.
Object	getAttribute(String attributeName) Returns the attribute with the given name.
boolean	getAttribute(String attributeName, boolean defaultValue) Returns the boolean-valued attribute with the given name.
int	getAttribute(String attributeName, int defaultValue) Returns the integer-valued attribute with the given name.
String	getAttribute(String attributeName, String defaultValue) Returns the string-valued attribute with the given name.
Map<String,Object>	getAttributes() Returns a map with all the attributes for the marker.
Object[]	getAttributes(String[] attributeNames) Returns the attributes with the given names.
long	getCreationTime() Returns the time at which this marker was created.
long	getId() Returns the id of the marker.
IResource	getResource() Returns the resource with which this marker is associated.
String	getType() Returns the type of this marker.
boolean	isSubtypeOf(String superType) Returns whether the type of this marker is considered to be a sub-type of the given marker type.
void	setAttribute(String attributeName, boolean value) Sets the boolean-valued attribute with the given name.
void	setAttribute(String attributeName, int value) Sets the integer-valued attribute with the given name.
void	setAttribute(String attributeName, Object value) Sets the attribute with the given name.
void	setAttributes(Map<String,? extends Object> attributes) Sets the attributes for this marker to be the ones contained in the given table.
void	setAttributes(String[] attributeNames, Object[] values) Sets the given attribute key-value pairs on this marker.

Methods inherited from interface org.eclipse.core.runtime.IAdaptable

getAdapter

Field Detail

MARKER

static final String MARKER

Base marker type.

See Also:

getType(), Constant Field Values

TASK

static final String TASK

Task marker type.

See Also:

getType(), Constant Field Values

PROBLEM

static final String PROBLEM

Problem marker type.

See Also:

getType(), Constant Field Values

TEXT

static final String TEXT

Text marker type.

See Also:

getType(), Constant Field Values

BOOKMARK

static final String BOOKMARK

Bookmark marker type.

See Also:

getType(), Constant Field Values

SEVERITY

static final String SEVERITY

Severity marker attribute. A number from the set of error, warning and info severities defined by the platform.

See Also:

SEVERITY_ERROR, SEVERITY_WARNING, SEVERITY_INFO, getAttribute(String, int), Constant Field Values

MESSAGE

static final String MESSAGE

Message marker attribute. A localized string describing the nature of the marker (e.g., a name for a bookmark or task). The content and form of this attribute is not specified or interpreted by the platform.

See Also:

getAttribute(String, String), Constant Field Values

LOCATION

static final String LOCATION

Location marker attribute. The location is a human-readable (localized) string which can be used to distinguish between markers on a resource. As such it should be concise and aimed at users. The content and form of this attribute is not specified or interpreted by the platform.

See Also:

getAttribute(String, String), Constant Field Values

PRIORITY

static final String PRIORITY

Priority marker attribute. A number from the set of high, normal and low priorities defined by the platform.

See Also:

PRIORITY_HIGH, PRIORITY_NORMAL, PRIORITY_LOW, getAttribute(String, int), Constant Field Values

DONE

static final String DONE

Done marker attribute. A boolean value indicating whether the marker (e.g., a task) is considered done.

See Also:

getAttribute(String, String), Constant Field Values

CHAR_START

static final String CHAR_START

Character start marker attribute. An integer value indicating where a text marker starts. This attribute is zero-relative and inclusive.

See Also:

getAttribute(String, String), Constant Field Values

CHAR_END

static final String CHAR_END

Character end marker attribute. An integer value indicating where a text marker ends. This attribute is zero-relative and exclusive.

See Also:

getAttribute(String, String), Constant Field Values

LINE_NUMBER

static final String LINE_NUMBER

Line number marker attribute. An integer value indicating the line number for a text marker. This attribute is 1-relative.

See Also:

getAttribute(String, String), Constant Field Values

TRANSIENT

static final String TRANSIENT

Transient marker attribute. A boolean value indicating whether the marker (e. g., a task) is considered transient even if its type is declared as persistent.

Since:

2.1

See Also:

getAttribute(String, String), Constant Field Values

USER_EDITABLE

static final String USER_EDITABLE

User editable marker attribute. A boolean value indicating whether a user should be able to manually change the marker (e.g. a task). The default is true. Note that the value of this attribute is to be used by the UI as a suggestion and its value will NOT be interpreted by Core in any manner and will not be enforced by Core when performing any operations on markers.

Since:

2.1

See Also:

getAttribute(String, String), Constant Field Values

SOURCE_ID

static final String SOURCE_ID

Source id attribute. A string attribute that can be used by tools that generate markers to indicate the source of the marker. Use of this attribute is optional and its format or existence is not enforced. This attribute is intended to improve serviceability by providing a value that product support personnel or automated tools can use to determine appropriate help and resolutions for markers.

Since:

3.3

See Also:

getAttribute(String, String), Constant Field Values

PRIORITY_HIGH

static final int PRIORITY_HIGH

High priority constant (value 2).

See Also:

getAttribute(String, int), Constant Field Values

PRIORITY_NORMAL

static final int PRIORITY_NORMAL

Normal priority constant (value 1).

See Also:

getAttribute(String, int), Constant Field Values

PRIORITY_LOW

static final int PRIORITY_LOW

Low priority constant (value 0).

See Also:

getAttribute(String, int), Constant Field Values

SEVERITY_ERROR

static final int SEVERITY_ERROR

Error severity constant (value 2) indicating an error state.

See Also:

getAttribute(String, int), Constant Field Values

SEVERITY_WARNING

static final int SEVERITY_WARNING

Warning severity constant (value 1) indicating a warning.

See Also:

getAttribute(String, int), Constant Field Values

SEVERITY_INFO

static final int SEVERITY_INFO

Info severity constant (value 0) indicating information only.

See Also:

getAttribute(String, int), Constant Field Values

Method Detail

delete

void delete()
     throws CoreException

Deletes this marker from its associated resource. This method has no effect if this marker does not exist.

Throws:

CoreException - if this marker could not be deleted. Reasons include:

• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

See Also:

IResourceRuleFactory.markerRule(IResource)

equals

boolean equals(Object object)

Tests this marker for equality with the given object. Two markers are equal if their id and resource are both equal.

Overrides:

equals in class Object

Parameters:

object - the other object

Returns:

an indication of whether the objects are equal

exists

boolean exists()

Returns whether this marker exists in the workspace. A marker exists if its resource exists and has a marker with the marker's id.

Returns:

true if this marker exists, otherwise false

getAttribute

Object getAttribute(String attributeName)
             throws CoreException

Returns the attribute with the given name. The result is an instance of one of the following classes: String, Integer, or Boolean. Returns null if the attribute is undefined.

Parameters:

attributeName - the name of the attribute

Returns:

the value, or null if the attribute is undefined.

Throws:

CoreException - if this method fails. Reasons include:

• This marker does not exist.

getAttribute

int getAttribute(String attributeName,
                 int defaultValue)

Returns the integer-valued attribute with the given name. Returns the given default value if the attribute is undefined. or the marker does not exist or is not an integer value.

Parameters:

attributeName - the name of the attribute

defaultValue - the value to use if no value is found

Returns:

the value or the default value if no value was found.

getAttribute

String getAttribute(String attributeName,
                    String defaultValue)

Returns the string-valued attribute with the given name. Returns the given default value if the attribute is undefined or the marker does not exist or is not a string value.

Parameters:

attributeName - the name of the attribute

defaultValue - the value to use if no value is found

Returns:

the value or the default value if no value was found.

getAttribute

boolean getAttribute(String attributeName,
                     boolean defaultValue)

Returns the boolean-valued attribute with the given name. Returns the given default value if the attribute is undefined or the marker does not exist or is not a boolean value.

Parameters:

attributeName - the name of the attribute

defaultValue - the value to use if no value is found

Returns:

the value or the default value if no value was found.

getAttributes

Map<String,Object> getAttributes()
                          throws CoreException

Returns a map with all the attributes for the marker. If the marker has no attributes then null is returned.

Returns:

a map of attribute keys and values (key type : String value type : String, Integer, or Boolean) or null.

Throws:

CoreException - if this method fails. Reasons include:

• This marker does not exist.

getAttributes

Object[] getAttributes(String[] attributeNames)
                throws CoreException

Returns the attributes with the given names. The result is an an array whose elements correspond to the elements of the given attribute name array. Each element is null or an instance of one of the following classes: String, Integer, or Boolean.

Parameters:

attributeNames - the names of the attributes

Returns:

the values of the given attributes.

Throws:

CoreException - if this method fails. Reasons include:

• This marker does not exist.

getCreationTime

long getCreationTime()
              throws CoreException

Returns the time at which this marker was created.

Returns:

the difference, measured in milliseconds, between the time at which this marker was created and midnight, January 1, 1970 UTC, or 0L if the creation time is not known (this can occur in workspaces created using v2.0 or earlier).

Throws:

CoreException - if this method fails. Reasons include:

• This marker does not exist.

Since:

2.1

getId

long getId()

Returns the id of the marker. The id of a marker is unique relative to the resource with which the marker is associated. Marker ids are not globally unique.

Returns:

the id of the marker

See Also:

IResource.findMarker(long)

getResource

IResource getResource()

Returns the resource with which this marker is associated.

Returns:

the resource with which this marker is associated

getType

String getType()
        throws CoreException

Returns the type of this marker. The returned marker type will not be null.

Returns:

the type of this marker

Throws:

CoreException - if this method fails. Reasons include:

• This marker does not exist.

isSubtypeOf

boolean isSubtypeOf(String superType)
             throws CoreException

Returns whether the type of this marker is considered to be a sub-type of the given marker type.

Returns:

boolean trueif the marker's type is the same as (or a sub-type of) the given type.

Throws:

CoreException - if this method fails. Reasons include:

• This marker does not exist.

setAttribute

void setAttribute(String attributeName,
                  int value)
           throws CoreException

Sets the integer-valued attribute with the given name.

This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this marker has been modified.

Parameters:

attributeName - the name of the attribute

value - the value

Throws:

CoreException - if this method fails. Reasons include:

• This marker does not exist.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

See Also:

IResourceRuleFactory.markerRule(IResource)

setAttribute

void setAttribute(String attributeName,
                  Object value)
           throws CoreException

Sets the attribute with the given name. The value must be null or an instance of one of the following classes: String, Integer, or Boolean. If the value is null, the attribute is considered to be undefined.

The attribute value cannot be String whose UTF encoding exceeds 65535 bytes. On persistent markers this limit is enforced by an assertion.

This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this marker has been modified.

Parameters:

attributeName - the name of the attribute

value - the value, or null if the attribute is to be undefined

Throws:

CoreException - if this method fails. Reasons include:

• This marker does not exist.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

See Also:

IResourceRuleFactory.markerRule(IResource)

setAttribute

void setAttribute(String attributeName,
                  boolean value)
           throws CoreException

Sets the boolean-valued attribute with the given name.

This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this marker has been modified.

Parameters:

attributeName - the name of the attribute

value - the value

Throws:

CoreException - if this method fails. Reasons include:

• This marker does not exist.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

See Also:

IResourceRuleFactory.markerRule(IResource)

setAttributes

void setAttributes(String[] attributeNames,
                   Object[] values)
            throws CoreException

Sets the given attribute key-value pairs on this marker. The values must be null or an instance of one of the following classes: String, Integer, or Boolean. If a value is null, the new value of the attribute is considered to be undefined.

The values of the attributes cannot be String whose UTF encoding exceeds 65535 bytes. On persistent markers this limit is enforced by an assertion.

This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this marker has been modified.

Parameters:

attributeNames - an array of attribute names

values - an array of attribute values

Throws:

CoreException - if this method fails. Reasons include:

• This marker does not exist.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

See Also:

IResourceRuleFactory.markerRule(IResource)

setAttributes

void setAttributes(Map<String,? extends Object> attributes)
            throws CoreException

Sets the attributes for this marker to be the ones contained in the given table. The values must be an instance of one of the following classes: String, Integer, or Boolean. Attributes previously set on the marker but not included in the given map are considered to be removals. Setting the given map to be null is equivalent to removing all marker attributes.

The values of the attributes cannot be String whose UTF encoding exceeds 65535 bytes. On persistent markers this limit is enforced by an assertion.

This method changes resources; these changes will be reported in a subsequent resource change event, including an indication that this marker has been modified.

Parameters:

attributes - a map of attribute names to attribute values (key type : String value type : String, Integer, or Boolean) or null

Throws:

CoreException - if this method fails. Reasons include:

• This marker does not exist.
• Resource changes are disallowed during certain types of resource change event notification. See IResourceChangeEvent for more details.

See Also:

IResourceRuleFactory.markerRule(IResource)