Eclipse Platform
Release 3.6

org.eclipse.core.resources
Interface IPathVariableManager


public interface IPathVariableManager

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.

Since:
2.1
See Also:
IPath
Restriction:
This interface is not intended to be implemented by clients.
Restriction:
This interface is not intended to be extended by clients.

Method Summary
 void addChangeListener(IPathVariableChangeListener listener)
          Registers the given listener to receive notification of changes to path variables.
 String convertFromUserEditableFormat(String value, boolean locationFormat, IResource resource)
          Converts the user editable format to the internal format.
 URI convertToRelative(URI path, IResource resource, boolean force, String variableHint)
          Convert an absolute path to path variable relative path.
 String convertToUserEditableFormat(String value, boolean locationFormat)
          Converts the internal format of the linked resource location if the PARENT variables is used.
 IPathVariable getPathVariable(String name, IResource resource)
          Returns the IPathVariable interface for the variable with the given name.
 String[] getPathVariableNames()
          Deprecated. use getPathVariableNames(IResource) instead.
 String[] getPathVariableNames(IResource resource)
          Returns an array containing all defined path variable names.
 IPath getValue(String name)
          Deprecated. use getValue(String, IResource) instead.
 URI getValue(String name, IResource resource)
          Returns the value of the path variable with the given name.
 URI getVariableRelativePathLocation(URI location, IResource resource)
          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.
 boolean isDefined(String name)
          Deprecated. use isDefined(String, IResource) instead.
 boolean isDefined(String name, IResource resource)
          Returns true if the given variable is defined and false otherwise.
 void removeChangeListener(IPathVariableChangeListener listener)
          Removes the given path variable change listener from the listeners list.
 IPath resolvePath(IPath path)
          Deprecated. use resolveURI(URI, IResource) instead.
 URI resolveURI(URI uri)
          Deprecated. use resolveURI(URI, IResource) instead.
 URI resolveURI(URI uri, IResource resource)
          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).
 void setValue(String name, IPath value)
          Deprecated. use setValue(String, IResource, URI) instead.
  • The variable name is not valid
  • The variable value is relative
 void setValue(String name, IResource resource, URI value)
          Sets the path variable with the given name to be the specified value.
 IStatus validateName(String name)
          Validates the given name as the name for a path variable.
 IStatus validateValue(IPath path)
          Validates the given path as the value for a path variable.
 IStatus validateValue(URI path)
          Validates the given path as the value for a path variable.
 

Method Detail

convertToRelative

URI convertToRelative(URI path,
                      IResource resource,
                      boolean force,
                      String variableHint)
                      throws CoreException
Convert an absolute path to path variable relative path. For example, converts "C:/foo/bar.txt" into "FOO/bar.txt", granted that the path variable "FOO" value is "C:/foo". The "force" argument allows intermediate path variable to be created if for a 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 to which path variable the path should be made relative to.

Parameters:
path - The absolute path to be converted
resource - the resource for which this variable is set
force - Set to true if intermediate path variables need to 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 relative to, or null for the nearest one.
Returns:
The converted path
Throws:
CoreException - if this method fails. Reasons include:
  • The variable name is not valid
  • Since:
    3.6

setValue

void setValue(String name,
              IPath value)
              throws CoreException
Deprecated. use setValue(String, IResource, URI) instead.
  • The variable name is not valid
  • The variable value is relative

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:

If a variable is effectively changed, created or removed by a call to this method, notification will be sent to all registered listeners.

Parameters:
name - the name of the variable
value - the value for the variable (may be null)
Throws:
CoreException - if this method fails. Reasons include:

setValue

void setValue(String name,
              IResource resource,
              URI 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:

If a variable is effectively changed, created or removed by a call to this method, notification will be sent to all registered listeners.

Parameters:
name - the name of the variable
resource - the resource for which this variable is set
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

getPathVariable

IPathVariable getPathVariable(String name,
                              IResource resource)
Returns the IPathVariable interface for the variable with the given name. If there is no variable defined with the given name, returns null.

Parameters:
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

getValue

IPath getValue(String name)
Deprecated. use getValue(String, IResource) instead.

Returns the value of the path variable with the given name. If there is no variable defined with the given name, returns null.

Parameters:
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

getValue

URI getValue(String name,
             IResource resource)
Returns the value of the path variable with the given name. If there is no variable defined with the given name, returns null.

Parameters:
name - the name of the variable to return the value for
resource - the resource for which this variable is resolved
Returns:
the value for the variable, or null if there is no variable defined with the given name
Since:
3.6

getPathVariableNames

String[] getPathVariableNames()
Deprecated. use getPathVariableNames(IResource) instead.

Returns an array containing all defined path variable names.

Returns:
an array containing all defined path variable names

getPathVariableNames

String[] getPathVariableNames(IResource resource)
Returns an array containing all defined path variable names.

Returns:
an array containing all defined path variable names
Since:
3.6

addChangeListener

void addChangeListener(IPathVariableChangeListener listener)
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.

Parameters:
listener - the listener
See Also:
IPathVariableChangeListener

removeChangeListener

void removeChangeListener(IPathVariableChangeListener listener)
Removes the given path variable change listener from the listeners list. Has no effect if an identical listener is not registered.

Parameters:
listener - the listener
See Also:
IPathVariableChangeListener

resolveURI

URI resolveURI(URI uri)
Deprecated. use resolveURI(URI, IResource) instead.

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.

Parameters:
uri - the URI to be resolved
Returns:
the resolved URI or null
Since:
3.2

resolveURI

URI resolveURI(URI uri,
               IResource resource)
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.

Parameters:
uri - the URI to be resolved
resource - the resource for which this variable is resolved
Returns:
the resolved URI or null
Since:
3.6

resolvePath

IPath resolvePath(IPath path)
Deprecated. use resolveURI(URI, IResource) instead.

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:

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

Parameters:
path - the path to be resolved
Returns:
the resolved path or null

isDefined

boolean isDefined(String name)
Deprecated. use isDefined(String, IResource) instead.

Returns true if the given variable is defined and false otherwise. Returns false if the given name is not a valid path variable name.

Parameters:
name - the variable's name
Returns:
true if the variable exists, false otherwise

isDefined

boolean isDefined(String name,
                  IResource resource)
Returns true if the given variable is defined and false otherwise. Returns false if the given name is not a valid path variable name.

Parameters:
name - the variable's name
resource - the resource for which this variable is resolved
Returns:
true if the variable exists, false otherwise
Since:
3.6

validateName

IStatus validateName(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.

Parameters:
name - a possibly valid path variable name
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
See Also:
IStatus.OK

validateValue

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.

Parameters:
path - a possibly valid path variable value
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
See Also:
IPath.isValidPath(String), IStatus.OK

validateValue

IStatus validateValue(URI path)
Validates the given path as the value for a path variable. A path variable value must be a valid path that is absolute.

Parameters:
path - a possibly valid path variable value
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
See Also:
IPath.isValidPath(String), IStatus.OK

getVariableRelativePathLocation

URI getVariableRelativePathLocation(URI location,
                                    IResource resource)
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.

Parameters:
location - a path in the local file system
resource - the resource for which this variable is resolved
Returns:
the corresponding variable relative path, or null if no such path is available
Since:
3.6

convertToUserEditableFormat

String convertToUserEditableFormat(String value,
                                   boolean locationFormat)
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".

Parameters:
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

convertFromUserEditableFormat

String convertFromUserEditableFormat(String value,
                                     boolean locationFormat,
                                     IResource resource)
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.

Parameters:
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
resource - the resource for which this variable is resolved
Returns:
the converted path variable value
Since:
3.6

Eclipse Platform
Release 3.6

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2010. All rights reserved.