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[]
|
getPathVariableNames
()
Returns an array containing all defined path variable names. |
IPath
|
getValue
(
String name)
Returns the value of the path variable with the given name. |
boolean
|
isDefined
(
String name)
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)
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). |
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
|
setValue
(
String name,
IPath 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. |
setValue
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.
-
-
Parameters:
-
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
getValue
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
.
-
-
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
getPathVariableNames
String[] getPathVariableNames()
- Returns an array containing all defined path variable names.
-
-
Returns:
- an array containing all defined path variable names
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)
- 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
resolvePath
IPath resolvePath(
IPath path)
- 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
-
-
Parameters:
-
path
- the path to be resolved
-
Returns:
- the resolved path or
null
isDefined
boolean isDefined(
String name)
- 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
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
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.