FileName


1   /*
2    * Copyright 2002-2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.vfs;
17  
18  /**
19   * Represents a file name.  File names are immutable, and work correctly as
20   * keys in hash tables.
21   *
22   * @author <a HREF="mailto:adammurdoch@apache.org">Adam Murdoch</a>
23   * @see FileObject
24   */
25  public interface FileName extends Comparable  
26  {
27      /**
28       * The separator character used in file paths.
29       */
30      public final char SEPARATOR_CHAR = '/';
31  
32      /**
33       * The separator used in file paths.
34       */
35      public final String   SEPARATOR = "/";
36  
37      /**
38       * The absolute path of the root of a file system.
39       */
40      public final 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</code> is <code>somefile</code>.
46       * <p/>
47       * <p>The root file of a file system has an empty base name.
48       *
49       * @return The base name.  Never returns null.
50       */
51      public String   getBaseName();
52  
53      /**
54       * Returns the absolute path of this file, within its file system.  This
55       * path is normalised, so that <code>.</code> and <code>..</code> elements
56       * have been removed.  Also, the path only contains <code>/</code> as its
57       * separator character.  The path always starts with <code>/</code>
58       * <p/>
59       * <p>The root of a file system has <code>/</code> as its absolute path.
60       *
61       * @return The path.  Never returns null.
62       */
63      public String   getPath();
64  
65      /**
66       * Returns the absolute path of this file, within its file system.  This
67       * path is normalised, so that <code>.</code> and <code>..</code> elements
68       * have been removed.  Also, the path only contains <code>/</code> as its
69       * separator character.  The path always starts with <code>/</code>
70       * <p/>
71       * <p>The root of a file system has <code>/</code> as its absolute path.
72       * <p/>
73       * In contrast to {@link #getPath()} the path is decoded i.e. all %nn stuff
74       * replaced by its character.
75       *
76       * @return The path.  Never returns null.
77       * @throws FileSystemException if the path is not correctly encoded
78       */
79      public String   getPathDecoded() throws FileSystemException;
80  
81      /**
82       * Returns the extension of this file name.
83       *
84       * @return The extension.  Returns an empty string if the name has no
85       *         extension.
86       */
87      public String   getExtension();
88  
89      /**
90       * Returns the depth of this file name, within its file system.  The depth
91       * of the root of a file system is 0.  The depth of any other file is
92       * 1 + the depth of its parent.
93       */
94      public int getDepth();
95  
96      /**
97       * Returns the URI scheme of this file.
98       */
99      public String   getScheme();
100 
101     /**
102      * Returns the absolute URI of this file.
103      */
104     public String   getURI();
105 
106     /**
107      * Returns the root URI of the file system this file belongs to.
108      */
109     public String   getRootURI();
110 
111     /**
112      * find the root of the filesystem
113      */
114     public FileName getRoot();
115 
116     /**
117      * Returns the file name of the parent of this file.  The root of a
118      * file system has no parent.
119      *
120      * @return A {@link FileName} object representing the parent name.  Returns
121      *         null for the root of a file system.
122      */
123     public FileName getParent();
124 
125     /**
126      * Resolves a name, relative to this file name.  Equivalent to calling
127      * <code>resolveName( path, NameScope.FILE_SYSTEM )</code>.
128      *
129      * @param name The name to resolve.
130      * @return A {@link FileName} object representing the resolved file name.
131      * @throws FileSystemException If the name is invalid.
132      */
133     // FileName resolveName(String name) throws FileSystemException;
134 
135     /**
136      * Resolves a name, relative to this file name.  Refer to {@link NameScope}
137      * for a description of how names are resolved.
138      *
139      * @param name  The name to resolve.
140      * @param scope The scope to use when resolving the name.
141      * @return A {@link FileName} object representing the resolved file name.
142      * @throws FileSystemException If the name is invalid.
143      */
144     // FileName resolveName(String name, NameScope scope)
145     //     throws FileSystemException;
146 
147     /**
148      * Converts a file name to a relative name, relative to this file name.
149      *
150      * @param name The name to convert to a relative path.
151      * @return The relative name.
152      * @throws FileSystemException On error.
153      */
154     public String   getRelativeName(FileName name) throws FileSystemException;
155 
156     /**
157      * Determines if another file name is an ancestor of this file name.
158      */
159     public boolean isAncestor(FileName ancestor);
160 
161     /**
162      * Determines if another file name is a descendent of this file name.
163      */
164     public boolean isDescendent(FileName descendent);
165 
166     /**
167      * Determines if another file name is a descendent of this file name.
168      */
169     public boolean isDescendent(FileName descendent, NameScope nameScope);
170 
171     /**
172      * Returns the requested or current type of this name. <br />
173      * <p/>
174      * The "requested" type is the one determined during resolving the name. <br/>
175      * In this case the name is a {@link FileType#FOLDER} if it ends with an "/" else
176      * it will be a {@link FileType#FILE}<br/>
177      * </p>
178      * <p/>
179      * Once attached it will be changed to reflect the real type of this resource.
180      * </p>
181      *
182      * @return {@link FileType#FOLDER} or {@link FileType#FILE}
183      */
184     public FileType getType();
185 }
186
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags