<classpathentry kind="src" path="remote"/>

package org.eclipse.cdt.core.remote;

import java.net.URI;

import org.eclipse.core.resources.IResource;

import org.eclipse.core.runtime.IPath;

import org.eclipse.core.runtime.Path;

/**

 * 

 * <p>

 * A universal representation of local and remote paths, which provides path manipulation facilities.

 * </p>

 * <p>

 * <strong>EXPERIMENTAL</strong>. 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.

 * </p>

 * <p>

 * This interface essentially bridges local paths and URIs that represent paths.

 * </p>

 * <p>

 * 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 <code>null</code> for a device id.

 * </p>

 * <p>

 * Note that paths are value objects; all operations on paths 

 * return a new path; the path that is operated on 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.

 * 

 * @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 <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(String)

	 */

	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 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.

	 * 

	 * <p>

	 * Example:

	 * </p>

	 * <p>

	 * Original path:  <code>rse://remoteMachine/home/youraccount/foo/bar.cpp</code>

	 * </p>

	 * <p>

	 * Format:  <code>Format.FORMAT_UNIX</code>

	 * </p>

	 * <p>Result: <code>/home/youraccount/foo/bar.cpp</code>

	 * </p>

	 * 

	 * Example:

	 * </p>

	 * <p>

	 * Original path:  <code>file://C%30/foo/bar.cpp</code>

	 * </p>

	 * <p>

	 * Format: <code>Format.FORMAT_WINDOWS</code>

	 * </p>  

	 * <p>Result: <code>C:\foo\bar.cpp</code>

	 * </p>

	 * 

	 * @return a <code>String</code> 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

	 * <code>null</code> if this path is not represented in the workspace.

	 * 

	 */

	public IResource getWorkspaceResource();

	/**

	 * 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.  UNC paths are always 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();

	/**

	 * @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.

	 * <p>

	 * 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.

	 * </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(IUniversalPath anotherPath);

	/**

	 * Returns whether this path is a root path.

	 * <p>

	 * The root path is the absolute non-UNC 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 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 <code>true</code> if the given string is a valid path,

	 *    and <code>false</code> 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:

	 * <ul>

	 * <li> the empty string is not valid

	 * <li> any string containing the slash character ('/') is not valid

	 * <li>any string containing segment or device separator characters

	 * on the local file system, such as the backslash ('\') and colon (':')

	 * on some file systems.

	 * </ul>

	 *

	 * @param segment the path segment to check

	 * @return <code>true</code> if the given path segment is valid,

	 *    and <code>false</code> otherwise

	 */

	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.

	 * 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 <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 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.

	 * <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 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.

	 * <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, a path with no segments is returned.

	 * </p>

	 *

	 * @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.

	 * <p>

	 * If this path does not have a trailing separator,

	 * this path is returned.

	 * </p>

	 *

	 * @return the new path

	 * @see #addTrailingSeparator()

	 * @see #hasTrailingSeparator()

	 */

	public IUniversalPath 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 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 <code>java.io.File</code> 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 <code>Path#fromPortableString(String)</code> 

	 * constructor to produce the exact same path on any platform.

	 * <p>

	 * This string is suitable for passing to <code>Path#fromPortableString(String)</code>.

	 * </p>

	 *

	 * @return a platform-neutral string representation of this path

	 * @see Path#fromPortableString(String)

	 * @since 3.1

	 */

	public String toPortableString();

	/**

	 * Returns a string representation of this path, suitable for display in the UI.

	 * 

	 * In the case of local paths, this will be a path in the local filesystem, including any device id.

	 * The scheme portion of the URI is not displayed for local files (i.e. c:/foo not file://c:/foo

	 * 

	 * For non-local files, the full URI of the file will be displayed.

	 * 

	 * @return a string representation of this path

	 */

	public String toString();

	/**

	 * Returns a string representing the path in the given format

	 * 

	 * @param format - either Format.FORMAT_UNIX or Format.FORMAT_WINDOWS

	 * @return

	 */

	public String toStringInFormat(Format format);

	/**

	 * Converts this path to a relative path in the context of the target.

	 * 

	 * <p>Example:</p>

	 * 

	 * <p>Original path:  <code>rse://remoteMachine/home/youraccount/foo/bar.cpp</code></p>

	 * 

	 * <p>pathRelativeTo:  <code>/home/yourAccount</code></p>

	 * 

	 * <p>Result:  <code>foo/bar.cpp</code></p>

	 * 

	 * @param uriRelativeTo - The URI which the path should be relative to

	 * @return A universal path relative to the given location

	 */

	public IUniversalPath toTargetRelativePath(IUniversalPath pathRelativeTo);

	/**

	 * Converts this path to a URI.  The URI may be absolute or relative depending upon whether or not the path

	 * is absolute or relative.

	 * 

	 * <p>

	 * 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., <code>C:\foo\bar</code> becomes <code>file://C%30/foo/bar</code>.

	 * </p>

	 * 

	 * <p>

	 * This will return a URI mapping to the local filesystem (file://...) if the path is local and absolute

	 * (i.e. both <code>isLocal()</code> and <code>isAbsolute()</code> return true).

	 * </p>

	 * 

	 * @return a URI representing the path, or <code>null</code> 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.

	 * <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 IUniversalPath uptoSegment(int count);

}