Skip to main content
summaryrefslogtreecommitdiffstats
blob: e3502e99b141382ba200b0c9194a0d16e6f801e9 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
/*******************************************************************************
 * Copyright (c) 2000, 2008 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.core.variables;

import org.eclipse.core.runtime.CoreException;

/**
 * Registry for string variables.
 * @since 3.0
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IStringVariableManager {

	/**
	 * Simple identifier constant (value <code>"dynamicVariables"</code>) for the
	 * dynamic variables extension point.
	 */
	public static final String EXTENSION_POINT_DYNAMIC_VARIABLES = "dynamicVariables"; //$NON-NLS-1$
	
	/**
	 * Simple identifier constant (value <code>"valueVariables"</code>) for the
	 * value variables extension point.
	 */
	public static final String EXTENSION_POINT_VALUE_VARIABLES = "valueVariables"; //$NON-NLS-1$
	
	/**
	 * Returns all registered variables.
	 * 
	 * @return a collection of all registered variables
	 */
	public IStringVariable[] getVariables();
	
	/**
	 * Returns all registered value variables.
	 * 
	 * @return a collection of all registered value variables
	 */
	public IValueVariable[] getValueVariables();
	
	/**
	 * Returns the value variable with the given name, or <code>null</code>
	 * if none.
	 * 
	 * @param name variable name
	 * @return the value variable with the given name, or <code>null</code>
	 * if none
	 */
	public IValueVariable getValueVariable(String name);
	
	/**
	 * Returns all registered dynamic variables.
	 * 
	 * @return a collection of all registered dynamic variables
	 */
	public IDynamicVariable[] getDynamicVariables();	
	
	/**
	 * Returns the dynamic variable with the given name or <code>null</code>
	 * if none.
	 * 
	 * @param name variable name
	 * @return the dynamic variable with the given name or <code>null</code>
	 * if none
	 */
	public IDynamicVariable getDynamicVariable(String name);
    
    /**
     * Returns the plug-in identifier of the plug-in that contributed the
     * given variable via extension or <code>null</code> if the given
     * variable wasn't contributed via extension.
     * 
     * @param variable the variable
     * @return the plug-in identifier of the plug-in that contributed the
     *  given variable or <code>null</code>
     * @since 3.1
     */
    public String getContributingPluginId(IStringVariable variable);
	
	/**
	 * 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
	 * <code>performStringSubstitution(expression, true)</code>).
	 * 
	 * @param expression expression referencing variables
	 * @return expression with variable references replaced with variable values
	 * @throws CoreException if unable to resolve the value of one or more variables
	 */
	public String performStringSubstitution(String expression) 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).  
	 * 
	 * @param expression expression referencing variables
	 * @param reportUndefinedVariables whether a reference to an undefined variable
	 *  is to be considered an error (i.e. throw an exception)
	 * @return expression with variable references replaced with variable values
	 * @throws CoreException if unable to resolve the value of one or more variables
	 */
	public String performStringSubstitution(String expression, boolean reportUndefinedVariables) throws CoreException;	
	
	/**
	 * Validates variables references in the given expression and reports errors
	 * for references to undefined variables.
	 * 
	 * @param expression expression referencing variables
	 * @throws CoreException if one or more referenced variables do not exist
	 */
	public void validateStringVariables(String expression) throws CoreException;
	
	/**
	 * Returns a new read-write value variable with the given name and description
	 * with a <code>null</code> value.
	 * 
	 * @param name variable name, cannot be <code>null</code>
	 * @param description variable description, possibly <code>null</code>
	 * @return a new value variable
	 */
	public IValueVariable newValueVariable(String name, String description);

	/**
	 * Returns a new value variable with the given properties.
	 * 
	 * @param name variable name, cannot be <code>null</code>
	 * @param description variable description, possibly <code>null</code>
	 * @param readOnly whether this variable is to be a read only variable
	 * @param value the string value to initialize this variable to - should
	 * 	not be <code>null</code> for read-only variables
	 * @return a new value variable
	 * @since 3.3
	 */
	public IValueVariable newValueVariable(String name, String description, boolean readOnly, String value);
	
	/**
	 * Adds the given variables to the variable registry.
	 * 
	 * @param variables the variables to add
	 * @throws CoreException if one or more variables to add has a name collision with
	 *  an existing variable 
	 */
	public void addVariables(IValueVariable[] variables) throws CoreException;
	
	/**
	 * Removes the given variables from the registry. Has no effect for unregistered
	 * variables.
	 * 
	 * @param variables variables to remove
	 */
	public void removeVariables(IValueVariable[] variables);
	
	/**
	 * Registers the given listener for value variable notifications. Has no effect
	 * if an identical listener is already registered.
	 *   
	 * @param listener value variable listener to add
	 */
	public void addValueVariableListener(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.
	 * 
	 * @param listener value variable listener to remove
	 */
	public void removeValueVariableListener(IValueVariableListener listener);
	
	/**
	 * Convenience method that returns an expression referencing the given
	 * variable and optional argument. For example, calling the method with
	 * a <code>varName</code> of <code>my_var</code> and an <code>argument</code>
	 * of <code>my_arg</code> results in the string <code>$(my_var:my_arg}</code>.
	 * 
	 * @param varName variable name
	 * @param arg argument text or <code>null</code>
	 * @return an expression referencing the given variable and
	 *  optional argument
	 */
	public String generateVariableExpression(String varName, String arg);
	
}

Back to the top