1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.vfs2;
18
19 /**
20 * Represents a file name. File names are immutable, and work correctly as keys in hash tables.
21 *
22 * @see FileObject
23 */
24 public interface FileName extends Comparable<FileName> {
25
26 /**
27 * The separator character used in file paths.
28 */
29 char SEPARATOR_CHAR = '/';
30
31 /**
32 * The separator used in file paths.
33 */
34 String SEPARATOR = "/";
35
36 /**
37 * The absolute path of the root of a file system.
38 */
39 String ROOT_PATH = "/";
40
41 /**
42 * Empty array of FileName.
43 *
44 * @since 2.8.0
45 */
46 FileName#FileName">FileName[] EMPTY_ARRAY = new FileName[0];
47
48 /**
49 * Gets the base name of this file. The base name is the last element of the file name. For example the base name
50 * of {@code /somefolder/somefile} is {@code somefile}.
51 * <p>
52 * The root file of a file system has an empty base name.
53 * </p>
54 *
55 * @return The base name. Never returns null.
56 */
57 String getBaseName();
58
59 /**
60 * Gets the depth of this file name, within its file system. The depth of the root of a file system is 0. The
61 * depth of any other file is 1 + the depth of its parent.
62 *
63 * @return The depth of this file name.
64 */
65 int getDepth();
66
67 /**
68 * Gets the extension of this file name.
69 *
70 * @return The extension. Returns an empty string if the name has no extension.
71 */
72 String getExtension();
73
74 /**
75 * Gets a "friendly path", this is a path without a password.
76 * <p>
77 * This path can not be used to resolve the path again.
78 * </p>
79 *
80 * @return the friendly URI as a String.
81 */
82 String getFriendlyURI();
83
84 /**
85 * Gets the file name of the parent of this file. The root of a file system has no parent.
86 *
87 * @return A {@link FileName} object representing the parent name. Returns null for the root of a file system.
88 */
89 FileName getParent();
90
91 /**
92 * Gets the absolute path string of this file, within its file system. This path is normalized, so that {@code .}
93 * and {@code ..} elements have been removed. Also, the path only contains {@code /} as its separator character. The
94 * path always starts with {@code /}
95 * <p>
96 * The root of a file system has {@code /} as its absolute path.
97 * </p>
98 *
99 * @return The path. Never returns null.
100 */
101 String getPath();
102
103 /**
104 * Returns the absolute path of this file, within its file system. This path is normalized, so that {@code .} and
105 * {@code ..} elements have been removed. Also, the path only contains {@code /} as its separator character. The
106 * path always starts with {@code /}
107 * <p>
108 * The root of a file system has {@code /} as its absolute path.
109 * </p>
110 * <p>
111 * In contrast to {@link #getPath()}, this path is decoded: All %nn escapes are replaced by their respective
112 * characters.
113 * </p>
114 *
115 * @return The decoded path. Never returns null.
116 * @throws FileSystemException if the path is not correctly encoded
117 */
118 String getPathDecoded() throws FileSystemException;
119
120 /**
121 * Converts a file name to a relative name, relative to this file name.
122 *
123 * @param name The name to convert to a relative path.
124 * @return The relative name.
125 * @throws FileSystemException On error.
126 */
127 String getRelativeName(FileName name) throws FileSystemException;
128
129 /**
130 * Gets the root of the file system.
131 *
132 * @return the file system root.
133 */
134 FileName getRoot();
135
136 /**
137 * Gets the root URI string of the file system this file belongs to.
138 *
139 * @return the root URI string.
140 */
141 String getRootURI();
142
143 /**
144 * Gets the URI scheme of this file.
145 *
146 * @return The URI scheme of this file.
147 */
148 String getScheme();
149
150 /**
151 * Gets the requested or current type of this name.
152 * <p>
153 * The "requested" type is the one determined during resolving the name. In this case the name is a
154 * {@link FileType#FOLDER} if it ends with an "/" else it will be a {@link FileType#FILE}.
155 * </p>
156 * <p>
157 * Once attached it will be changed to reflect the real type of this resource.
158 * </p>
159 *
160 * @return {@link FileType#FOLDER} or {@link FileType#FILE}
161 */
162 FileType getType();
163
164 /**
165 * Gets the absolute URI string of this file.
166 *
167 * @return the absolute URI string of this file.
168 */
169 String getURI();
170
171 /**
172 * Tests if another file name is an ancestor of this file name.
173 *
174 * @param ancestor The FileName to check.
175 * @return true if another file name is an ancestor of this file name.
176 */
177 boolean isAncestor(FileName ancestor);
178
179 /**
180 * Tests if another file name is a descendent of this file name.
181 *
182 * @param descendent the FileName to check.
183 * @return true if the other FileName is a descendent of this file name.
184 */
185 boolean isDescendent(FileName descendent);
186
187 /**
188 * Tests if another file name is a descendent of this file name.
189 *
190 * @param descendent the FileName to check.
191 * @param nameScope the NameScope of the FileName.
192 * @return true if the other FileName is a descendent of this file name.
193 */
194 boolean isDescendent(FileName descendent, NameScope nameScope);
195
196 /**
197 * Tests if this file name is a name for a regular file.
198 *
199 * @return true if this file name is a name for a regular file.
200 * @throws FileSystemException if an error occurs.
201 * @see #getType()
202 * @see FileType#FILE
203 * @since 2.1
204 */
205 boolean isFile() throws FileSystemException;
206 }