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.vfs;
18  
19  /***
20   * Represents a file name.  File names are immutable, and work correctly as
21   * keys in hash tables.
22   *
23   * @author <a href="mailto:adammurdoch@apache.org">Adam Murdoch</a>
24   * @version $Revision: 480428 $ $Date: 2006-11-29 07:15:24 +0100 (Mi, 29 Nov 2006) $
25   * @see FileObject
26   */
27  public interface FileName extends Comparable
28  {
29      /***
30       * The separator character used in file paths.
31       */
32      public final char SEPARATOR_CHAR = '/';
33  
34      /***
35       * The separator used in file paths.
36       */
37      public final String SEPARATOR = "/";
38  
39      /***
40       * The absolute path of the root of a file system.
41       */
42      public final String ROOT_PATH = "/";
43  
44      /***
45       * Returns the base name of this file.  The base name is the last element
46       * of the file name.  For example the base name of
47       * <code>/somefolder/somefile</code> is <code>somefile</code>.
48       * <p/>
49       * <p>The root file of a file system has an empty base name.
50       *
51       * @return The base name.  Never returns null.
52       */
53      public String getBaseName();
54  
55      /***
56       * Returns the absolute path of this file, within its file system.  This
57       * path is normalised, so that <code>.</code> and <code>..</code> elements
58       * have been removed.  Also, the path only contains <code>/</code> as its
59       * separator character.  The path always starts with <code>/</code>
60       * <p/>
61       * <p>The root of a file system has <code>/</code> as its absolute path.
62       *
63       * @return The path.  Never returns null.
64       */
65      public String getPath();
66  
67      /***
68       * Returns the absolute path of this file, within its file system.  This
69       * path is normalised, so that <code>.</code> and <code>..</code> elements
70       * have been removed.  Also, the path only contains <code>/</code> as its
71       * separator character.  The path always starts with <code>/</code>
72       * <p/>
73       * <p>The root of a file system has <code>/</code> as its absolute path.
74       * <p/>
75       * In contrast to {@link #getPath()} the path is decoded i.e. all %nn stuff
76       * replaced by its character.
77       *
78       * @return The path.  Never returns null.
79       * @throws FileSystemException if the path is not correctly encoded
80       */
81      public String getPathDecoded() throws FileSystemException;
82  
83      /***
84       * Returns the extension of this file name.
85       *
86       * @return The extension.  Returns an empty string if the name has no
87       *         extension.
88       */
89      public String getExtension();
90  
91      /***
92       * Returns the depth of this file name, within its file system.  The depth
93       * of the root of a file system is 0.  The depth of any other file is
94       * 1 + the depth of its parent.
95       */
96      public int getDepth();
97  
98      /***
99       * Returns the URI scheme of this file.
100      */
101     public String getScheme();
102 
103     /***
104      * Returns the absolute URI of this file.
105      */
106     public String getURI();
107 
108     /***
109      * Returns the root URI of the file system this file belongs to.
110      */
111     public String getRootURI();
112 
113     /***
114      * find the root of the filesystem
115      */
116     public FileName getRoot();
117 
118     /***
119      * Returns the file name of the parent of this file.  The root of a
120      * file system has no parent.
121      *
122      * @return A {@link FileName} object representing the parent name.  Returns
123      *         null for the root of a file system.
124      */
125     public FileName getParent();
126 
127     /***
128      * Resolves a name, relative to this file name.  Equivalent to calling
129      * <code>resolveName( path, NameScope.FILE_SYSTEM )</code>.
130      *
131      * @param name The name to resolve.
132      * @return A {@link FileName} object representing the resolved file name.
133      * @throws FileSystemException If the name is invalid.
134      */
135     // FileName resolveName(String name) throws FileSystemException;
136 
137     /***
138      * Resolves a name, relative to this file name.  Refer to {@link NameScope}
139      * for a description of how names are resolved.
140      *
141      * @param name  The name to resolve.
142      * @param scope The scope to use when resolving the name.
143      * @return A {@link FileName} object representing the resolved file name.
144      * @throws FileSystemException If the name is invalid.
145      */
146     // FileName resolveName(String name, NameScope scope)
147     //     throws FileSystemException;
148 
149     /***
150      * Converts a file name to a relative name, relative to this file name.
151      *
152      * @param name The name to convert to a relative path.
153      * @return The relative name.
154      * @throws FileSystemException On error.
155      */
156     public String getRelativeName(FileName name) throws FileSystemException;
157 
158     /***
159      * Determines if another file name is an ancestor of this file name.
160      */
161     public boolean isAncestor(FileName ancestor);
162 
163     /***
164      * Determines if another file name is a descendent of this file name.
165      */
166     public boolean isDescendent(FileName descendent);
167 
168     /***
169      * Determines if another file name is a descendent of this file name.
170      */
171     public boolean isDescendent(FileName descendent, NameScope nameScope);
172 
173     /***
174      * Returns the requested or current type of this name. <br />
175      * <p/>
176      * The "requested" type is the one determined during resolving the name. <br/>
177      * In this case the name is a {@link FileType#FOLDER} if it ends with an "/" else
178      * it will be a {@link FileType#FILE}<br/>
179      * </p>
180      * <p/>
181      * Once attached it will be changed to reflect the real type of this resource.
182      * </p>
183      *
184      * @return {@link FileType#FOLDER} or {@link FileType#FILE}
185      */
186     public FileType getType();
187 
188     /***
189      * returns a "friendly path", this is a path without a password.<br />
190      * This path can not be used to resolve the path again
191      */
192     public String getFriendlyURI();
193 }