View Javadoc
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       * Returns the base name of this file. The base name is the last element of the file name. For example the base name
43       * of {@code /somefolder/somefile} is {@code somefile}.
44       * <p>
45       * The root file of a file system has an empty base name.
46       * </p>
47       *
48       * @return The base name. Never returns null.
49       */
50      String getBaseName();
51  
52      /**
53       * Returns the absolute path of this file, within its file system. This path is normalized, so that {@code .} and
54       * {@code ..} elements have been removed. Also, the path only contains {@code /} as its separator character. The
55       * path always starts with {@code /}
56       * <p>
57       * The root of a file system has {@code /} as its absolute path.
58       * </p>
59       *
60       * @return The path. Never returns null.
61       */
62      String getPath();
63  
64      /**
65       * Returns the absolute path of this file, within its file system. This path is normalized, so that {@code .} and
66       * {@code ..} elements have been removed. Also, the path only contains {@code /} as its separator character. The
67       * path always starts with {@code /}
68       * <p>
69       * The root of a file system has {@code /} as its absolute path.
70       * </p>
71       * <p>
72       * In contrast to {@link #getPath()} the path is decoded i.e. all %nn stuff replaced by its character.
73       * </p>
74       *
75       * @return The path. Never returns null.
76       * @throws FileSystemException if the path is not correctly encoded
77       */
78      String getPathDecoded() throws FileSystemException;
79  
80      /**
81       * Returns the extension of this file name.
82       *
83       * @return The extension. Returns an empty string if the name has no extension.
84       */
85      String getExtension();
86  
87      /**
88       * Returns the depth of this file name, within its file system. The depth of the root of a file system is 0. The
89       * depth of any other file is 1 + the depth of its parent.
90       *
91       * @return The depth of this file name.
92       */
93      int getDepth();
94  
95      /**
96       * Returns the URI scheme of this file.
97       *
98       * @return The URI scheme of this file.
99       */
100     String getScheme();
101 
102     /**
103      * Returns the absolute URI of this file.
104      *
105      * @return the absolute URI of this file.
106      */
107     String getURI();
108 
109     /**
110      * Returns the root URI of the file system this file belongs to.
111      *
112      * @return the root URI.
113      */
114     String getRootURI();
115 
116     /**
117      * Finds the root of the file system.
118      *
119      * @return the file system root.
120      */
121     FileName getRoot();
122 
123     /**
124      * Returns the file name of the parent of this file. The root of a file system has no parent.
125      *
126      * @return A {@link FileName} object representing the parent name. Returns null for the root of a file system.
127      */
128     FileName getParent();
129 
130     /**
131      * Converts a file name to a relative name, relative to this file name.
132      *
133      * @param name The name to convert to a relative path.
134      * @return The relative name.
135      * @throws FileSystemException On error.
136      */
137     String getRelativeName(FileName name) throws FileSystemException;
138 
139     /**
140      * Determines if another file name is an ancestor of this file name.
141      *
142      * @param ancestor The FileName to check.
143      * @return true if another file name is an ancestor of this file name.
144      */
145     boolean isAncestor(FileName ancestor);
146 
147     /**
148      * Determines if another file name is a descendent of this file name.
149      *
150      * @param descendent the FileName to check.
151      * @return true if the other FileName is a descendent of this file name.
152      */
153     boolean isDescendent(FileName descendent);
154 
155     /**
156      * Determines if another file name is a descendent of this file name.
157      *
158      * @param descendent the FileName to check.
159      * @param nameScope the NameScope of the FileName.
160      * @return true if the other FileName is a descendent of this file name.
161      */
162     boolean isDescendent(FileName descendent, NameScope nameScope);
163 
164     /**
165      * Checks if this file name is a name for a regular file.
166      *
167      * @return true if this file name is a name for a regular file.
168      * @throws FileSystemException if an error occurs.
169      * @see #getType()
170      * @see FileType#FILE
171      * @since 2.1
172      */
173     boolean isFile() throws FileSystemException;
174 
175     /**
176      * Returns the requested or current type of this name.
177      * <p>
178      * The "requested" type is the one determined during resolving the name. In this case the name is a
179      * {@link FileType#FOLDER} if it ends with an "/" else it will be a {@link FileType#FILE}.
180      * </p>
181      * <p>
182      * Once attached it will be changed to reflect the real type of this resource.
183      * </p>
184      *
185      * @return {@link FileType#FOLDER} or {@link FileType#FILE}
186      */
187     FileType getType();
188 
189     /**
190      * Returns a "friendly path", this is a path without a password.
191      * <p>
192      * This path can not be used to resolve the path again.
193      * </p>
194      *
195      * @return the friendly URI as a String.
196      */
197     String getFriendlyURI();
198 }