+ * A universal representation of local and remote paths, which provides path manipulation facilities. + *
+ *+ * EXPERIMENTAL. This class or interface has been added as + * part of a work in progress. There is no guarantee that this API will work or + * that it will remain the same. Please do not use this API without consulting + * with the author. + *
+ *+ * This interface essentially bridges local paths and URIs that represent paths. + *
+ *
+ * A path is an ordered collection of string segments, separated by a separator character
+ * (either a forward slash or a backslash depending upon the path format).
+ * A path may also have a leading and/or a trailing separator.
+ * Paths may 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 null for a device id.
+ *
+ * Note that paths are value objects; all operations on paths + * return a new path; the path that is operated on is unscathed. + *
+ *
+ * UNC paths are denoted by leading double-slashes such
+ * as //Server/Volume/My/Path. When a new path
+ * is constructed all double-slashes are removed except those
+ * appearing at the beginning of the path.
+ *
+ * @author crecoskie
+ * @see java.net.URI
+ *
+ */
+public interface IUniversalPath {
+
+ /**
+ * Encapsulates possible formats for paths. Paths can be either UNIX or Windows format.
+ *
+ */
+ public enum Format {
+ /**
+ * Constant indicating that this path is in UNIX format. I.e., it has no device id, and
+ * the path separator is the forward slash character.
+ */
+ FORMAT_UNIX,
+
+ /**
+ * Constant indicating that this path is in Windows format. I.e., it can have a device id, and
+ * the path separator is the backslash character.
+ */
+ FORMAT_WINDOWS
+ }
+
+ /**
+ * 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 IUniversalPath append(IUniversalPath tail);
+
+ /**
+ * 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(String)
+ */
+ public IUniversalPath append(String path);
+
+ /**
+ * Returns the device id for this path, or null if this
+ * path has no device id. Note that the result will end in ':'.
+ *
+ * @return the device id, or null
+ * @see #setDevice(String)
+ */
+ public String getDevice();
+
+ /**
+ * Returns the file extension portion of this path,
+ * or null if there is none.
+ *
+ * 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. + *
+ * + * @return the file extension ornull
+ */
+ public String getFileExtension();
+
+ /**
+ * Returns the format for native paths on the local machine.
+ *
+ * @return Format.FORMAT_WINDOWS if native paths are in Windows format, Format.FORMAT_UNIX otherwise
+ */
+ public Format getLocalPathFormat();
+
+
+ /**
+ * Returns the format of this path as it would be represented on the targeted machine.
+ * The targeted machine might be local or remote.
+ *
+ * @return Format.FORMAT_WINDOWS if this path represents a Windows path, Format.FORMAT_UNIX otherwise.
+ */
+ public Format getTargetPathFormat();
+
+
+ /**
+ * Gets only the filesystem specific part of the path, in the context of the target.
+ * The target's path format is used to format the string.
+ *
+ * + * Example: + *
+ *
+ * Original path: rse://remoteMachine/home/youraccount/foo/bar.cpp
+ *
+ * Format: Format.FORMAT_UNIX
+ *
Result: /home/youraccount/foo/bar.cpp
+ *
+ * Original path: file://C%30/foo/bar.cpp
+ *
+ * Format: Format.FORMAT_WINDOWS
+ *
Result: C:\foo\bar.cpp
+ *
String corresponding to the target path
+ */
+ public String getTargetPathString();
+
+ /**
+ * Gets the path relative to the workspace.
+ *
+ * @return an IResource corresponding to the path's location in the workspace, or
+ * null if this path is not represented in the workspace.
+ *
+ */
+ public IResource getWorkspaceResource();
+
+ /**
+ * Returns whether this path has a trailing separator.
+ * + * Note: In the root path ("/"), the separator is considered to + * be leading rather than trailing. + *
+ * + * @returntrue if this path has a trailing
+ * separator, and false otherwise
+ * @see #addTrailingSeparator()
+ * @see #removeTrailingSeparator()
+ */
+ public boolean hasTrailingSeparator();
+
+
+ /**
+ * Returns whether this path is an absolute path (ignoring
+ * any device id).
+ *
+ * Absolute paths start with a path separator.
+ * A root path, like / or C:/,
+ * is considered absolute. UNC paths are always absolute.
+ *
true if this path is an absolute path,
+ * and false otherwise
+ */
+ public boolean isAbsolute();
+
+ /**
+ * Returns whether this path has no segments and is not
+ * a root path.
+ *
+ * @return true if this path is empty,
+ * and false otherwise
+ */
+ public boolean isEmpty();
+
+ /**
+ * @return true if the path corresponds to the local machine's native filesystem, false otherwise.
+ */
+ public boolean isLocal();
+
+ /**
+ * 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.
+ * + * An empty path is a prefix of all paths with the same device; a root path is a prefix of + * all absolute paths with the same device. + *
+ * @param anotherPath the other path + * @returntrue if this path is a prefix of the given path,
+ * and false otherwise
+ */
+ public boolean isPrefixOf(IUniversalPath anotherPath);
+
+ /**
+ * Returns whether this path is a root path.
+ *
+ * The root path is the absolute non-UNC path with zero segments;
+ * e.g., / or C:/.
+ * The separator is considered a leading separator, not a trailing one.
+ *
true if this path is a root path,
+ * and false 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 Path.SEPARATOR.
+ *
+ * @return boolean indicating if this path is UNC
+ */
+ public boolean isUNC();
+
+ /**
+ * Returns whether the given string is syntactically correct as
+ * a universal path.
+ *
+ *
+ * The device id is the prefix up to and including the device
+ * separator for the local file system; the path proper is everything to
+ * the right of it, or the entire string if there is no device separator.
+ * When the platform location is a file system with no meaningful device
+ * separator, the entire string is treated as the path proper.
+ * The device id is not checked for validity; the path proper is correct
+ * if each of the segments in its canonicalized form is valid.
+ *
+ * @param path the path to check
+ * @return true if the given string is a valid path,
+ * and false otherwise
+ * @see #isValidSegment(String)
+ */
+ 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:
+ * true if the given path segment is valid,
+ * and false otherwise
+ */
+ public boolean isValidSegment(String segment);
+
+ /**
+ * Returns the last segment of this path, or
+ * null if it does not have any segments.
+ *
+ * @return the last segment of this path, or null
+ */
+ public String lastSegment();
+
+ /**
+ * Returns an absolute path with the segments and device id of this path.
+ * Absolute paths start with a path separator. If this path is absolute,
+ * it is simply returned.
+ *
+ * @return the new path
+ */
+ public IUniversalPath makeAbsolute();
+
+ /**
+ * Returns a relative path with the segments and device id of this path.
+ * Absolute paths start with a path separator and relative paths do not.
+ * If this path is relative, it is simply returned.
+ *
+ * @return the new path
+ */
+ public IUniversalPath 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 Path.SEPARATOR. If not UNC, the
+ * first 2 characters of the returned path string will not be Path.SEPARATOR.
+ *
+ * @param toUNC true if converting to UNC, false otherwise
+ * @return the new path, either in UNC form or not depending on the boolean parameter
+ */
+ public IUniversalPath 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(IUniversalPath 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.
+ * + * 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. + *
+ * + * @return the new path + */ + public IUniversalPath 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. + * + * @param count the number of segments to remove + * @return the new path + */ + public IUniversalPath 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. + *+ * 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, a path with no segments is returned. + *
+ * + * @param count the number of segments to remove + * @return the new path + */ + public IUniversalPath 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. + *+ * If this path does not have a trailing separator, + * this path is returned. + *
+ * + * @return the new path + * @see #addTrailingSeparator() + * @see #hasTrailingSeparator() + */ + public IUniversalPath removeTrailingSeparator(); + + /** + * Returns the specified segment of this path, or + *null if the path does not have such a segment.
+ *
+ * @param index the 0-based segment index
+ * @return the specified segment, or null
+ */
+ public String segment(int index);
+
+ /**
+ * Returns the number of segments in this path.
+ * + * Note that both root and empty paths have 0 segments. + *
+ * + * @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 passingnull.
+ * + * For example, "C:" and "Server/Volume:" are typical device ids. + *
+ * + * @param device the device id ornull
+ * @return a new path
+ * @see #getDevice()
+ */
+ public IUniversalPath setDevice(String device);
+
+ /**
+ * Sets the format of this path as it would be represented on the targeted machine.
+ * The targeted machine might be local or remote.
+ *
+ * @param format - Format of the path
+ * @return a new universal path with the specified format.
+ */
+ public IUniversalPath setTargetPathFormat(Format format);
+
+ /**
+ * Sets up a mapping between this path and a path in the workspace. This does not in any way
+ * setup a link in the workspace itself or otherwise indicate to any of the workspace's resource
+ * management facilities that such a mapping exists.
+ *
+ * @param resource - the resource in the workspace to map to.
+ * @return a new path with the appropriate mapping set.
+ */
+ public IUniversalPath setWorkspaceResource(IResource resource);
+
+ /**
+ * Returns a string representation of this path which uses the
+ * platform-dependent path separator defined by java.io.File corresponding
+ * to the local execution environment.
+ * @return a platform-dependent string representation of this path
+ */
+ public String toOSString();
+
+
+ /**
+ * Returns a platform-neutral string representation of this path. The
+ * format is not specified, except that the resulting string can be
+ * passed back to the Path#fromPortableString(String)
+ * constructor to produce the exact same path on any platform.
+ *
+ * This string is suitable for passing to Path#fromPortableString(String).
+ *
Example:
+ * + *Original path: rse://remoteMachine/home/youraccount/foo/bar.cpp
pathRelativeTo: /home/yourAccount
Result: foo/bar.cpp
+ * In the case of local paths, path separators are converted to URI format (forward slashes),
+ * but any other characters which are not legally allowed in the path portion of the URI are escaped.
+ * E.g., in the case of paths targeting Windows systems, the URI may potentially contain an escaped colon
+ * corresponding to the device id. E.g., C:\foo\bar becomes file://C%30/foo/bar.
+ *
+ * This will return a URI mapping to the local filesystem (file://...) if the path is local and absolute
+ * (i.e. both isLocal() and isAbsolute() return true).
+ *
null if the path is empty.
+ *
+ */
+ public URI toURI();
+
+ /**
+ * Returns a copy of this path truncated after the
+ * given number of segments. The number must not be negative.
+ * The device id is preserved.
+ * + * 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. + *
+ * + * @param count the segment number at which to truncate the path + * @return the new path + */ + public IUniversalPath uptoSegment(int count); + +}