org.eclipse.platform/org.eclipse.core.resources/3.13.600 : org/eclipse/core/resources/IPathVariableManager.java

IPathVariableManager
http://www.eclipse.org/platform: Core Resource Management (Eclipse Foundation)
Eclipse Public License - v 2.0
 Copyright (c) 2000, 2015 IBM Corporation and others.
 This program and the accompanying materials
 are made available under the terms of the Eclipse Public License 2.0
 which accompanies this distribution, and is available at
 https://www.eclipse.org/legal/epl-2.0/
 SPDX-License-Identifier: EPL-2.0
 Contributors:
    IBM Corporation - initial API and implementation
    Serge Beauchamp (Freescale Semiconductor) - [229633] Project Path Variable Support
/*******************************************************************************
 *  Copyright (c) 2000, 2015 IBM Corporation and others.
 *
 *  This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License 2.0
 *  which accompanies this distribution, and is available at
 *  https://www.eclipse.org/legal/epl-2.0/
 *
 *  SPDX-License-Identifier: EPL-2.0
 *
 *  Contributors:
 *     IBM Corporation - initial API and implementation
 *     Serge Beauchamp (Freescale Semiconductor) - [229633] Project Path Variable Support
 *******************************************************************************/

package org.eclipse.core.resources;

import java.net.URI;
import org.eclipse.core.runtime.*;

Manages a collection of path variables and resolves paths containing a
variable reference.

A path variable is a pair of non-null elements (name,value) where name is
a case-sensitive string (containing only letters, digits and the underscore
character, and not starting with a digit), and value is an absolute
IPath object.


Path variables allow for the creation of relative paths whose exact
location in the file system depends on the value of a variable. A variable
reference may only appear as the first segment of a relative path.

See Also: IPath
Since: 2.1
@noimplement This interface is not intended to be implemented by clients.
@noextend This interface is not intended to be extended by clients./**
 * Manages a collection of path variables and resolves paths containing a
 * variable reference.
 * <p>
 * A path variable is a pair of non-null elements (name,value) where name is
 * a case-sensitive string (containing only letters, digits and the underscore
 * character, and not starting with a digit), and value is an absolute
 * <code>IPath</code> object.
 * </p>
 * <p>
 * Path variables allow for the creation of relative paths whose exact
 * location in the file system depends on the value of a variable. A variable
 * reference may only appear as the first segment of a relative path.
 * </p>
 *
 * @see org.eclipse.core.runtime.IPath
 * @since 2.1
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
public interface IPathVariableManager {

	Converts an absolute path to path relative to some defined
variable. For example, converts "C:/foo/bar.txt" into "FOO/bar.txt",
granted that the path variable "FOO" value is "C:/foo".

The "force" argument will cause an intermediate path variable to be created if
the given path can be relative only to a parent of an existing path variable.
For example, if the path "C:/other/file.txt" is to be converted
and no path variables point to "C:/" or "C:/other" but "FOO"
points to "C:/foo", an intermediate "OTHER" variable will be
created relative to "FOO" containing the value "${PARENT-1-FOO}"
so that the final path returned will be "OTHER/file.txt".


The argument "variableHint" can be used to specify the name of the path
variable to make the provided path relative to.

Params: path –  The absolute path to be converted
force – indicates whether intermediate path variables should be created
if the path is relative only to a parent of an existing path variable.
variableHint – The name of the variable to which the path should be made
relative to, or null for the nearest one.
Throws: CoreException – if this method fails. Reasons include:

The variable name is not valid
Returns: The converted path
Since: 3.6/**
	 * Converts an absolute path to path relative to some defined
	 * variable. For example, converts "C:/foo/bar.txt" into "FOO/bar.txt",
	 * granted that the path variable "FOO" value is "C:/foo".
	 * <p>
	 * The "force" argument will cause an intermediate path variable to be created if
	 * the given path can be relative only to a parent of an existing path variable.
	 * For example, if the path "C:/other/file.txt" is to be converted
	 * and no path variables point to "C:/" or "C:/other" but "FOO"
	 * points to "C:/foo", an intermediate "OTHER" variable will be
	 * created relative to "FOO" containing the value "${PARENT-1-FOO}"
	 * so that the final path returned will be "OTHER/file.txt".
	 * </p>
	 * <p>
	 * The argument "variableHint" can be used to specify the name of the path
	 * variable to make the provided path relative to.
	 * </p>
	 *
	 * @param path  The absolute path to be converted
	 * @param force indicates whether intermediate path variables should be created
	 * if the path is relative only to a parent of an existing path variable.
	 * @param variableHint The name of the variable to which the path should be made
	 * relative to, or <code>null</code> for the nearest one.
	 * @return The converted path
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li>The variable name is not valid</li>
	 * </ul>
	 * @since 3.6
	 */
	URI convertToRelative(URI path, boolean force, String variableHint) throws CoreException;

	Sets the path variable with the given name to be the specified value.
Depending on the value given and if the variable is currently defined
or not, there are several possible outcomes for this operation:

A new variable will be created, if there is no variable defined with
the given name, and the given value is not null.

The referred variable's value will be changed, if it already exists
and the given value is not null.
The referred variable will be removed, if a variable with the given
name is currently defined and the given value is null.

The call will be ignored, if a variable with the given name is not
currently defined and the given value is null, or if it is
defined but the given value is equal to its current value.


If a variable is effectively changed, created or removed by a call to
this method, notification will be sent to all registered listeners.
Params: name – the name of the variable
value – the value for the variable (may be null)
Throws: CoreException – if this method fails. Reasons include:

The variable name is not valid
The variable value is relative
Deprecated: use setURIValue(String, URI) instead./**
	 * Sets the path variable with the given name to be the specified value.
	 * Depending on the value given and if the variable is currently defined
	 * or not, there are several possible outcomes for this operation:
	 * <ul>
	 * <li>A new variable will be created, if there is no variable defined with
	 * the given name, and the given value is not <code>null</code>.
	 * </li>
	 *
	 * <li>The referred variable's value will be changed, if it already exists
	 * and the given value is not <code>null</code>.</li>
	 *
	 * <li>The referred variable will be removed, if a variable with the given
	 * name is currently defined and the given value is <code>null</code>.
	 * </li>
	 *
	 * <li>The call will be ignored, if a variable with the given name is not
	 * currently defined and the given value is <code>null</code>, or if it is
	 * defined but the given value is equal to its current value.
	 * </li>
	 * </ul>
	 * <p>If a variable is effectively changed, created or removed by a call to
	 * this method, notification will be sent to all registered listeners.</p>
	 *
	 * @param name the name of the variable
	 * @param value the value for the variable (may be <code>null</code>)
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li>The variable name is not valid</li>
	 * <li>The variable value is relative</li>
	 * </ul>
	 * @deprecated use {@link #setURIValue(String, URI)} instead.
	 */
	@Deprecated
	void setValue(String name, IPath value) throws CoreException;

	Sets the path variable with the given name to be the specified value.
Depending on the value given and if the variable is currently defined
or not, there are several possible outcomes for this operation:

A new variable will be created, if there is no variable defined with
the given name, and the given value is not null.

The referred variable's value will be changed, if it already exists
and the given value is not null.
The referred variable will be removed, if a variable with the given
name is currently defined and the given value is null.

The call will be ignored, if a variable with the given name is not
currently defined and the given value is null, or if it is
defined but the given value is equal to its current value.


If a variable is effectively changed, created or removed by a call to
this method, notification will be sent to all registered listeners.
Params: name – the name of the variable
value – the value for the variable (may be null)
Throws: CoreException – if this method fails. Reasons include:

The variable name is not valid
The variable value is relative
Since: 3.6/**
	 * Sets the path variable with the given name to be the specified value.
	 * Depending on the value given and if the variable is currently defined
	 * or not, there are several possible outcomes for this operation:
	 * <ul>
	 * <li>A new variable will be created, if there is no variable defined with
	 * the given name, and the given value is not <code>null</code>.
	 * </li>
	 *
	 * <li>The referred variable's value will be changed, if it already exists
	 * and the given value is not <code>null</code>.</li>
	 *
	 * <li>The referred variable will be removed, if a variable with the given
	 * name is currently defined and the given value is <code>null</code>.
	 * </li>
	 *
	 * <li>The call will be ignored, if a variable with the given name is not
	 * currently defined and the given value is <code>null</code>, or if it is
	 * defined but the given value is equal to its current value.
	 * </li>
	 * </ul>
	 * <p>If a variable is effectively changed, created or removed by a call to
	 * this method, notification will be sent to all registered listeners.</p>
	 *
	 * @param name the name of the variable
	 * @param value the value for the variable (may be <code>null</code>)
	 * @exception CoreException if this method fails. Reasons include:
	 * <ul>
	 * <li>The variable name is not valid</li>
	 * <li>The variable value is relative</li>
	 * </ul>
	 * @since 3.6
	 */
	void setURIValue(String name, URI value) throws CoreException;

	Returns the value of the path variable with the given name. If there is
no variable defined with the given name, returns null.
Params: name – the name of the variable to return the value for
Returns: the value for the variable, or null if there is no
   variable defined with the given name
Deprecated: use getURIValue(String) instead./**
	 * Returns the value of the path variable with the given name. If there is
	 * no variable defined with the given name, returns <code>null</code>.
	 *
	 * @param name the name of the variable to return the value for
	 * @return the value for the variable, or <code>null</code> if there is no
	 *    variable defined with the given name
	 * @deprecated use {@link #getURIValue(String)} instead.
	 */
	@Deprecated
	IPath getValue(String name);

	Returns the value of the path variable with the given name. If there is
no variable defined with the given name, returns null.
Params: name – the name of the variable to return the value for
Returns: the value for the variable, or null if there is no
   variable defined with the given name
Since: 3.6/**
	 * Returns the value of the path variable with the given name. If there is
	 * no variable defined with the given name, returns <code>null</code>.
	 *
	 * @param name the name of the variable to return the value for
	 * @return the value for the variable, or <code>null</code> if there is no
	 *    variable defined with the given name
	 * @since 3.6
	 */
	URI getURIValue(String name);

	Returns an array containing all defined path variable names.
Returns: an array containing all defined path variable names/**
	 * Returns an array containing all defined path variable names.
	 *
	 * @return an array containing all defined path variable names
	 */
	String[] getPathVariableNames();

	//	Should be added for 3.6
	//	public String[] getPathVariableNames(String name);

	Registers the given listener to receive notification of changes to path
variables. The listener will be notified whenever a variable has been
added, removed or had its value changed. Has no effect if an identical
path variable change listener is already registered.
Params: listener – the listener
See Also: IPathVariableChangeListener/**
	 * Registers the given listener to receive notification of changes to path
	 * variables. The listener will be notified whenever a variable has been
	 * added, removed or had its value changed. Has no effect if an identical
	 * path variable change listener is already registered.
	 *
	 * @param listener the listener
	 * @see IPathVariableChangeListener
	 */
	void addChangeListener(IPathVariableChangeListener listener);

	Removes the given path variable change listener from the listeners list.
Has no effect if an identical listener is not registered.
Params: listener – the listener
See Also: IPathVariableChangeListener/**
	 * Removes the given path variable change listener from the listeners list.
	 * Has no effect if an identical listener is not registered.
	 *
	 * @param listener the listener
	 * @see IPathVariableChangeListener
	 */
	void removeChangeListener(IPathVariableChangeListener listener);

	Resolves a relative URI object potentially containing a
variable reference as its first segment, replacing the variable reference
(if any) with the variable's value (which is a concrete absolute URI).
If the given URI is absolute or has a non- null device then
no variable substitution is done and that URI is returned as is.  If the
given URI is relative and has a null device, but the first
segment does not correspond to a defined variable, then the URI is
returned as is.

If the given URI is null then null will be
returned.  In all other cases the result will be non-null.

Params: uri –  the URI to be resolved
Returns: the resolved URI or null
Since: 3.2/**
	 * Resolves a relative <code>URI</code> object potentially containing a
	 * variable reference as its first segment, replacing the variable reference
	 * (if any) with the variable's value (which is a concrete absolute URI).
	 * If the given URI is absolute or has a non- <code>null</code> device then
	 * no variable substitution is done and that URI is returned as is.  If the
	 * given URI is relative and has a <code>null</code> device, but the first
	 * segment does not correspond to a defined variable, then the URI is
	 * returned as is.
	 * <p>
	 * If the given URI is <code>null</code> then <code>null</code> will be
	 * returned.  In all other cases the result will be non-<code>null</code>.
	 * </p>
	 *
	 * @param uri  the URI to be resolved
	 * @return the resolved URI or <code>null</code>
	 * @since 3.2
	 */
	URI resolveURI(URI uri);

	Resolves a relative IPath object potentially containing a
variable reference as its first segment, replacing the variable reference
(if any) with the variable's value (which is a concrete absolute path).
If the given path is absolute or has a non- null device then
no variable substitution is done and that path is returned as is.  If the
given path is relative and has a null device, but the first
segment does not correspond to a defined variable, then the path is
returned as is.

If the given path is null then null will be
returned.  In all other cases the result will be non-null.


For example, consider the following collection of path variables:


TEMP = c:/temp
BACKUP = /tmp/backup

The following paths would be resolved as:
c:/bin => c:/bin
c:TEMP => c:TEMP
/TEMP => /TEMP
TEMP  => c:/temp
TEMP/foo  => c:/temp/foo
BACKUP  => /tmp/backup
BACKUP/bar.txt  => /tmp/backup/bar.txt
SOMEPATH/foo => SOMEPATH/foo
Params: path – the path to be resolved
Returns: the resolved path or null
Deprecated: use resolveURI(URI) instead./**
	 * Resolves a relative <code>IPath</code> object potentially containing a
	 * variable reference as its first segment, replacing the variable reference
	 * (if any) with the variable's value (which is a concrete absolute path).
	 * If the given path is absolute or has a non- <code>null</code> device then
	 * no variable substitution is done and that path is returned as is.  If the
	 * given path is relative and has a <code>null</code> device, but the first
	 * segment does not correspond to a defined variable, then the path is
	 * returned as is.
	 * <p>
	 * If the given path is <code>null</code> then <code>null</code> will be
	 * returned.  In all other cases the result will be non-<code>null</code>.
	 * </p>
	 *
	 * <p>
	 * For example, consider the following collection of path variables:
	 * </p>
	 * <ul>
	 * <li>TEMP = c:/temp</li>
	 * <li>BACKUP = /tmp/backup</li>
	 * </ul>
	 * <p>The following paths would be resolved as:
	 * <p>c:/bin =&gt; c:/bin</p>
	 * <p>c:TEMP =&gt; c:TEMP</p>
	 * <p>/TEMP =&gt; /TEMP</p>
	 * <p>TEMP  =&gt; c:/temp</p>
	 * <p>TEMP/foo  =&gt; c:/temp/foo</p>
	 * <p>BACKUP  =&gt; /tmp/backup</p>
	 * <p>BACKUP/bar.txt  =&gt; /tmp/backup/bar.txt</p>
	 * <p>SOMEPATH/foo =&gt; SOMEPATH/foo</p>
	 *
	 * @param path the path to be resolved
	 * @return the resolved path or <code>null</code>
	 * @deprecated use {@link #resolveURI(URI)} instead.
	 */
	@Deprecated
	IPath resolvePath(IPath path);

	Returns true if the given variable is defined and
false otherwise. Returns false if the given
name is not a valid path variable name.
Params: name – the variable's name
Returns: true if the variable exists, false
   otherwise/**
	 * Returns <code>true</code> if the given variable is defined and
	 * <code>false</code> otherwise. Returns <code>false</code> if the given
	 * name is not a valid path variable name.
	 *
	 * @param name the variable's name
	 * @return <code>true</code> if the variable exists, <code>false</code>
	 *    otherwise
	 */
	boolean isDefined(String name);

	Returns whether a variable is user defined or not.
Returns: true if the path is user defined.
Since: 3.6/**
	 * Returns whether a variable is user defined or not.
	 *
	 * @return true if the path is user defined.
	 * @since 3.6
	 */
	boolean isUserDefined(String name);

	Validates the given name as the name for a path variable. A valid path
variable name is made exclusively of letters, digits and the underscore
character, and does not start with a digit.
Params: name – a possibly valid path variable name
See Also: IStatus.OK
Returns: a status object with code IStatus.OK if
   the given name is a valid path variable name, otherwise a status
   object indicating what is wrong with the string/**
	 * Validates the given name as the name for a path variable. A valid path
	 * variable name is made exclusively of letters, digits and the underscore
	 * character, and does not start with a digit.
	 *
	 * @param name a possibly valid path variable name
	 * @return a status object with code <code>IStatus.OK</code> if
	 *    the given name is a valid path variable name, otherwise a status
	 *    object indicating what is wrong with the string
	 * @see IStatus#OK
	 */
	IStatus validateName(String name);

	Validates the given path as the value for a path variable. A path
variable value must be a valid path that is absolute.
Params: path – a possibly valid path variable value
See Also: IPath.isValidPath(String)
IStatus.OK
Returns: a status object with code IStatus.OK if the given
path is a valid path variable value, otherwise a status object indicating
what is wrong with the value/**
	 * Validates the given path as the value for a path variable. A path
	 * variable value must be a valid path that is absolute.
	 *
	 * @param path a possibly valid path variable value
	 * @return a status object with code <code>IStatus.OK</code> if the given
	 * path is a valid path variable value, otherwise a status object indicating
	 * what is wrong with the value
	 * @see IPath#isValidPath(String)
	 * @see IStatus#OK
	 */
	IStatus validateValue(IPath path);

	Validates the given path as the value for a path variable. A path
variable value must be a valid path that is absolute.
Params: path – a possibly valid path variable value
See Also: IPath.isValidPath(String)
IStatus.OK
Returns: a status object with code IStatus.OK if the given path is a valid path variable value, otherwise a status object indicating what is wrong with the value
Since: 3.6/**
	 * Validates the given path as the value for a path variable. A path
	 * variable value must be a valid path that is absolute.
	 *
	 * @param path a possibly valid path variable value
	 * @return a status object with code {@link IStatus#OK} if the given
	 * path is a valid path variable value, otherwise a status object indicating
	 * what is wrong with the value
	 * @see IPath#isValidPath(String)
	 * @see IStatus#OK
	 * @since 3.6
	 */
	IStatus validateValue(URI path);

	Returns a variable relative path equivalent to an absolute path for a
file or folder in the file system, according to the variables defined in
this project PathVariableManager. The file or folder need not to exist.
Params: location – 
           a path in the local file system
Returns: the corresponding variable relative path, or null
        if no such path is available
Since: 3.6/**
	 * Returns a variable relative path equivalent to an absolute path for a
	 * file or folder in the file system, according to the variables defined in
	 * this project PathVariableManager. The file or folder need not to exist.
	 *
	 * @param location
	 *            a path in the local file system
	 * @return the corresponding variable relative path, or <code>null</code>
	 *         if no such path is available
	 * @since 3.6
	 */
	URI getVariableRelativePathLocation(URI location);

	Converts the internal format of the linked resource location if the PARENT
variables is used.  For example, if the value is "${PARENT-2-VAR}\foo", the
converted result is "${VAR}\..\..\foo".
Params: value – the value encoded using OS string (as returned from Path.toOSString())
locationFormat – indicates whether the value contains a string that is stored in the linked resource location rather than in the path variable value
Returns: the converted path variable value
Since: 3.6/**
	 * Converts the internal format of the linked resource location if the PARENT
	 * variables is used.  For example, if the value is "${PARENT-2-VAR}\foo", the
	 * converted result is "${VAR}\..\..\foo".
	 * @param value the value encoded using OS string (as returned from Path.toOSString())
	 * @param locationFormat indicates whether the value contains a string that is stored in the linked resource location rather than in the path variable value
	 * @return the converted path variable value
	 * @since 3.6
	 */
	String convertToUserEditableFormat(String value, boolean locationFormat);

	Converts the user editable format to the internal format.
For example, if the value is "${VAR}\..\..\foo", the
converted result is "${PARENT-2-VAR}\foo".
If the string is not directly convertible to a ${PARENT-COUNT-VAR}
syntax (for example, the editable string "${FOO}bar\..\..\"), intermediate
path variables will be created.
Params: value – the value encoded using OS string (as returned from Path.toOSString())
locationFormat – indicates whether the value contains a string that is stored in the linked resource location rather than in the path variable value
Returns: the converted path variable value
Since: 3.6/**
	 * Converts the user editable format to the internal format.
	 * For example, if the value is "${VAR}\..\..\foo", the
	 * converted result is "${PARENT-2-VAR}\foo".
	 * If the string is not directly convertible to a ${PARENT-COUNT-VAR}
	 * syntax (for example, the editable string "${FOO}bar\..\..\"), intermediate
	 * path variables will be created.
	 * @param value the value encoded using OS string (as returned from Path.toOSString())
	 * @param locationFormat indicates whether the value contains a string that is stored in the linked resource location rather than in the path variable value
	 * @return the converted path variable value
	 * @since 3.6
	 */
	String convertFromUserEditableFormat(String value, boolean locationFormat);
}
See Also:	IPath
Since:	2.1
@noimplement	This interface is not intended to be implemented by clients.
@noextend	This interface is not intended to be extended by clients.
Params:	path – The absolute path to be converted force – indicates whether intermediate path variables should be created if the path is relative only to a parent of an existing path variable. variableHint – The name of the variable to which the path should be made relative to, or `null` for the nearest one.
Throws:	CoreException – if this method fails. Reasons include: The variable name is not valid
Returns:	The converted path
Since:	3.6
Params:	name – the name of the variable value – the value for the variable (may be `null`)
Throws:	CoreException – if this method fails. Reasons include: The variable name is not valid The variable value is relative
Deprecated:	use `setURIValue(String, URI)` instead.
Params:	name – the name of the variable to return the value for
Returns:	the value for the variable, or `null` if there is no variable defined with the given name
Deprecated:	use `getURIValue(String)` instead.
Params:	listener – the listener
See Also:	IPathVariableChangeListener
Params:	uri – the URI to be resolved
Returns:	the resolved URI or `null`
Since:	3.2
Params:	path – the path to be resolved
Returns:	the resolved path or `null`
Deprecated:	use `resolveURI(URI)` instead.
Params:	name – the variable's name
Returns:	`true` if the variable exists, `false` otherwise
Params:	name – a possibly valid path variable name
See Also:	IStatus.OK
Returns:	a status object with code `IStatus.OK` if the given name is a valid path variable name, otherwise a status object indicating what is wrong with the string
Params:	path – a possibly valid path variable value
See Also:	IPath.isValidPath(String) IStatus.OK
Returns:	a status object with code `IStatus.OK` if the given path is a valid path variable value, otherwise a status object indicating what is wrong with the value
Params:	location – a path in the local file system
Returns:	the corresponding variable relative path, or `null` if no such path is available
Since:	3.6
Params:	value – the value encoded using OS string (as returned from Path.toOSString()) locationFormat – indicates whether the value contains a string that is stored in the linked resource location rather than in the path variable value
Returns:	the converted path variable value
Since:	3.6
/

org.eclipse.platform/ org.eclipse.core.resources/ 3.13.600/ org/eclipse/core/resources/IPathVariableManager.java
