public interface IPathVariableManager
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.
IPath
Modifier and Type | Method and Description |
---|---|
void |
addChangeListener(IPathVariableChangeListener listener)
Registers the given listener to receive notification of changes to path
variables.
|
String |
convertFromUserEditableFormat(String value,
boolean locationFormat)
Converts the user editable format to the internal format.
|
URI |
convertToRelative(URI path,
boolean force,
String variableHint)
Converts an absolute path to path relative to some defined
variable.
|
String |
convertToUserEditableFormat(String value,
boolean locationFormat)
Converts the internal format of the linked resource location if the PARENT
variables is used.
|
String[] |
getPathVariableNames()
Returns an array containing all defined path variable names.
|
URI |
getURIValue(String name)
Returns the value of the path variable with the given name.
|
IPath |
getValue(String name)
Deprecated.
use
getURIValue(String) instead. |
URI |
getVariableRelativePathLocation(URI location)
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)
Returns
true if the given variable is defined and
false otherwise. |
boolean |
isUserDefined(String name)
Returns whether a variable is user defined or not.
|
void |
removeChangeListener(IPathVariableChangeListener listener)
Removes the given path variable change listener from the listeners list.
|
IPath |
resolvePath(IPath path)
Deprecated.
use
resolveURI(URI) instead. |
URI |
resolveURI(URI uri)
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 |
setURIValue(String name,
URI value)
Sets the path variable with the given name to be the specified value.
|
void |
setValue(String name,
IPath value)
Deprecated.
use
setURIValue(String, URI) instead. |
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.
|
URI convertToRelative(URI path, boolean force, String variableHint) throws CoreException
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.
path
- The absolute path to be convertedforce
- 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.CoreException
- if this method fails. Reasons include:
@Deprecated void setValue(String name, IPath value) throws CoreException
setURIValue(String, URI)
instead.
null
.
null
.null
.
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.
name
- the name of the variablevalue
- the value for the variable (may be null
)CoreException
- if this method fails. Reasons include:
void setURIValue(String name, URI value) throws CoreException
null
.
null
.null
.
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.
name
- the name of the variablevalue
- the value for the variable (may be null
)CoreException
- if this method fails. Reasons include:
@Deprecated IPath getValue(String name)
getURIValue(String)
instead.null
.name
- the name of the variable to return the value fornull
if there is no
variable defined with the given nameURI getURIValue(String name)
null
.name
- the name of the variable to return the value fornull
if there is no
variable defined with the given nameString[] getPathVariableNames()
void addChangeListener(IPathVariableChangeListener listener)
listener
- the listenerIPathVariableChangeListener
void removeChangeListener(IPathVariableChangeListener listener)
listener
- the listenerIPathVariableChangeListener
URI resolveURI(URI uri)
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
.
uri
- the URI to be resolvednull
@Deprecated IPath resolvePath(IPath path)
resolveURI(URI)
instead.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
path
- the path to be resolvednull
boolean isDefined(String name)
true
if the given variable is defined and
false
otherwise. Returns false
if the given
name is not a valid path variable name.name
- the variable's nametrue
if the variable exists, false
otherwiseboolean isUserDefined(String name)
IStatus validateName(String name)
name
- a possibly valid path variable nameIStatus.OK
if
the given name is a valid path variable name, otherwise a status
object indicating what is wrong with the stringIStatus.OK
IStatus validateValue(IPath path)
path
- a possibly valid path variable valueIStatus.OK
if the given
path is a valid path variable value, otherwise a status object indicating
what is wrong with the valueIPath.isValidPath(String)
,
IStatus.OK
IStatus validateValue(URI path)
path
- a possibly valid path variable valueIStatus.OK
if the given
path is a valid path variable value, otherwise a status object indicating
what is wrong with the valueIPath.isValidPath(String)
,
IStatus.OK
URI getVariableRelativePathLocation(URI location)
location
- a path in the local file systemnull
if no such path is availableString convertToUserEditableFormat(String value, boolean locationFormat)
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 valueString convertFromUserEditableFormat(String value, boolean locationFormat)
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
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.