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 */
017package 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 * @see FileObject
024 */
025public interface FileName extends Comparable<FileName>
026{
027    /**
028     * The separator character used in file paths.
029     */
030    char SEPARATOR_CHAR = '/';
031
032    /**
033     * The separator used in file paths.
034     */
035    String SEPARATOR = "/";
036
037    /**
038     * The absolute path of the root of a file system.
039     */
040    String ROOT_PATH = "/";
041
042    /**
043     * Returns the base name of this file.  The base name is the last element
044     * of the file name.  For example the base name of
045     * {@code /somefolder/somefile} is {@code somefile}.
046     * <p>
047     * The root file of a file system has an empty base name.
048     * </p>
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 normalized, so that {@code .} and {@code ..} elements
057     * have been removed.  Also, the path only contains {@code /} as its
058     * separator character.  The path always starts with {@code /}
059     * <p>
060     * The root of a file system has {@code /} as its absolute path.
061     * </p>
062     *
063     * @return The path.  Never returns null.
064     */
065    String getPath();
066
067    /**
068     * Returns the absolute path of this file, within its file system.  This
069     * path is normalized, so that {@code .} and {@code ..} elements
070     * have been removed.  Also, the path only contains {@code /} as its
071     * separator character.  The path always starts with {@code /}
072     * <p>
073     * The root of a file system has {@code /} as its absolute path.
074     * </p>
075     * <p>
076     * In contrast to {@link #getPath()} the path is decoded i.e. all %nn stuff
077     * replaced by its character.
078     * </p>
079     *
080     * @return The path.  Never returns null.
081     * @throws FileSystemException if the path is not correctly encoded
082     */
083    String getPathDecoded() throws FileSystemException;
084
085    /**
086     * Returns the extension of this file name.
087     *
088     * @return The extension.  Returns an empty string if the name has no
089     *         extension.
090     */
091    String getExtension();
092
093    /**
094     * Returns the depth of this file name, within its file system.  The depth
095     * of the root of a file system is 0.  The depth of any other file is
096     * 1 + the depth of its parent.
097     *
098     * @return The depth of this file name.
099     */
100    int getDepth();
101
102    /**
103     * Returns the URI scheme of this file.
104     *
105     * @return The URI scheme of this file.
106     */
107    String getScheme();
108
109    /**
110     * Returns the absolute URI of this file.
111     *
112     * @return the absolute URI of this file.
113     */
114    String getURI();
115
116    /**
117     * Returns the root URI of the file system this file belongs to.
118     *
119     * @return the root URI.
120     */
121    String getRootURI();
122
123    /**
124     * Finds the root of the file system.
125     *
126     * @return the file system root.
127     */
128    FileName getRoot();
129
130    /**
131     * Returns the file name of the parent of this file.  The root of a
132     * file system has no parent.
133     *
134     * @return A {@link FileName} object representing the parent name.  Returns
135     *         null for the root of a file system.
136     */
137    FileName getParent();
138
139    /**
140     * Resolves a name, relative to this file name.  Equivalent to calling
141     * {@code resolveName( path, NameScope.FILE_SYSTEM )}.
142     *
143     * @param name The name to resolve.
144     * @return A {@link FileName} object representing the resolved file name.
145     * @throws FileSystemException If the name is invalid.
146     */
147    // FileName resolveName(String name) throws FileSystemException;
148
149    /**
150     * Resolves a name, relative to this file name.  Refer to {@link NameScope}
151     * for a description of how names are resolved.
152     *
153     * @param name  The name to resolve.
154     * @param scope The scope to use when resolving the name.
155     * @return A {@link FileName} object representing the resolved file name.
156     * @throws FileSystemException If the name is invalid.
157     */
158    // FileName resolveName(String name, NameScope scope)
159    //     throws FileSystemException;
160
161    /**
162     * Converts a file name to a relative name, relative to this file name.
163     *
164     * @param name The name to convert to a relative path.
165     * @return The relative name.
166     * @throws FileSystemException On error.
167     */
168    String getRelativeName(FileName name) throws FileSystemException;
169
170    /**
171     * Determines if another file name is an ancestor of this file name.
172     *
173     * @param ancestor The FileName to check.
174     * @return true if another file name is an ancestor of this file name.
175     */
176    boolean isAncestor(FileName ancestor);
177
178    /**
179     * Determines if another file name is a descendent of this file name.
180     *
181     * @param descendent the FileName to check.
182     * @return true if the other FileName is a descendent of this file name.
183     */
184    boolean isDescendent(FileName descendent);
185
186    /**
187     * Determines if another file name is a descendent of this file name.
188     *
189     * @param descendent the FileName to check.
190     * @param nameScope the NameScope of the FileName.
191     * @return true if the other FileName is a descendent of this file name.
192     */
193    boolean isDescendent(FileName descendent, NameScope nameScope);
194
195    /**
196     * Checks if this file name is a name for a regular file.
197     *
198     * @return true if this file name is a name for a regular file.
199     * @throws FileSystemException if an error occurs.
200     * @see #getType()
201     * @see FileType#FILE
202     * @since 2.1
203     */
204    boolean isFile() throws FileSystemException;
205
206    /**
207     * Returns the requested or current type of this name. <br />
208     * <p>
209     * The "requested" type is the one determined during resolving the name. <br/>
210     * In this case the name is a {@link FileType#FOLDER} if it ends with an "/" else
211     * it will be a {@link FileType#FILE}<br/>
212     * </p>
213     * <p>
214     * Once attached it will be changed to reflect the real type of this resource.
215     * </p>
216     *
217     * @return {@link FileType#FOLDER} or {@link FileType#FILE}
218     */
219    FileType getType();
220
221    /**
222     * Returns a "friendly path", this is a path without a password.
223     * <p>
224     * This path can not be used to resolve the path again
225     * </p>
226     *
227     * @return the friendly URI as a String.
228     */
229    String getFriendlyURI();
230}