KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > runtime > IPath


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 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.runtime;
12
13 /**
14  * A path is an ordered collection of string segments,
15  * separated by a standard separator character, "/".
16  * A path may also have a leading and/or a trailing separator.
17  * Paths may also be prefixed by an optional device id, which includes
18  * the character(s) which separate the device id from the rest
19  * of the path. For example, "C:" and "Server/Volume:" are typical
20  * device ids.
21  * A device independent path has <code>null</code> for a device id.
22  * <p>
23  * Note that paths are value objects; all operations on paths
24  * return a new path; the path that is operated on is unscathed.
25  * </p>
26  * <p>
27  * UNC paths are denoted by leading double-slashes such
28  * as <code>//Server/Volume/My/Path</code>. When a new path
29  * is constructed all double-slashes are removed except those
30  * appearing at the beginning of the path.
31  * </p>
32  * <p>
33  * This interface can be used without OSGi running.
34  * </p><p>
35  * This interface is not intended to be implemented by clients.
36  * </p>
37  * @see Path
38  */

39 public interface IPath extends Cloneable JavaDoc {
40
41     /**
42      * Path separator character constant "/" used in paths.
43      */

44     public static final char SEPARATOR = '/';
45
46     /**
47      * Device separator character constant ":" used in paths.
48      */

49     public static final char DEVICE_SEPARATOR = ':';
50
51     /**
52      * Returns a new path which is the same as this path but with
53      * the given file extension added. If this path is empty, root or has a
54      * trailing separator, this path is returned. If this path already
55      * has an extension, the existing extension is left and the given
56      * extension simply appended. Clients wishing to replace
57      * the current extension should first remove the extension and
58      * then add the desired one.
59      * <p>
60      * The file extension portion is defined as the string
61      * following the last period (".") character in the last segment.
62      * The given extension should not include a leading ".".
63      * </p>
64      *
65      * @param extension the file extension to append
66      * @return the new path
67      */

68     public IPath addFileExtension(String JavaDoc extension);
69
70     /**
71      * Returns a path with the same segments as this path
72      * but with a trailing separator added.
73      * This path must have at least one segment.
74      * <p>
75      * If this path already has a trailing separator,
76      * this path is returned.
77      * </p>
78      *
79      * @return the new path
80      * @see #hasTrailingSeparator()
81      * @see #removeTrailingSeparator()
82      */

83     public IPath addTrailingSeparator();
84
85     /**
86      * Returns the canonicalized path obtained from the
87      * concatenation of the given string path to the
88      * end of this path. The given string path must be a valid
89      * path. If it has a trailing separator,
90      * the result will have a trailing separator.
91      * The device id of this path is preserved (the one
92      * of the given string is ignored). Duplicate slashes
93      * are removed from the path except at the beginning
94      * where the path is considered to be UNC.
95      *
96      * @param path the string path to concatenate
97      * @return the new path
98      * @see #isValidPath(String)
99      */

100     public IPath append(String JavaDoc path);
101
102     /**
103      * Returns the canonicalized path obtained from the
104      * concatenation of the given path's segments to the
105      * end of this path. If the given path has a trailing
106      * separator, the result will have a trailing separator.
107      * The device id of this path is preserved (the one
108      * of the given path is ignored). Duplicate slashes
109      * are removed from the path except at the beginning
110      * where the path is considered to be UNC.
111      *
112      * @param path the path to concatenate
113      * @return the new path
114      */

115     public IPath append(IPath path);
116
117     /**
118      * Returns a copy of this path.
119      *
120      * @return the cloned path
121      */

122     public Object JavaDoc clone();
123
124     /**
125      * Returns whether this path equals the given object.
126      * <p>
127      * Equality for paths is defined to be: same sequence of segments,
128      * same absolute/relative status, and same device.
129      * Trailing separators are disregarded.
130      * Paths are not generally considered equal to objects other than paths.
131      * </p>
132      *
133      * @param obj the other object
134      * @return <code>true</code> if the paths are equivalent,
135      * and <code>false</code> if they are not
136      */

137     public boolean equals(Object JavaDoc obj);
138
139     /**
140      * Returns the device id for this path, or <code>null</code> if this
141      * path has no device id. Note that the result will end in ':'.
142      *
143      * @return the device id, or <code>null</code>
144      * @see #setDevice(String)
145      */

146     public String JavaDoc getDevice();
147
148     /**
149      * Returns the file extension portion of this path,
150      * or <code>null</code> if there is none.
151      * <p>
152      * The file extension portion is defined as the string
153      * following the last period (".") character in the last segment.
154      * If there is no period in the last segment, the path has no
155      * file extension portion. If the last segment ends in a period,
156      * the file extension portion is the empty string.
157      * </p>
158      *
159      * @return the file extension or <code>null</code>
160      */

161     public String JavaDoc getFileExtension();
162
163     /**
164      * Returns whether this path has a trailing separator.
165      * <p>
166      * Note: In the root path ("/"), the separator is considered to
167      * be leading rather than trailing.
168      * </p>
169      *
170      * @return <code>true</code> if this path has a trailing
171      * separator, and <code>false</code> otherwise
172      * @see #addTrailingSeparator()
173      * @see #removeTrailingSeparator()
174      */

175     public boolean hasTrailingSeparator();
176
177     /**
178      * Returns whether this path is an absolute path (ignoring
179      * any device id).
180      * <p>
181      * Absolute paths start with a path separator.
182      * A root path, like <code>/</code> or <code>C:/</code>,
183      * is considered absolute. UNC paths are always absolute.
184      * </p>
185      *
186      * @return <code>true</code> if this path is an absolute path,
187      * and <code>false</code> otherwise
188      */

189     public boolean isAbsolute();
190
191     /**
192      * Returns whether this path has no segments and is not
193      * a root path.
194      *
195      * @return <code>true</code> if this path is empty,
196      * and <code>false</code> otherwise
197      */

198     public boolean isEmpty();
199
200     /**
201      * Returns whether this path is a prefix of the given path.
202      * To be a prefix, this path's segments must
203      * appear in the argument path in the same order,
204      * and their device ids must match.
205      * <p>
206      * An empty path is a prefix of all paths with the same device; a root path is a prefix of
207      * all absolute paths with the same device.
208      * </p>
209      * @param anotherPath the other path
210      * @return <code>true</code> if this path is a prefix of the given path,
211      * and <code>false</code> otherwise
212      */

213     public boolean isPrefixOf(IPath anotherPath);
214
215     /**
216      * Returns whether this path is a root path.
217      * <p>
218      * The root path is the absolute non-UNC path with zero segments;
219      * e.g., <code>/</code> or <code>C:/</code>.
220      * The separator is considered a leading separator, not a trailing one.
221      * </p>
222      *
223      * @return <code>true</code> if this path is a root path,
224      * and <code>false</code> otherwise
225      */

226     public boolean isRoot();
227
228     /**
229      * Returns a boolean value indicating whether or not this path
230      * is considered to be in UNC form. Return false if this path
231      * has a device set or if the first 2 characters of the path string
232      * are not <code>Path.SEPARATOR</code>.
233      *
234      * @return boolean indicating if this path is UNC
235      */

236     public boolean isUNC();
237
238     /**
239      * Returns whether the given string is syntactically correct as
240      * a path. The device id is the prefix up to and including the device
241      * separator for the local file system; the path proper is everything to
242      * the right of it, or the entire string if there is no device separator.
243      * When the platform location is a file system with no meaningful device
244      * separator, the entire string is treated as the path proper.
245      * The device id is not checked for validity; the path proper is correct
246     * if each of the segments in its canonicalized form is valid.
247      *
248      * @param path the path to check
249      * @return <code>true</code> if the given string is a valid path,
250      * and <code>false</code> otherwise
251      * @see #isValidSegment(String)
252      */

253     public boolean isValidPath(String JavaDoc path);
254
255     /**
256      * Returns whether the given string is valid as a segment in
257      * a path. The rules for valid segments are as follows:
258      * <ul>
259      * <li> the empty string is not valid
260      * <li> any string containing the slash character ('/') is not valid
261      * <li>any string containing segment or device separator characters
262      * on the local file system, such as the backslash ('\') and colon (':')
263      * on some file systems.
264      * </ul>
265      *
266      * @param segment the path segment to check
267      * @return <code>true</code> if the given path segment is valid,
268      * and <code>false</code> otherwise
269      */

270     public boolean isValidSegment(String JavaDoc segment);
271
272     /**
273      * Returns the last segment of this path, or
274      * <code>null</code> if it does not have any segments.
275      *
276      * @return the last segment of this path, or <code>null</code>
277      */

278     public String JavaDoc lastSegment();
279
280     /**
281      * Returns an absolute path with the segments and device id of this path.
282      * Absolute paths start with a path separator. If this path is absolute,
283      * it is simply returned.
284      *
285      * @return the new path
286      */

287     public IPath makeAbsolute();
288
289     /**
290      * Returns a relative path with the segments and device id of this path.
291      * Absolute paths start with a path separator and relative paths do not.
292      * If this path is relative, it is simply returned.
293      *
294      * @return the new path
295      */

296     public IPath makeRelative();
297
298     /**
299      * Return a new path which is the equivalent of this path converted to UNC
300      * form (if the given boolean is true) or this path not as a UNC path (if the given
301      * boolean is false). If UNC, the returned path will not have a device and the
302      * first 2 characters of the path string will be <code>Path.SEPARATOR</code>. If not UNC, the
303      * first 2 characters of the returned path string will not be <code>Path.SEPARATOR</code>.
304      *
305      * @param toUNC true if converting to UNC, false otherwise
306      * @return the new path, either in UNC form or not depending on the boolean parameter
307      */

308     public IPath makeUNC(boolean toUNC);
309
310     /**
311      * Returns a count of the number of segments which match in
312      * this path and the given path (device ids are ignored),
313      * comparing in increasing segment number order.
314      *
315      * @param anotherPath the other path
316      * @return the number of matching segments
317      */

318     public int matchingFirstSegments(IPath anotherPath);
319
320     /**
321      * Returns a new path which is the same as this path but with
322      * the file extension removed. If this path does not have an
323      * extension, this path is returned.
324      * <p>
325      * The file extension portion is defined as the string
326      * following the last period (".") character in the last segment.
327      * If there is no period in the last segment, the path has no
328      * file extension portion. If the last segment ends in a period,
329      * the file extension portion is the empty string.
330      * </p>
331      *
332      * @return the new path
333      */

334     public IPath removeFileExtension();
335
336     /**
337      * Returns a copy of this path with the given number of segments
338      * removed from the beginning. The device id is preserved.
339      * The number must be greater or equal zero.
340      * If the count is zero, this path is returned.
341      * The resulting path will always be a relative path with respect
342      * to this path. If the number equals or exceeds the number
343      * of segments in this path, an empty relative path is returned.
344      *
345      * @param count the number of segments to remove
346      * @return the new path
347      */

348     public IPath removeFirstSegments(int count);
349
350     /**
351      * Returns a copy of this path with the given number of segments
352      * removed from the end. The device id is preserved.
353      * The number must be greater or equal zero.
354      * If the count is zero, this path is returned.
355      * <p>
356      * If this path has a trailing separator, it will still
357      * have a trailing separator after the last segments are removed
358      * (assuming there are some segments left). If there is no
359      * trailing separator, the result will not have a trailing
360      * separator.
361      * If the number equals or exceeds the number
362      * of segments in this path, a path with no segments is returned.
363      * </p>
364      *
365      * @param count the number of segments to remove
366      * @return the new path
367      */

368     public IPath removeLastSegments(int count);
369
370     /**
371      * Returns a path with the same segments as this path
372      * but with a trailing separator removed.
373      * Does nothing if this path does not have at least one segment.
374      * The device id is preserved.
375      * <p>
376      * If this path does not have a trailing separator,
377      * this path is returned.
378      * </p>
379      *
380      * @return the new path
381      * @see #addTrailingSeparator()
382      * @see #hasTrailingSeparator()
383      */

384     public IPath removeTrailingSeparator();
385
386     /**
387      * Returns the specified segment of this path, or
388      * <code>null</code> if the path does not have such a segment.
389      *
390      * @param index the 0-based segment index
391      * @return the specified segment, or <code>null</code>
392      */

393     public String JavaDoc segment(int index);
394
395     /**
396      * Returns the number of segments in this path.
397      * <p>
398      * Note that both root and empty paths have 0 segments.
399      * </p>
400      *
401      * @return the number of segments
402      */

403     public int segmentCount();
404
405     /**
406      * Returns the segments in this path in order.
407      *
408      * @return an array of string segments
409      */

410     public String JavaDoc[] segments();
411
412     /**
413      * Returns a new path which is the same as this path but with
414      * the given device id. The device id must end with a ":".
415      * A device independent path is obtained by passing <code>null</code>.
416      * <p>
417      * For example, "C:" and "Server/Volume:" are typical device ids.
418      * </p>
419      *
420      * @param device the device id or <code>null</code>
421      * @return a new path
422      * @see #getDevice()
423      */

424     public IPath setDevice(String JavaDoc device);
425
426     /**
427      * Returns a <code>java.io.File</code> corresponding to this path.
428      *
429      * @return the file corresponding to this path
430      */

431     public java.io.File JavaDoc toFile();
432
433     /**
434      * Returns a string representation of this path which uses the
435      * platform-dependent path separator defined by <code>java.io.File</code>.
436      * This method is like <code>toString()</code> except that the
437      * latter always uses the same separator (<code>/</code>) regardless of platform.
438      * <p>
439      * This string is suitable for passing to <code>java.io.File(String)</code>.
440      * </p>
441      *
442      * @return a platform-dependent string representation of this path
443      */

444     public String JavaDoc toOSString();
445
446     /**
447      * Returns a platform-neutral string representation of this path. The
448      * format is not specified, except that the resulting string can be
449      * passed back to the <code>Path#fromPortableString(String)</code>
450      * constructor to produce the exact same path on any platform.
451      * <p>
452      * This string is suitable for passing to <code>Path#fromPortableString(String)</code>.
453      * </p>
454      *
455      * @return a platform-neutral string representation of this path
456      * @see Path#fromPortableString(String)
457      * @since 3.1
458      */

459     public String JavaDoc toPortableString();
460
461     /**
462      * Returns a string representation of this path, including its
463      * device id. The same separator, "/", is used on all platforms.
464      * <p>
465      * Example result strings (without and with device id):
466      * <pre>
467      * "/foo/bar.txt"
468      * "bar.txt"
469      * "/foo/"
470      * "foo/"
471      * ""
472      * "/"
473      * "C:/foo/bar.txt"
474      * "C:bar.txt"
475      * "C:/foo/"
476      * "C:foo/"
477      * "C:"
478      * "C:/"
479      * </pre>
480      * This string is suitable for passing to <code>Path(String)</code>.
481      * </p>
482      *
483      * @return a string representation of this path
484      * @see Path
485      */

486     public String JavaDoc toString();
487
488     /**
489      * Returns a copy of this path truncated after the
490      * given number of segments. The number must not be negative.
491      * The device id is preserved.
492      * <p>
493      * If this path has a trailing separator, the result will too
494      * (assuming there are some segments left). If there is no
495      * trailing separator, the result will not have a trailing
496      * separator.
497      * Copying up to segment zero simply means making an copy with
498      * no path segments.
499      * </p>
500      *
501      * @param count the segment number at which to truncate the path
502      * @return the new path
503      */

504     public IPath uptoSegment(int count);
505 }
506
Popular Tags