IPathVariableManager


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 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  
12  package org.eclipse.core.resources;
13  
14  import java.net.URI  ;
15  import org.eclipse.core.runtime.*;
16  
17  /**
18   * Manages a collection of path variables and resolves paths containing a
19   * variable reference.
20   * <p>
21   * A path variable is a pair of non-null elements (name,value) where name is 
22   * a case-sensitive string (containing only letters, digits and the underscore
23   * character, and not starting with a digit), and value is an absolute
24   * <code>IPath</code> object.
25   * </p>
26   * <p>
27   * Path variables allow for the creation of relative paths whose exact
28   * location in the file system depends on the value of a variable. A variable
29   * reference may only appear as the first segment of a relative path.
30   * </p>
31   * <p>
32   * This interface is not intended to be implemented by clients.
33   * </p>
34   * 
35   * @see org.eclipse.core.runtime.IPath
36   * @since 2.1
37   */
38  public interface IPathVariableManager {
39  
40      /**
41       * Sets the path variable with the given name to be the specified value.
42       * Depending on the value given and if the variable is currently defined
43       * or not, there are several possible outcomes for this operation:
44       * <p>
45       * <ul>
46       * <li>A new variable will be created, if there is no variable defined with
47       * the given name, and the given value is not <code>null</code>.
48       * </li>
49       * 
50       * <li>The referred variable's value will be changed, if it already exists
51       * and the given value is not <code>null</code>.</li>
52       * 
53       * <li>The referred variable will be removed, if a variable with the given
54       * name is currently defined and the given value is <code>null</code>.
55       * </li>
56       *  
57       * <li>The call will be ignored, if a variable with the given name is not
58       * currently defined and the given value is <code>null</code>, or if it is
59       * defined but the given value is equal to its current value.
60       * </li>
61       * </ul>
62       * <p>If a variable is effectively changed, created or removed by a call to
63       * this method, notification will be sent to all registered listeners.</p>
64       * 
65       * @param name the name of the variable 
66       * @param value the value for the variable (may be <code>null</code>)
67       * @exception CoreException if this method fails. Reasons include:
68       * <ul>
69       * <li>The variable name is not valid</li>
70       * <li>The variable value is relative</li>
71       * </ul>
72       */
73      public void setValue(String   name, IPath value) throws CoreException;
74  
75      /**
76       * Returns the value of the path variable with the given name. If there is
77       * no variable defined with the given name, returns <code>null</code>.
78       * 
79       * @param name the name of the variable to return the value for  
80       * @return the value for the variable, or <code>null</code> if there is no
81       *    variable defined with the given name
82       */
83      public IPath getValue(String   name);
84  
85      /**
86       * Returns an array containing all defined path variable names.
87       *  
88       * @return an array containing all defined path variable names
89       */
90      public String  [] getPathVariableNames();
91  
92      /**
93       * Registers the given listener to receive notification of changes to path
94       * variables. The listener will be notified whenever a variable has been
95       * added, removed or had its value changed. Has no effect if an identical
96       * path variable change listener is already registered.
97       * 
98       * @param listener the listener
99       * @see IPathVariableChangeListener
100      */
101     public void addChangeListener(IPathVariableChangeListener listener);
102 
103     /**
104      * Removes the given path variable change listener from the listeners list.
105      * Has no effect if an identical listener is not registered.
106      * 
107      * @param listener the listener 
108      * @see IPathVariableChangeListener
109      */
110     public void removeChangeListener(IPathVariableChangeListener listener);
111 
112     /**
113      * Resolves a relative <code>URI</code> object potentially containing a
114      * variable reference as its first segment, replacing the variable reference
115      * (if any) with the variable's value (which is a concrete absolute URI).
116      * If the given URI is absolute or has a non- <code>null</code> device then
117      * no variable substitution is done and that URI is returned as is.  If the
118      * given URI is relative and has a <code>null</code> device, but the first
119      * segment does not correspond to a defined variable, then the URI is
120      * returned as is.
121      * <p>
122      * If the given URI is <code>null</code> then <code>null</code> will be
123      * returned.  In all other cases the result will be non-<code>null</code>.
124      * </p>
125      * 
126      * @param uri  the URI to be resolved
127      * @return the resolved URI or <code>null</code>
128      * @since 3.2
129      */
130     public URI   resolveURI(URI   uri);
131 
132     /**
133      * Resolves a relative <code>IPath</code> object potentially containing a
134      * variable reference as its first segment, replacing the variable reference
135      * (if any) with the variable's value (which is a concrete absolute path).
136      * If the given path is absolute or has a non- <code>null</code> device then
137      * no variable substitution is done and that path is returned as is.  If the
138      * given path is relative and has a <code>null</code> device, but the first
139      * segment does not correspond to a defined variable, then the path is
140      * returned as is.
141      * <p>
142      * If the given path is <code>null</code> then <code>null</code> will be
143      * returned.  In all other cases the result will be non-<code>null</code>.
144      * </p>
145      * 
146      * <p>
147      * For example, consider the following collection of path variables:
148      * </p>
149      * <ul>
150      * <li>TEMP = c:/temp</li>
151      * <li>BACKUP = /tmp/backup</li>
152      * </ul>
153      * <p>The following paths would be resolved as:
154      * <p>c:/bin => c:/bin</p>
155      * <p>c:TEMP => c:TEMP</p>
156      * <p>/TEMP => /TEMP</p>
157      * <p>TEMP  => c:/temp</p>
158      * <p>TEMP/foo  => c:/temp/foo</p>
159      * <p>BACKUP  => /tmp/backup</p>
160      * <p>BACKUP/bar.txt  => /tmp/backup/bar.txt</p>
161      * <p>SOMEPATH/foo => SOMEPATH/foo</p></p>
162      * 
163      * @param path the path to be resolved
164      * @return the resolved path or <code>null</code>
165      */
166     public IPath resolvePath(IPath path);
167 
168     /**
169      * Returns <code>true</code> if the given variable is defined and
170      * <code>false</code> otherwise. Returns <code>false</code> if the given
171      * name is not a valid path variable name.
172      * 
173      * @param name the variable's name
174      * @return <code>true</code> if the variable exists, <code>false</code>
175      *    otherwise
176      */
177     public boolean isDefined(String   name);
178 
179     /**
180      * Validates the given name as the name for a path variable. A valid path
181      * variable name is made exclusively of letters, digits and the underscore
182      * character, and does not start with a digit.
183      * 
184      * @param name a possibly valid path variable name
185      * @return a status object with code <code>IStatus.OK</code> if
186      *    the given name is a valid path variable name, otherwise a status
187      *    object indicating what is wrong with the string
188      * @see IStatus#OK
189      */
190     public IStatus validateName(String   name);
191 
192     /**
193      * Validates the given path as the value for a path variable. A path
194      * variable value must be a valid path that is absolute.
195      *
196      * @param path a possibly valid path variable value
197      * @return a status object with code <code>IStatus.OK</code> if the given
198      * path is a valid path variable value, otherwise a status object indicating
199      * what is wrong with the value
200      * @see IPath#isValidPath(String)
201      * @see IStatus#OK
202      */
203     public IStatus validateValue(IPath path);
204 }
205
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags