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   {
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   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   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   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   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   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   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   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   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   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   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  [] 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   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   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   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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags