package org.eclipse.core.runtime; | |
/* | |
* (c) Copyright IBM Corp. 2000, 2001. | |
* All Rights Reserved. | |
*/ | |
import java.io.File; | |
/** | |
* A path is an ordered collection of string segments, | |
* separated by a standard separator character, "/". | |
* A path may also have a leading and/or a trailing separator. | |
* Paths also be prefixed by an optional device id, which includes | |
* the character(s) which separate the device id from the rest | |
* of the path. For example, "C:" and "Server/Volume:" are typical | |
* device ids. | |
* A device independent path has <code>null</code> for a device id. | |
* <p> | |
* Note that paths are value objects; all operations on paths | |
* return a new path; the receiver is unscathed. | |
* </p> | |
* <p> | |
* UNC paths are denoted by leading double-slashes such | |
* as <code>//Server/Volume/My/Path</code>. When a new path | |
* is constructed all double-slashes are removed except those | |
* appearing at the beginning of the path. | |
* </p> | |
* <p> | |
* This interface is not intended to be implemented by clients. | |
* </p> | |
* | |
* @see Path | |
*/ | |
public interface IPath extends Cloneable { | |
/** | |
* Path separator character constant "/" used in paths. | |
*/ | |
public static final char SEPARATOR = '/'; | |
/** | |
* Device separator character constant ":" used in paths. | |
*/ | |
public static final char DEVICE_SEPARATOR = ':'; | |
/** | |
* Returns a new path which is the same as this path but with | |
* the given file extension added. If this path is empty, root or has a | |
* trailing separator, this path is returned. If this path already | |
* has an extension, the existing extension is left and the given | |
* extension simply appended. Clients wishing to replace | |
* the current extension should first remove the extension and | |
* then add the desired one. | |
* <p> | |
* The file extension portion is defined as the string | |
* following the last period (".") character in the last segment. | |
* The given extension should not include a leading ".". | |
* </p> | |
* | |
* @param extension the file extension to append | |
* @return the new path | |
*/ | |
public IPath addFileExtension(String extension); | |
/** | |
* Returns a path with the same segments as this path | |
* but with a trailing separator added. | |
* This path must have at least one segment. | |
* <p> | |
* If this path already has a trailing separator, | |
* this path is returned. | |
* </p> | |
* | |
* @return the new path | |
* @see #hasTrailingSeparator | |
* @see #removeTrailingSeparator | |
*/ | |
public IPath addTrailingSeparator(); | |
/** | |
* Returns the canonicalized path obtained from the | |
* concatenation of the given string path to the | |
* end of this path. The given string path must be a valid | |
* path. If it has a trailing separator, | |
* the result will have a trailing separator. | |
* The device id of this path is preserved (the one | |
* of the given string is ignored). Duplicate slashes | |
* are removed from the path except at the beginning | |
* where the path is considered to be UNC. | |
* | |
* @param path the string path to concatenate | |
* @return the new path | |
* @see #isValidPath | |
*/ | |
public IPath append(String path); | |
/** | |
* Returns the canonicalized path obtained from the | |
* concatenation of the given path's segments to the | |
* end of this path. If the given path has a trailing | |
* separator, the result will have a trailing separator. | |
* The device id of this path is preserved (the one | |
* of the given path is ignored). Duplicate slashes | |
* are removed from the path except at the beginning | |
* where the path is considered to be UNC. | |
* | |
* @param path the path to concatenate | |
* @return the new path | |
*/ | |
public IPath append(IPath path); | |
/** | |
* Returns a copy of this path. | |
* | |
* @return the cloned path | |
*/ | |
public Object clone(); | |
/** | |
* Returns whether this path equals the given object. | |
* <p> | |
* Equality for paths is defined to be: same sequence of segments, | |
* same absolute/relative status, and same device. | |
* Trailing separators are disregarded. | |
* Paths are not generally considered equal to objects other than paths. | |
* </p> | |
* | |
* @param obj the other object | |
* @return <code>true</code> if the paths are equivalent, | |
* and <code>false</code> if they are not | |
*/ | |
public boolean equals(Object obj); | |
/** | |
* Returns the device id for this path, or <code>null</code> if this | |
* path has no device id. Note that the result will end in ':'. | |
* | |
* @return the device id, or <code>null</code> | |
* @see #setDevice | |
*/ | |
public String getDevice(); | |
/** | |
* Returns the file extension portion of this path, | |
* or <code>null</code> if there is none. | |
* <p> | |
* The file extension portion is defined as the string | |
* following the last period (".") character in the last segment. | |
* If there is no period in the last segment, the path has no | |
* file extension portion. If the last segment ends in a period, | |
* the file extension portion is the empty string. | |
* </p> | |
* | |
* @return the file extension or <code>null</code> | |
*/ | |
public String getFileExtension(); | |
/** | |
* Returns whether this path has a trailing separator. | |
* <p> | |
* Note: In the root path ("/"), the separator is considered to | |
* be leading rather than trailing. | |
* </p> | |
* | |
* @return <code>true</code> if this path has a trailing | |
* separator, and <code>false</code> otherwise | |
* @see #addTrailingSeparator | |
* @see #removeTrailingSeparator | |
*/ | |
public boolean hasTrailingSeparator(); | |
/** | |
* Returns whether this path is an absolute path (ignoring | |
* any device id). | |
* <p> | |
* Absolute paths start with a path separator. | |
* A root path, like <code>/</code> or <code>C:/</code>, | |
* is considered absolute. | |
* </p> | |
* | |
* @return <code>true</code> if this path is an absolute path, | |
* and <code>false</code> otherwise | |
*/ | |
public boolean isAbsolute(); | |
/** | |
* Returns whether this path has no segments and is not | |
* a root path. | |
* | |
* @return <code>true</code> if this path is empty, | |
* and <code>false</code> otherwise | |
*/ | |
public boolean isEmpty(); | |
/** | |
* Returns whether this path is a prefix of the given path. | |
* To be a prefix, this path's segments must | |
* appear in the argument path in the same order, | |
* and their device ids must match. | |
* <p> | |
* Modulo device ids, an empty path is a prefix of all paths; | |
* a root path is a prefix of all absolute paths. | |
* </p> | |
* | |
* @param anotherPath the other path | |
* @return <code>true</code> if this path is a prefix of the given path, | |
* and <code>false</code> otherwise | |
*/ | |
public boolean isPrefixOf(IPath anotherPath); | |
/** | |
* Returns whether this path is a root path. | |
* <p> | |
* The root path is the absolute path with zero segments; | |
* e.g., <code>/</code> or <code>C:/</code>. | |
* The separator is considered a leading separator, not a trailing one. | |
* </p> | |
* | |
* @return <code>true</code> if this path is a root path, | |
* and <code>false</code> otherwise | |
*/ | |
public boolean isRoot(); | |
/** | |
* Returns a boolean value indicating whether or not this path | |
* is considered to be in UNC form. Return false if this path | |
* has a device set or if the first 2 characters of the path string | |
* are not <code>Path.SEPARATOR</code>. | |
* | |
* @return boolean indicating if this path is UNC | |
*/ | |
public boolean isUNC(); | |
/** | |
* Returns whether the given string is syntactically correct as | |
* a path. The device id is the prefix up to and including the first ":"; | |
* the path proper is everything to the right of it, or the entire string | |
* if there is no ":". The device id is not checked for validity; | |
* the path proper is correct if each of the segments in its canonicalized | |
* form is valid. | |
* | |
* @return <code>true</code> if the given string is a valid path, | |
* and <code>false</code> otherwise | |
* @see #isValidSegment | |
*/ | |
public boolean isValidPath(String path); | |
/** | |
* Returns whether the given string is valid as a segment in | |
* a path. The rules for valid segments are as follows: | |
* <ul> | |
* <li> the empty string is not valid | |
* <li> any string containing the colon character (":") is not valid | |
* <li> any string containing the slash character ("/") is not valid | |
* <li> any string containing the backslash character ("\") is not valid | |
* <li> any string starting or ending with a whitespace character is not valid | |
* <li> all other strings are valid | |
* </ul> | |
* | |
* @param segment the path segment to check | |
* @return <code>true</code> if the given path segment is valid, | |
* and <code>false</code> otherwise | |
* @see java.lang.Character#isWhitespace | |
*/ | |
public boolean isValidSegment(String segment); | |
/** | |
* Returns the last segment of this path, or | |
* <code>null</code> if it does not have any segments. | |
* | |
* @return the last segment of this path, or <code>null</code> | |
*/ | |
public String lastSegment(); | |
/** | |
* Returns an absolute path with the segments and device id of this path. | |
* If this path is absolute, it is simply returned. | |
* | |
* @return the new path | |
*/ | |
public IPath makeAbsolute(); | |
/** | |
* Returns a relative path with the segments and device id of this path. | |
* If this path is relative, it is simply returned. | |
* | |
* @return the new path | |
*/ | |
public IPath makeRelative(); | |
/** | |
* Return a new path which is the equivalent of this path converted to UNC | |
* form (if the given boolean is true) or this path not as a UNC path (if the given | |
* boolean is false). If UNC, the returned path will not have a device and the | |
* first 2 characters of the path string will be <code>Path.SEPARATOR</code>. If not UNC, the | |
* first 2 characters of the returned path string will not be <code>Path.SEPARATOR</code>. | |
* | |
* @param toUNC true if converting to UNC, false otherwise | |
* @return the new path, either in UNC form or not depending on the boolean parm | |
*/ | |
public IPath makeUNC(boolean toUNC); | |
/** | |
* Returns a count of the number of segments which match in | |
* this path and the given path (device ids are ignored), | |
* comparing in increasing segment number order. | |
* | |
* @param anotherPath the other path | |
* @return the number of matching segments | |
*/ | |
public int matchingFirstSegments(IPath anotherPath); | |
/** | |
* Returns a new path which is the same as this path but with | |
* the file extension removed. If this path does not have an | |
* extension, this path is returned. | |
* <p> | |
* The file extension portion is defined as the string | |
* following the last period (".") character in the last segment. | |
* If there is no period in the last segment, the path has no | |
* file extension portion. If the last segment ends in a period, | |
* the file extension portion is the empty string. | |
* </p> | |
* | |
* @return the new path | |
*/ | |
public IPath removeFileExtension(); | |
/** | |
* Returns a copy of this path with the given number of segments | |
* removed from the beginning. The device id is preserved. | |
* The number must be greater or equal zero. | |
* If the count is zero, this path is returned. | |
* The resulting path will always be a relative path with respect | |
* to this path. If the number equals or exceeds the number | |
* of segments in this path, an empty relative path is returned. | |
* | |
* @return the new path | |
*/ | |
public IPath removeFirstSegments(int count); | |
/** | |
* Returns a copy of this path with the given number of segments | |
* removed from the end. The device id is preserved. | |
* The number must be greater or equal zero. | |
* If the count is zero, this path is returned. | |
* <p> | |
* If this path has a trailing separator, it will still | |
* have a trailing separator after the last segments are removed | |
* (assuming there are some segments left). If there is no | |
* trailing separator, the result will not have a trailing | |
* separator. | |
* If the number equals or exceeds the number | |
* of segments in this path, an empty path is returned. | |
* </p> | |
* | |
* @return the new path | |
*/ | |
public IPath removeLastSegments(int count); | |
/** | |
* Returns a path with the same segments as this path | |
* but with a trailing separator removed. | |
* Does nothing if this path does not have at least one segment. | |
* The device id is preserved. | |
* <p> | |
* If this path does not have a trailing separator, | |
* this path is returned. | |
* </p> | |
* | |
* @return the new path | |
* @see #addTrailingSeparator | |
* @see #hasTrailingSeparator | |
*/ | |
public IPath removeTrailingSeparator(); | |
/** | |
* Returns the specified segment of this path, or | |
* <code>null</code> if the path does not have such a segment. | |
* | |
* @param index the 0-based segment index | |
* @return the specified segment, or <code>null</code> | |
*/ | |
public String segment(int index); | |
/** | |
* Returns the number of segments in this path. | |
* <p> | |
* Note that both root and empty paths have 0 segments. | |
* </p> | |
* | |
* @return the number of segments | |
*/ | |
public int segmentCount(); | |
/** | |
* Returns the segments in this path in order. | |
* | |
* @return an array of string segments | |
*/ | |
public String[] segments(); | |
/** | |
* Returns a new path which is the same as this path but with | |
* the given device id. The device id must end with a ":". | |
* A device independent path is obtained by passing <code>null</code>. | |
* <p> | |
* For example, "C:" and "Server/Volume:" are typical device ids. | |
* </p> | |
* | |
* @param device the device id or <code>null</code> | |
* @return a new path | |
* @see #getDevice | |
*/ | |
public IPath setDevice(String device); | |
/** | |
* Returns a <code>java.io.File</code> corresponding to this path. | |
* | |
* @return the file corresponding to this path | |
*/ | |
public java.io.File toFile(); | |
/** | |
* Returns a string representation of this path which uses the | |
* platform-dependent path separator defined by <code>java.io.File</code>. | |
* This method is like <code>toString()</code> except that the | |
* latter always uses the same separator (<code>/</code>) regardless of platform. | |
* <p> | |
* This string is suitable for passing to <code>java.io.File(String)</code>. | |
* </p> | |
* | |
* @return a platform-dependent string representation of this path | |
*/ | |
public String toOSString(); | |
/** | |
* Returns a string representation of this path, including its | |
* device id. The same separator, "/", is used on all platforms. | |
* <p> | |
* Example result strings (without and with device id): | |
* <pre> | |
* "/foo/bar.txt" | |
* "bar.txt" | |
* "/foo/" | |
* "foo/" | |
* "" | |
* "/" | |
* "C:/foo/bar.txt" | |
* "C:bar.txt" | |
* "C:/foo/" | |
* "C:foo/" | |
* "C:" | |
* "C:/" | |
* </pre> | |
* This string is suitable for passing to <code>Path(String)</code>. | |
* </p> | |
* | |
* @return a string representation of this path | |
* @see Path | |
*/ | |
public String toString(); | |
/** | |
* Returns a copy of this path truncated after the | |
* given number of segments. The number must not be negative. | |
* The device id is preserved. | |
* <p> | |
* If this path has a trailing separator, the result will too | |
* (assuming there are some segments left). If there is no | |
* trailing separator, the result will not have a trailing | |
* separator. | |
* Copying up to segment zero simply means making an copy with | |
* no path segments. | |
* </p> | |
* | |
* @param count the segment number at which to truncate the path | |
* @return the new path | |
*/ | |
public IPath uptoSegment(int count); | |
} |