KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > resources > 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 JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc[] 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 JavaDoc resolveURI(URI JavaDoc 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 JavaDoc 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 JavaDoc 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
Popular Tags