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