IStringVariableManager


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.core.variables;
12  
13  import org.eclipse.core.runtime.CoreException;
14  
15  /**
16   * Registry for string variables.
17   * <p>
18   * Clients are not intended to implement this interface.
19   * </p>
20   * @since 3.0
21   */
22  public interface IStringVariableManager {
23  
24      /**
25       * Simple identifier constant (value <code>"dynamicVariables"</code>) for the
26       * dynamic variables extension point.
27       */
28      public static final String   EXTENSION_POINT_DYNAMIC_VARIABLES = "dynamicVariables"; //$NON-NLS-1$
29      
30      /**
31       * Simple identifier constant (value <code>"valueVariables"</code>) for the
32       * value variables extension point.
33       */
34      public static final String   EXTENSION_POINT_VALUE_VARIABLES = "valueVariables"; //$NON-NLS-1$
35      
36      /**
37       * Returns all registered variables.
38       * 
39       * @return a collection of all registered variables
40       */
41      public IStringVariable[] getVariables();
42      
43      /**
44       * Returns all registered value variables.
45       * 
46       * @return a collection of all registered value variables
47       */
48      public IValueVariable[] getValueVariables();
49      
50      /**
51       * Returns the value variable with the given name, or <code>null</code>
52       * if none.
53       * 
54       * @param name variable name
55       * @return the value variable with the given name, or <code>null</code>
56       * if none
57       */
58      public IValueVariable getValueVariable(String   name);
59      
60      /**
61       * Returns all registered dynamic variables.
62       * 
63       * @return a collection of all registered dynamic variables
64       */
65      public IDynamicVariable[] getDynamicVariables();    
66      
67      /**
68       * Returns the dynamic variable with the given name or <code>null</code>
69       * if none.
70       * 
71       * @param name variable name
72       * @return the dynamic variable with the given name or <code>null</code>
73       * if none
74       */
75      public IDynamicVariable getDynamicVariable(String   name);
76      
77      /**
78       * Returns the plug-in identifier of the plug-in that contributed the
79       * given variable via extension or <code>null</code> if the given
80       * variable wasn't contributed via extension.
81       * 
82       * @param variable the variable
83       * @return the plug-in identifier of the plug-in that contributed the
84       *  given variable or <code>null</code>
85       * @since 3.1
86       */
87      public String   getContributingPluginId(IStringVariable variable);
88      
89      /**
90       * Recursively resolves and replaces all variable references in the given
91       * expression with their corresponding values. Reports errors for references
92       * to undefined variables (equivalent to calling
93       * <code>performStringSubstitution(expression, true)</code>).
94       * 
95       * @param expression expression referencing variables
96       * @return expression with variable references replaced with variable values
97       * @throws CoreException if unable to resolve the value of one or more variables
98       */
99      public String   performStringSubstitution(String   expression) throws CoreException;
100     
101     /**
102      * Recursively resolves and replaces all variable references in the given
103      * expression with their corresponding values. Allows the client to control
104      * whether references to undefined variables are reported as an error (i.e.
105      * an exception is thrown).  
106      * 
107      * @param expression expression referencing variables
108      * @param reportUndefinedVariables whether a reference to an undefined variable
109      *  is to be considered an error (i.e. throw an exception)
110      * @return expression with variable references replaced with variable values
111      * @throws CoreException if unable to resolve the value of one or more variables
112      */
113     public String   performStringSubstitution(String   expression, boolean reportUndefinedVariables) throws CoreException;  
114     
115     /**
116      * Validates variables references in the given expression and reports errors
117      * for references to undefined variables.
118      * 
119      * @param expression expression referencing variables
120      * @throws CoreException if one or more referenced variables do not exist
121      */
122     public void validateStringVariables(String   expression) throws CoreException;
123     
124     /**
125      * Returns a new read-write value variable with the given name and description
126      * with a <code>null</code> value.
127      * 
128      * @param name variable name, cannot be <code>null</code>
129      * @param description variable description, possibly <code>null</code>
130      * @return a new value variable
131      */
132     public IValueVariable newValueVariable(String   name, String   description);
133 
134     /**
135      * Returns a new value variable with the given properties.
136      * 
137      * @param name variable name, cannot be <code>null</code>
138      * @param description variable description, possibly <code>null</code>
139      * @param readOnly whether this variable is to be a read only variable
140      * @param value the string value to initialize this variable to - should
141      *  not be <code>null</code> for read-only variables
142      * @return a new value variable
143      * @since 3.3
144      */
145     public IValueVariable newValueVariable(String   name, String   description, boolean readOnly, String   value);
146     
147     /**
148      * Adds the given variables to the variable registry.
149      * 
150      * @param variables the variables to add
151      * @throws CoreException if one or more variables to add has a name collision with
152      *  an existing variable 
153      */
154     public void addVariables(IValueVariable[] variables) throws CoreException;
155     
156     /**
157      * Removes the given variables from the registry. Has no effect for unregistered
158      * variables.
159      * 
160      * @param variables variables to remove
161      */
162     public void removeVariables(IValueVariable[] variables);
163     
164     /**
165      * Registers the given listener for value variable notifications. Has no effect
166      * if an identical listener is already registered.
167      *   
168      * @param listener value variable listener to add
169      */
170     public void addValueVariableListener(IValueVariableListener listener);
171     
172     /**
173      * Removes the given listener from the list of registered value variable
174      * listeners. Has no effect if an identical listener is not already registered.
175      * 
176      * @param listener value variable listener to remove
177      */
178     public void removeValueVariableListener(IValueVariableListener listener);
179     
180     /**
181      * Convenience method that returns an expression referencing the given
182      * variable and optional argument. For example, calling the method with
183      * a <code>varName</code> of <code>my_var</code> and an <code>argument</code>
184      * of <code>my_arg</code> results in the string <code>$(my_var:my_arg}</code>.
185      * 
186      * @param varName variable name
187      * @param arg argument text or <code>null</code>
188      * @return an expression referencing the given variable and
189      *  optional argument
190      */
191     public String   generateVariableExpression(String   varName, String   arg);
192     
193 }
194
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags