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
21   * keys in hash tables.
22   *
23   * @see FileObject
24   */
25  public interface FileName extends Comparable<FileName>
26  {
27      /**
28       * The separator character used in file paths.
29       */
30      char SEPARATOR_CHAR = '/';
31  
32      /**
33       * The separator used in file paths.
34       */
35      String SEPARATOR = "/";
36  
37      /**
38       * The absolute path of the root of a file system.
39       */
40      String ROOT_PATH = "/";
41  
42      /**
43       * Returns the base name of this file.  The base name is the last element
44       * of the file name.  For example the base name of
45       * {@code /somefolder/somefile} is {@code somefile}.
46       * <p>
47       * The root file of a file system has an empty base name.
48       * </p>
49       *
50       * @return The base name.  Never returns null.
51       */
52      String getBaseName();
53  
54      /**
55       * Returns the absolute path of this file, within its file system.  This
56       * path is normalized, so that {@code .} and {@code ..} elements
57       * have been removed.  Also, the path only contains {@code /} as its
58       * separator character.  The path always starts with {@code /}
59       * <p>
60       * The root of a file system has {@code /} as its absolute path.
61       * </p>
62       *
63       * @return The path.  Never returns null.
64       */
65      String getPath();
66  
67      /**
68       * Returns the absolute path of this file, within its file system.  This
69       * path is normalized, so that {@code .} and {@code ..} elements
70       * have been removed.  Also, the path only contains {@code /} as its
71       * separator character.  The path always starts with {@code /}
72       * <p>
73       * The root of a file system has {@code /} as its absolute path.
74       * </p>
75       * <p>
76       * In contrast to {@link #getPath()} the path is decoded i.e. all %nn stuff
77       * replaced by its character.
78       * </p>
79       *
80       * @return The path.  Never returns null.
81       * @throws FileSystemException if the path is not correctly encoded
82       */
83      String getPathDecoded() throws FileSystemException;
84  
85      /**
86       * Returns the extension of this file name.
87       *
88       * @return The extension.  Returns an empty string if the name has no
89       *         extension.
90       */
91      String getExtension();
92  
93      /**
94       * Returns the depth of this file name, within its file system.  The depth
95       * of the root of a file system is 0.  The depth of any other file is
96       * 1 + the depth of its parent.
97       *
98       * @return The depth of this file name.
99       */
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.
208      * <p>
209      * The "requested" type is the one determined during resolving the name.
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}.
212      * <p>
213      * Once attached it will be changed to reflect the real type of this resource.
214      *
215      * @return {@link FileType#FOLDER} or {@link FileType#FILE}
216      */
217     FileType getType();
218 
219     /**
220      * Returns a "friendly path", this is a path without a password.
221      * <p>
222      * This path can not be used to resolve the path again.
223      *
224      * @return the friendly URI as a String.
225      */
226     String getFriendlyURI();
227 }