001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.vfs2;
018
019 /**
020 * Represents a file name. File names are immutable, and work correctly as
021 * keys in hash tables.
022 *
023 * @author <a href="http://commons.apache.org/vfs/team-list.html">Commons VFS team</a>
024 * @see FileObject
025 */
026 public interface FileName extends Comparable<FileName>
027 {
028 /**
029 * The separator character used in file paths.
030 */
031 char SEPARATOR_CHAR = '/';
032
033 /**
034 * The separator used in file paths.
035 */
036 String SEPARATOR = "/";
037
038 /**
039 * The absolute path of the root of a file system.
040 */
041 String ROOT_PATH = "/";
042
043 /**
044 * Returns the base name of this file. The base name is the last element
045 * of the file name. For example the base name of
046 * <code>/somefolder/somefile</code> is <code>somefile</code>.
047 * <p/>
048 * <p>The root file of a file system has an empty base name.
049 *
050 * @return The base name. Never returns null.
051 */
052 String getBaseName();
053
054 /**
055 * Returns the absolute path of this file, within its file system. This
056 * path is normalised, so that <code>.</code> and <code>..</code> elements
057 * have been removed. Also, the path only contains <code>/</code> as its
058 * separator character. The path always starts with <code>/</code>
059 * <p/>
060 * <p>The root of a file system has <code>/</code> as its absolute path.
061 *
062 * @return The path. Never returns null.
063 */
064 String getPath();
065
066 /**
067 * Returns the absolute path of this file, within its file system. This
068 * path is normalised, so that <code>.</code> and <code>..</code> elements
069 * have been removed. Also, the path only contains <code>/</code> as its
070 * separator character. The path always starts with <code>/</code>
071 * <p/>
072 * <p>The root of a file system has <code>/</code> as its absolute path.
073 * <p/>
074 * In contrast to {@link #getPath()} the path is decoded i.e. all %nn stuff
075 * replaced by its character.
076 *
077 * @return The path. Never returns null.
078 * @throws FileSystemException if the path is not correctly encoded
079 */
080 String getPathDecoded() throws FileSystemException;
081
082 /**
083 * Returns the extension of this file name.
084 *
085 * @return The extension. Returns an empty string if the name has no
086 * extension.
087 */
088 String getExtension();
089
090 /**
091 * Returns the depth of this file name, within its file system. The depth
092 * of the root of a file system is 0. The depth of any other file is
093 * 1 + the depth of its parent.
094 * @return The depth of this file name.
095 */
096 int getDepth();
097
098 /**
099 * Returns the URI scheme of this file.
100 * @return The URI scheme of this file.
101 */
102 String getScheme();
103
104 /**
105 * Returns the absolute URI of this file.
106 * @return the absolute URI of this file.
107 */
108 String getURI();
109
110 /**
111 * Returns the root URI of the file system this file belongs to.
112 * @return the root URI.
113 */
114 String getRootURI();
115
116 /**
117 * find the root of the filesystem.
118 * @return the file system root.
119 */
120 FileName getRoot();
121
122 /**
123 * Returns the file name of the parent of this file. The root of a
124 * file system has no parent.
125 *
126 * @return A {@link FileName} object representing the parent name. Returns
127 * null for the root of a file system.
128 */
129 FileName getParent();
130
131 /**
132 * Resolves a name, relative to this file name. Equivalent to calling
133 * <code>resolveName( path, NameScope.FILE_SYSTEM )</code>.
134 *
135 * @param name The name to resolve.
136 * @return A {@link FileName} object representing the resolved file name.
137 * @throws FileSystemException If the name is invalid.
138 */
139 // FileName resolveName(String name) throws FileSystemException;
140
141 /**
142 * Resolves a name, relative to this file name. Refer to {@link NameScope}
143 * for a description of how names are resolved.
144 *
145 * @param name The name to resolve.
146 * @param scope The scope to use when resolving the name.
147 * @return A {@link FileName} object representing the resolved file name.
148 * @throws FileSystemException If the name is invalid.
149 */
150 // FileName resolveName(String name, NameScope scope)
151 // throws FileSystemException;
152
153 /**
154 * Converts a file name to a relative name, relative to this file name.
155 *
156 * @param name The name to convert to a relative path.
157 * @return The relative name.
158 * @throws FileSystemException On error.
159 */
160 String getRelativeName(FileName name) throws FileSystemException;
161
162 /**
163 * Determines if another file name is an ancestor of this file name.
164 * @param ancestor The FileName to check.
165 * @return true if another file name is an ancestor of this file name.
166 */
167 boolean isAncestor(FileName ancestor);
168
169 /**
170 * Determines if another file name is a descendent of this file name.
171 * @param descendent the FileName to check.
172 * @return true if the other FileName is a descendent of this file name.
173 */
174 boolean isDescendent(FileName descendent);
175
176 /**
177 * Determines if another file name is a descendent of this file name.
178 * @param descendent the FileName to check.
179 * @param nameScope the NameScope of the FileName.
180 * @return true if the other FileName is a descendent of this file name.
181 */
182 boolean isDescendent(FileName descendent, NameScope nameScope);
183
184 /**
185 * Returns the requested or current type of this name. <br />
186 * <p>
187 * The "requested" type is the one determined during resolving the name. <br/>
188 * In this case the name is a {@link FileType#FOLDER} if it ends with an "/" else
189 * it will be a {@link FileType#FILE}<br/>
190 * </p>
191 * <p>
192 * Once attached it will be changed to reflect the real type of this resource.
193 * </p>
194 *
195 * @return {@link FileType#FOLDER} or {@link FileType#FILE}
196 */
197 FileType getType();
198
199 /**
200 * returns a "friendly path", this is a path without a password.<br />
201 * This path can not be used to resolve the path again
202 * @return the friendly URI as a String.
203 */
204 String getFriendlyURI();
205 }