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 keys in hash tables.
021 *
022 * @see FileObject
023 */
024public interface FileName extends Comparable<FileName> {
025
026    /**
027     * The separator character used in file paths.
028     */
029    char SEPARATOR_CHAR = '/';
030
031    /**
032     * The separator used in file paths.
033     */
034    String SEPARATOR = "/";
035
036    /**
037     * The absolute path of the root of a file system.
038     */
039    String ROOT_PATH = "/";
040
041    /**
042     * Empty array of FileName.
043     *
044     * @since 2.8.0
045     */
046    FileName[] EMPTY_ARRAY = {};
047
048    /**
049     * Gets the base name of this file. The base name is the last element of the file name. For example the base name
050     * of {@code /somefolder/somefile} is {@code somefile}.
051     * <p>
052     * The root file of a file system has an empty base name.
053     * </p>
054     *
055     * @return The base name. Never returns null.
056     */
057    String getBaseName();
058
059    /**
060     * Gets the depth of this file name, within its file system. The depth of the root of a file system is 0. The
061     * depth of any other file is 1 + the depth of its parent.
062     *
063     * @return The depth of this file name.
064     */
065    int getDepth();
066
067    /**
068     * Gets the extension of this file name.
069     *
070     * @return The extension. Returns an empty string if the name has no extension.
071     */
072    String getExtension();
073
074    /**
075     * Gets a "friendly path", this is a path without a password.
076     * <p>
077     * This path cannot be used to resolve the path again.
078     * </p>
079     *
080     * @return the friendly URI as a String.
081     */
082    String getFriendlyURI();
083
084    /**
085     * Gets the file name of the parent of this file. The root of a file system has no parent.
086     *
087     * @return A {@link FileName} object representing the parent name. Returns null for the root of a file system.
088     */
089    FileName getParent();
090
091    /**
092     * Gets the absolute path string of this file, within its file system. This path is normalized, so that {@code .}
093     * and {@code ..} elements have been removed. Also, the path only contains {@code /} as its separator character. The
094     * path always starts with {@code /}
095     * <p>
096     * The root of a file system has {@code /} as its absolute path.
097     * </p>
098     *
099     * @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}