Eclipse Platform
Release 3.0

org.eclipse.core.variables
Interface IStringVariableManager


public interface IStringVariableManager

Registry for string variables.

Since:
3.0

Field Summary
static String EXTENSION_POINT_DYNAMIC_VARIABLES
          Simple identifier constant (value "dynamicVariables") for the dynamic variables extension point.
static String EXTENSION_POINT_VALUE_VARIABLES
          Simple identifier constant (value "valueVariables") for the value variables extension point.
 
Method Summary
 void addValueVariableListener(IValueVariableListener listener)
          Registers the given listener for value variable notifications.
 void addVariables(IValueVariable[] variables)
          Adds the given variables to the variable registry.
 String generateVariableExpression(String varName, String arg)
          Convenience method that returns an expression referencing the given variable and optional argument.
 IDynamicVariable getDynamicVariable(String name)
          Returns the dynamic variable with the given name or null if none.
 IDynamicVariable[] getDynamicVariables()
          Returns all registered dynamic variables.
 IValueVariable getValueVariable(String name)
          Returns the value variable with the given name, or null if none.
 IValueVariable[] getValueVariables()
          Returns all registered value variables.
 IStringVariable[] getVariables()
          Returns all registered variables.
 IValueVariable newValueVariable(String name, String description)
          Returns a new value variable with the given name and description.
 String performStringSubstitution(String expression)
          Recursively resolves and replaces all variable references in the given expression with their corresponding values.
 String performStringSubstitution(String expression, boolean reportUndefinedVariables)
          Recursively resolves and replaces all variable references in the given expression with their corresponding values.
 void removeValueVariableListener(IValueVariableListener listener)
          Removes the given listener from the list of registered value variable listeners.
 void removeVariables(IValueVariable[] variables)
          Removes the given variables from the registry.
 void validateStringVariables(String expression)
          Validates variables references in the given expression and reports errors for references to undefined variables.
 

Field Detail

EXTENSION_POINT_DYNAMIC_VARIABLES

public static final String EXTENSION_POINT_DYNAMIC_VARIABLES
Simple identifier constant (value "dynamicVariables") for the dynamic variables extension point.

See Also:
Constant Field Values

EXTENSION_POINT_VALUE_VARIABLES

public static final String EXTENSION_POINT_VALUE_VARIABLES
Simple identifier constant (value "valueVariables") for the value variables extension point.

See Also:
Constant Field Values
Method Detail

getVariables

public IStringVariable[] getVariables()
Returns all registered variables.

Returns:
a collection of all registered variables

getValueVariables

public IValueVariable[] getValueVariables()
Returns all registered value variables.

Returns:
a collection of all registered value variables

getValueVariable

public IValueVariable getValueVariable(String name)
Returns the value variable with the given name, or null if none.

Parameters:
name - variable name
Returns:
the value variable with the given name, or null if none

getDynamicVariables

public IDynamicVariable[] getDynamicVariables()
Returns all registered dynamic variables.

Returns:
a collection of all registered dynamic variables

getDynamicVariable

public IDynamicVariable getDynamicVariable(String name)
Returns the dynamic variable with the given name or null if none.

Parameters:
name - variable name
Returns:
the dynamic variable with the given name or null if none

performStringSubstitution

public String performStringSubstitution(String expression)
                                 throws CoreException
Recursively resolves and replaces all variable references in the given expression with their corresponding values. Reports errors for references to undefined variables (equivalent to calling performStringSubstitution(expression, true)).

Parameters:
expression - expression referencing variables
Returns:
expression with variable references replaced with variable values
Throws:
CoreException - if unable to resolve the value of one or more variables

performStringSubstitution

public String performStringSubstitution(String expression,
                                        boolean reportUndefinedVariables)
                                 throws CoreException
Recursively resolves and replaces all variable references in the given expression with their corresponding values. Allows the client to control whether references to undefined variables are reported as an error (i.e. an exception is thrown).

Parameters:
expression - expression referencing variables
reportUndefinedVariables - whether a reference to an undefined variable is to be considered an error (i.e. throw an exception)
Returns:
expression with variable references replaced with variable values
Throws:
CoreException - if unable to resolve the value of one or more variables

validateStringVariables

public void validateStringVariables(String expression)
                             throws CoreException
Validates variables references in the given expression and reports errors for references to undefined variables.

Parameters:
expression - expression referencing variables
Throws:
CoreException - if one or more referenced variables do not exist

newValueVariable

public IValueVariable newValueVariable(String name,
                                       String description)
Returns a new value variable with the given name and description.

Parameters:
name - variable name, cannot be null
description - variable description, possibly null
Returns:
a new variable
Throws:
CoreException - if a variable already exists with the given name

addVariables

public void addVariables(IValueVariable[] variables)
                  throws CoreException
Adds the given variables to the variable registry.

Parameters:
variables - the variables to add
Throws:
CoreException - if one or more variables to add has a name collision with an existing variable

removeVariables

public void removeVariables(IValueVariable[] variables)
Removes the given variables from the registry. Has no effect for unregistered variables.

Parameters:
variables - variables to remove

addValueVariableListener

public void addValueVariableListener(IValueVariableListener listener)
Registers the given listener for value variable notifications. Has no effect if an identical listener is already registered.

Parameters:
listener - value variable listener to add

removeValueVariableListener

public void removeValueVariableListener(IValueVariableListener listener)
Removes the given listener from the list of registered value variable listeners. Has no effect if an identical listener is not already registered.

Parameters:
listener - value variable listener to remove

generateVariableExpression

public String generateVariableExpression(String varName,
                                         String arg)
Convenience method that returns an expression referencing the given variable and optional argument. For example, calling the method with a varName of my_var and an argument of my_arg results in the string $(my_var:my_arg}.

Parameters:
varName - variable name
arg - argument text or null
Returns:
an expression referencing the given variable and optional argument

Eclipse Platform
Release 3.0

Guidelines for using Eclipse APIs.

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