Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

This interface is not intended to be implemented by clients.

Since:
  2.1
See Also:
  `IPath`

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

Method Detail

### setValue

    public 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

    public 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

    public String[] getPathVariableNames()

  Returns an array containing all defined path variable names.

  Returns:
    an array containing all defined path variable names

### addChangeListener

    public 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

    public 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`

### resolvePath

    public 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

    public 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

    public 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

    public 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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.