KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > vfs > FileName


1 /*
2  * Copyright 2002-2005 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16 package org.apache.commons.vfs;
17
18 /**
19  * Represents a file name. File names are immutable, and work correctly as
20  * keys in hash tables.
21  *
22  * @author <a HREF="mailto:adammurdoch@apache.org">Adam Murdoch</a>
23  * @see FileObject
24  */

25 public interface FileName extends Comparable JavaDoc
26 {
27     /**
28      * The separator character used in file paths.
29      */

30     public final char SEPARATOR_CHAR = '/';
31
32     /**
33      * The separator used in file paths.
34      */

35     public final String JavaDoc SEPARATOR = "/";
36
37     /**
38      * The absolute path of the root of a file system.
39      */

40     public final String JavaDoc ROOT_PATH = "/";
41
42     /**
43      * Returns the base name of this file. The base name is the last element
44      * of the file name. For example the base name of
45      * <code>/somefolder/somefile</code> is <code>somefile</code>.
46      * <p/>
47      * <p>The root file of a file system has an empty base name.
48      *
49      * @return The base name. Never returns null.
50      */

51     public String JavaDoc getBaseName();
52
53     /**
54      * Returns the absolute path of this file, within its file system. This
55      * path is normalised, so that <code>.</code> and <code>..</code> elements
56      * have been removed. Also, the path only contains <code>/</code> as its
57      * separator character. The path always starts with <code>/</code>
58      * <p/>
59      * <p>The root of a file system has <code>/</code> as its absolute path.
60      *
61      * @return The path. Never returns null.
62      */

63     public String JavaDoc getPath();
64
65     /**
66      * Returns the absolute path of this file, within its file system. This
67      * path is normalised, so that <code>.</code> and <code>..</code> elements
68      * have been removed. Also, the path only contains <code>/</code> as its
69      * separator character. The path always starts with <code>/</code>
70      * <p/>
71      * <p>The root of a file system has <code>/</code> as its absolute path.
72      * <p/>
73      * In contrast to {@link #getPath()} the path is decoded i.e. all %nn stuff
74      * replaced by its character.
75      *
76      * @return The path. Never returns null.
77      * @throws FileSystemException if the path is not correctly encoded
78      */

79     public String JavaDoc getPathDecoded() throws FileSystemException;
80
81     /**
82      * Returns the extension of this file name.
83      *
84      * @return The extension. Returns an empty string if the name has no
85      * extension.
86      */

87     public String JavaDoc getExtension();
88
89     /**
90      * Returns the depth of this file name, within its file system. The depth
91      * of the root of a file system is 0. The depth of any other file is
92      * 1 + the depth of its parent.
93      */

94     public int getDepth();
95
96     /**
97      * Returns the URI scheme of this file.
98      */

99     public String JavaDoc getScheme();
100
101     /**
102      * Returns the absolute URI of this file.
103      */

104     public String JavaDoc getURI();
105
106     /**
107      * Returns the root URI of the file system this file belongs to.
108      */

109     public String JavaDoc getRootURI();
110
111     /**
112      * find the root of the filesystem
113      */

114     public FileName getRoot();
115
116     /**
117      * Returns the file name of the parent of this file. The root of a
118      * file system has no parent.
119      *
120      * @return A {@link FileName} object representing the parent name. Returns
121      * null for the root of a file system.
122      */

123     public FileName getParent();
124
125     /**
126      * Resolves a name, relative to this file name. Equivalent to calling
127      * <code>resolveName( path, NameScope.FILE_SYSTEM )</code>.
128      *
129      * @param name The name to resolve.
130      * @return A {@link FileName} object representing the resolved file name.
131      * @throws FileSystemException If the name is invalid.
132      */

133     // FileName resolveName(String name) throws FileSystemException;
134

135     /**
136      * Resolves a name, relative to this file name. Refer to {@link NameScope}
137      * for a description of how names are resolved.
138      *
139      * @param name The name to resolve.
140      * @param scope The scope to use when resolving the name.
141      * @return A {@link FileName} object representing the resolved file name.
142      * @throws FileSystemException If the name is invalid.
143      */

144     // FileName resolveName(String name, NameScope scope)
145
// throws FileSystemException;
146

147     /**
148      * Converts a file name to a relative name, relative to this file name.
149      *
150      * @param name The name to convert to a relative path.
151      * @return The relative name.
152      * @throws FileSystemException On error.
153      */

154     public String JavaDoc getRelativeName(FileName name) throws FileSystemException;
155
156     /**
157      * Determines if another file name is an ancestor of this file name.
158      */

159     public boolean isAncestor(FileName ancestor);
160
161     /**
162      * Determines if another file name is a descendent of this file name.
163      */

164     public boolean isDescendent(FileName descendent);
165
166     /**
167      * Determines if another file name is a descendent of this file name.
168      */

169     public boolean isDescendent(FileName descendent, NameScope nameScope);
170
171     /**
172      * Returns the requested or current type of this name. <br />
173      * <p/>
174      * The "requested" type is the one determined during resolving the name. <br/>
175      * In this case the name is a {@link FileType#FOLDER} if it ends with an "/" else
176      * it will be a {@link FileType#FILE}<br/>
177      * </p>
178      * <p/>
179      * Once attached it will be changed to reflect the real type of this resource.
180      * </p>
181      *
182      * @return {@link FileType#FOLDER} or {@link FileType#FILE}
183      */

184     public FileType getType();
185 }
186
Popular Tags