/*******************************************************************************
* Copyright (c) 2000, 2009 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.core.resources;
import java.util.Map;
import org.eclipse.core.runtime.CoreException;
import org.eclipse.core.runtime.IAdaptable;
/**
* Markers are a general mechanism for associating notes and meta-data with resources.
* <p>
* Markers themselves are handles in the same way as <code>IResources</code> are handles. Instances
* of <code>IMarker</code> 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.
* </p>
* The Resources plug-in provides a general framework for defining and manipulating markers and
* provides several standard marker types. </p>
* <p>
* Each marker has:
* <ul>
* <li>a type string, specifying its type (e.g. <code>"org.eclipse.core.resources.taskmarker"</code>
* ),</li>
* <li>an identifier which is unique (relative to a particular resource)</li>
* </ul>
* Specific types of markers may carry additional information.
* </p>
* <p>
* The resources plug-in defines five standard types:
* <ul>
* <li><code>org.eclipse.core.resources.marker</code></li>
* <li><code>org.eclipse.core.resources.taskmarker</code></li>
* <li><code>org.eclipse.core.resources.problemmarker</code></li>
* <li><code>org.eclipse.core.resources.bookmark</code></li>
* <li><code>org.eclipse.core.resources.textmarker</code></li>
* </ul>
* The plug-in also provides an extension point ( <code>org.eclipse.core.resources.markers</code>)
* into which other plug-ins can install marker type declaration extensions.
* </p>
* <p>
* Marker types are declared within a multiple inheritance type system. New markers are defined in
* the <code>plugin.xml</code> file of the declaring plug-in. A valid declaration contains elements
* as defined by the extension point DTD:
* <ul>
* <li><i>type</i> - the unique name of the marker type</li>
* <li><i>super</i> - the list of marker types of which this marker is to be considered a sub-type</li>
* <li><i>attributes</i> - the list of standard attributes which may be present on this type of
* marker</li>
* <li><i>persistent</i> - whether markers of this type should be persisted by the platform</li>
* </li>
* </p>
* <p>
* All markers declared as <code>persistent</code> are saved when the workspace is saved, except
* those explicitly set as transient (the <code>TRANSIENT</code> attribute is set as
* <code>true</code>). 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.
* </p>
* <p>
* Markers implement the <code>IAdaptable</code> interface; extensions are managed by the platform's
* adapter manager.
* </p>
*
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface IMarker extends IAdaptable {
/*====================================================================
* Marker types:
*====================================================================*/
/**
* Base marker type.
*
* @see #getType()
*/
public static final String MARKER= ResourcesPlugin.PI_RESOURCES + ".marker"; //$NON-NLS-1$
/**
* Task marker type.
*
* @see #getType()
*/
public static final String TASK= ResourcesPlugin.PI_RESOURCES + ".taskmarker"; //$NON-NLS-1$
/**
* Problem marker type.
*
* @see #getType()
*/
public static final String PROBLEM= ResourcesPlugin.PI_RESOURCES + ".problemmarker"; //$NON-NLS-1$
/**
* Text marker type.
*
* @see #getType()
*/
public static final String TEXT= ResourcesPlugin.PI_RESOURCES + ".textmarker"; //$NON-NLS-1$
/**
* Bookmark marker type.
*
* @see #getType()
*/
public static final String BOOKMARK= ResourcesPlugin.PI_RESOURCES + ".bookmark"; //$NON-NLS-1$
/*====================================================================
* Marker attributes:
*====================================================================*/
/**
* Severity marker attribute. A number from the set of error, warning and info severities
* defined by the platform.
*
* @see #SEVERITY_ERROR
* @see #SEVERITY_WARNING
* @see #SEVERITY_INFO
* @see #getAttribute(String, int)
*/
public static final String SEVERITY= "severity"; //$NON-NLS-1$
/**
* 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 #getAttribute(String, String)
*/
public static final String MESSAGE= "message"; //$NON-NLS-1$
/**
* 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 #getAttribute(String, String)
*/
public static final String LOCATION= "location"; //$NON-NLS-1$
/**
* Priority marker attribute. A number from the set of high, normal and low priorities defined
* by the platform.
*
* @see #PRIORITY_HIGH
* @see #PRIORITY_NORMAL
* @see #PRIORITY_LOW
* @see #getAttribute(String, int)
*/
public static final String PRIORITY= "priority"; //$NON-NLS-1$
/**
* Done marker attribute. A boolean value indicating whether the marker (e.g., a task) is
* considered done.
*
* @see #getAttribute(String, String)
*/
public static final String DONE= "done"; //$NON-NLS-1$
/**
* Character start marker attribute. An integer value indicating where a text marker starts.
* This attribute is zero-relative and inclusive.
*
* @see #getAttribute(String, String)
*/
public static final String CHAR_START= "charStart"; //$NON-NLS-1$
/**
* Character end marker attribute. An integer value indicating where a text marker ends. This
* attribute is zero-relative and exclusive.
*
* @see #getAttribute(String, String)
*/
public static final String CHAR_END= "charEnd"; //$NON-NLS-1$
/**
* Line number marker attribute. An integer value indicating the line number for a text marker.
* This attribute is 1-relative.
*
* @see #getAttribute(String, String)
*/
public static final String LINE_NUMBER= "lineNumber"; //$NON-NLS-1$
/**
* 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.
*
* @see #getAttribute(String, String)
* @since 2.1
*/
public static final String TRANSIENT= "transient"; //$NON-NLS-1$
/**
* 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 <code>true</code>. 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.
*
* @see #getAttribute(String, String)
* @since 2.1
*/
public static final String USER_EDITABLE= "userEditable"; //$NON-NLS-1$
/**
* 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.
*
* @see #getAttribute(String, String)
* @since 3.3
*/
public static final String SOURCE_ID= "sourceId"; //$NON-NLS-1$
/*====================================================================
* Marker attributes values:
*====================================================================*/
/**
* High priority constant (value 2).
*
* @see #getAttribute(String, int)
*/
public static final int PRIORITY_HIGH= 2;
/**
* Normal priority constant (value 1).
*
* @see #getAttribute(String, int)
*/
public static final int PRIORITY_NORMAL= 1;
/**
* Low priority constant (value 0).
*
* @see #getAttribute(String, int)
*/
public static final int PRIORITY_LOW= 0;
/**
* Error severity constant (value 2) indicating an error state.
*
* @see #getAttribute(String, int)
*/
public static final int SEVERITY_ERROR= 2;
/**
* Warning severity constant (value 1) indicating a warning.
*
* @see #getAttribute(String, int)
*/
public static final int SEVERITY_WARNING= 1;
/**
* Info severity constant (value 0) indicating information only.
*
* @see #getAttribute(String, int)
*/
public static final int SEVERITY_INFO= 0;
/**
* Deletes this marker from its associated resource. This method has no effect if this marker
* does not exist.
*
* @exception CoreException if this marker could not be deleted. Reasons include:
* <ul>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* </ul>
* @see IResourceRuleFactory#markerRule(IResource)
*/
public void delete() throws CoreException;
/**
* Tests this marker for equality with the given object. Two markers are equal if their id and
* resource are both equal.
*
* @param object the other object
* @return an indication of whether the objects are equal
*/
public boolean equals(Object object);
/**
* Returns whether this marker exists in the workspace. A marker exists if its resource exists
* and has a marker with the marker's id.
*
* @return <code>true</code> if this marker exists, otherwise <code>false</code>
*/
public boolean exists();
/**
* Returns the attribute with the given name. The result is an instance of one of the following
* classes: <code>String</code>, <code>Integer</code>, or <code>Boolean</code>. Returns
* <code>null</code> if the attribute is undefined.
*
* @param attributeName the name of the attribute
* @return the value, or <code>null</code> if the attribute is undefined.
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This marker does not exist.</li>
* </ul>
*/
public Object getAttribute(String attributeName) throws CoreException;
/**
* 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.
*
* @param attributeName the name of the attribute
* @param defaultValue the value to use if no value is found
* @return the value or the default value if no value was found.
*/
public int getAttribute(String attributeName, int 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.
*
* @param attributeName the name of the attribute
* @param defaultValue the value to use if no value is found
* @return the value or the default value if no value was found.
*/
public String getAttribute(String attributeName, String 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.
*
* @param attributeName the name of the attribute
* @param defaultValue the value to use if no value is found
* @return the value or the default value if no value was found.
*/
public boolean getAttribute(String attributeName, boolean defaultValue);
/**
* Returns a map with all the attributes for the marker. If the marker has no attributes then
* <code>null</code> is returned.
*
* @return a map of attribute keys and values (key type : <code>String</code> value type :
* <code>String</code>, <code>Integer</code>, or <code>Boolean</code>) or
* <code>null</code>.
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This marker does not exist.</li>
* </ul>
*/
public Map getAttributes() 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
* <code>null</code> or an instance of one of the following classes: <code>String</code>,
* <code>Integer</code>, or <code>Boolean</code>.
*
* @param attributeNames the names of the attributes
* @return the values of the given attributes.
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This marker does not exist.</li>
* </ul>
*/
public Object[] getAttributes(String[] attributeNames) throws CoreException;
/**
* Returns the time at which this marker was created.
*
* @return the difference, measured in milliseconds, between the time at which this marker was
* created and midnight, January 1, 1970 UTC, or <code>0L</code> if the creation time is
* not known (this can occur in workspaces created using v2.0 or earlier).
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This marker does not exist.</li>
* </ul>
* @since 2.1
*/
public long getCreationTime() throws CoreException;
/**
* 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.
*
* @return the id of the marker
* @see IResource#findMarker(long)
*/
public long getId();
/**
* Returns the resource with which this marker is associated.
*
* @return the resource with which this marker is associated
*/
public IResource getResource();
/**
* Returns the type of this marker. The returned marker type will not be <code>null</code>.
*
* @return the type of this marker
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This marker does not exist.</li>
* </ul>
*/
public String getType() throws CoreException;
/**
* Returns whether the type of this marker is considered to be a sub-type of the given marker
* type.
*
* @return boolean <code>true</code>if the marker's type is the same as (or a sub-type of) the
* given type.
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This marker does not exist.</li>
* </ul>
*/
public boolean isSubtypeOf(String superType) throws CoreException;
/**
* Sets the integer-valued attribute with the given name.
* <p>
* This method changes resources; these changes will be reported in a subsequent resource change
* event, including an indication that this marker has been modified.
* </p>
*
* @param attributeName the name of the attribute
* @param value the value
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This marker does not exist.</li>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* </ul>
* @see IResourceRuleFactory#markerRule(IResource)
*/
public void setAttribute(String attributeName, int value) throws CoreException;
/**
* Sets the attribute with the given name. The value must be <code>null</code> or an instance of
* one of the following classes: <code>String</code>, <code>Integer</code>, or
* <code>Boolean</code>. If the value is <code>null</code>, the attribute is considered to be
* undefined.
*
* <p>
* The attribute value cannot be <code>String</code> whose UTF encoding exceeds 65535 bytes. On
* persistent markers this limit is enforced by an assertion.
* </p>
*
* <p>
* This method changes resources; these changes will be reported in a subsequent resource change
* event, including an indication that this marker has been modified.
* </p>
*
* @param attributeName the name of the attribute
* @param value the value, or <code>null</code> if the attribute is to be undefined
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This marker does not exist.</li>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* </ul>
* @see IResourceRuleFactory#markerRule(IResource)
*/
public void setAttribute(String attributeName, Object value) throws CoreException;
/**
* Sets the boolean-valued attribute with the given name.
* <p>
* This method changes resources; these changes will be reported in a subsequent resource change
* event, including an indication that this marker has been modified.
* </p>
*
* @param attributeName the name of the attribute
* @param value the value
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This marker does not exist.</li>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* </ul>
* @see IResourceRuleFactory#markerRule(IResource)
*/
public void setAttribute(String attributeName, boolean value) throws CoreException;
/**
* Sets the given attribute key-value pairs on this marker. The values must be <code>null</code>
* or an instance of one of the following classes: <code>String</code>, <code>Integer</code>, or
* <code>Boolean</code>. If a value is <code>null</code>, the new value of the attribute is
* considered to be undefined.
*
* <p>
* The values of the attributes cannot be <code>String</code> whose UTF encoding exceeds 65535
* bytes. On persistent markers this limit is enforced by an assertion.
* </p>
*
* <p>
* This method changes resources; these changes will be reported in a subsequent resource change
* event, including an indication that this marker has been modified.
* </p>
*
* @param attributeNames an array of attribute names
* @param values an array of attribute values
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This marker does not exist.</li>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* </ul>
* @see IResourceRuleFactory#markerRule(IResource)
*/
public void setAttributes(String[] attributeNames, Object[] values) 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: <code>String</code>,
* <code>Integer</code>, or <code>Boolean</code>. Attributes previously set on the marker but
* not included in the given map are considered to be removals. Setting the given map to be
* <code>null</code> is equivalent to removing all marker attributes.
*
* <p>
* The values of the attributes cannot be <code>String</code> whose UTF encoding exceeds 65535
* bytes. On persistent markers this limit is enforced by an assertion.
* </p>
*
* <p>
* This method changes resources; these changes will be reported in a subsequent resource change
* event, including an indication that this marker has been modified.
* </p>
*
* @param attributes a map of attribute names to attribute values (key type :
* <code>String</code> value type : <code>String</code>, <code>Integer</code>, or
* <code>Boolean</code>) or <code>null</code>
* @exception CoreException if this method fails. Reasons include:
* <ul>
* <li>This marker does not exist.</li>
* <li>Resource changes are disallowed during certain types of resource change
* event notification. See <code>IResourceChangeEvent</code> for more details.</li>
* </ul>
* @see IResourceRuleFactory#markerRule(IResource)
*/
public void setAttributes(Map attributes) throws CoreException;
}