org.eclipse.core.variables

Interface IStringVariableManager

public interface IStringVariableManager

Registry for string variables.

Since:

3.0

Restriction:

This interface is not intended to be implemented by clients.

Field Summary

Fields

Modifier and Type	Field and Description
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

Modifier and Type	Method and Description
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.
String	getContributingPluginId(IStringVariable variable) Returns the plug-in identifier of the plug-in that contributed the given variable via extension or null if the given variable wasn't contributed via extension.
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 read-write value variable with the given name and description with a null value.
IValueVariable	newValueVariable(String name, String description, boolean readOnly, String value) Returns a new value variable with the given properties.
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

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

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

IStringVariable[] getVariables()

Returns all registered variables.

Returns:

a collection of all registered variables

getValueVariables

IValueVariable[] getValueVariables()

Returns all registered value variables.

Returns:

a collection of all registered value variables

getValueVariable

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

IDynamicVariable[] getDynamicVariables()

Returns all registered dynamic variables.

Returns:

a collection of all registered dynamic variables

getDynamicVariable

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

getContributingPluginId

String getContributingPluginId(IStringVariable variable)

Returns the plug-in identifier of the plug-in that contributed the given variable via extension or null if the given variable wasn't contributed via extension.

Parameters:

variable - the variable

Returns:

the plug-in identifier of the plug-in that contributed the given variable or null

Since:

3.1

performStringSubstitution

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

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

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

IValueVariable newValueVariable(String name,
                                String description)

Returns a new read-write value variable with the given name and description with a null value.

Parameters:

name - variable name, cannot be null

description - variable description, possibly null

Returns:

a new value variable

newValueVariable

IValueVariable newValueVariable(String name,
                                String description,
                                boolean readOnly,
                                String value)

Returns a new value variable with the given properties.

Parameters:

name - variable name, cannot be null

description - variable description, possibly null

readOnly - whether this variable is to be a read only variable

value - the string value to initialize this variable to - should not be null for read-only variables

Returns:

a new value variable

Since:

3.3

addVariables

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

void removeVariables(IValueVariable[] variables)

Removes the given variables from the registry. Has no effect for unregistered variables.

Parameters:

variables - variables to remove

addValueVariableListener

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

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

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