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 */
017 package org.apache.commons.vfs2;
018
019 import java.net.URL;
020 import java.util.List;
021
022 import org.apache.commons.vfs2.operations.FileOperations;
023
024 /**
025 * Represents a file, and is used to access the content and
026 * structure of the file.
027 * <p/>
028 * <p>Files are arranged in a hierarchy. Each hierachy forms a
029 * <i>file system</i>. A file system represents things like a local OS
030 * file system, a windows share, an HTTP server, or the contents of a Zip file.
031 * <p/>
032 * <p>There are two types of files: <i>Folders</i>, which contain other files,
033 * and <i>normal files</i>, which contain data, or <i>content</i>. A folder may
034 * not have any content, and a normal file cannot contain other files.
035 * <p/>
036 * <h4>File Naming</h4>
037 * <p/>
038 * <p>TODO - write this.
039 * <p/>
040 * <h4>Reading and Writing a File</h4>
041 * <p/>
042 * <p>Reading and writing a file, and all other operations on the file's
043 * <i>content</i>, is done using the {@link FileContent} object returned
044 * by {@link #getContent}.
045 * <p/>
046 * <h4>Creating and Deleting a File</h4>
047 * <p/>
048 * <p>A file is created using either {@link #createFolder}, {@link #createFile},
049 * or by writing to the file using one of the {@link FileContent} methods.
050 * <p/>
051 * <p>A file is deleted using {@link #delete}. Recursive deletion can be
052 * done using {@link #delete(FileSelector)}.
053 * <p/>
054 * <h4>Finding Files</h4>
055 * <p/>
056 * <p>Other files in the <i>same</i> file system as this file can be found
057 * using:
058 * <ul>
059 * <li>{@link #resolveFile} to find another file relative to this file.
060 * <li>{@link #getChildren} and {@link #getChild} to find the children of this file.
061 * <li>{@link #getParent} to find the folder containing this file.
062 * <li>{@link #getFileSystem} to find another file in the same file system.
063 * </ul>
064 * <p/>
065 * <p>To find files in another file system, use a {@link FileSystemManager}.
066 *
067 * @author <a href="http://commons.apache.org/vfs/team-list.html">Commons VFS team</a>
068 * @see FileSystemManager
069 * @see FileContent
070 * @see FileName
071 */
072 public interface FileObject
073 {
074 /**
075 * Returns the name of this file.
076 * @return the FileName.
077 */
078 FileName getName();
079
080 /**
081 * Returns a URL representing this file.
082 * @return the URL for the file.
083 * @throws FileSystemException if an error occurs.
084 */
085 URL getURL() throws FileSystemException;
086
087 /**
088 * Determines if this file exists.
089 *
090 * @return <code>true</code> if this file exists, <code>false</code> if not.
091 * @throws FileSystemException On error determining if this file exists.
092 */
093 boolean exists() throws FileSystemException;
094
095 /**
096 * Determines if this file is hidden.
097 *
098 * @return <code>true</code> if this file is hidden, <code>false</code> if not.
099 * @throws FileSystemException On error determining if this file exists.
100 */
101 boolean isHidden() throws FileSystemException;
102
103 /**
104 * Determines if this file can be read.
105 *
106 * @return <code>true</code> if this file is readable, <code>false</code> if not.
107 * @throws FileSystemException On error determining if this file exists.
108 */
109 boolean isReadable() throws FileSystemException;
110
111 /**
112 * Determines if this file can be written to.
113 *
114 * @return <code>true</code> if this file is writeable, <code>false</code> if not.
115 * @throws FileSystemException On error determining if this file exists.
116 */
117 boolean isWriteable() throws FileSystemException;
118
119 /**
120 * Returns this file's type.
121 *
122 * @return One of the {@link FileType} constants. Never returns null.
123 * @throws FileSystemException On error determining the file's type.
124 */
125 FileType getType() throws FileSystemException;
126
127 /**
128 * Returns the folder that contains this file.
129 *
130 * @return The folder that contains this file. Returns null if this file is
131 * the root of a file system.
132 * @throws FileSystemException On error finding the file's parent.
133 */
134 FileObject getParent() throws FileSystemException;
135
136 /**
137 * Returns the file system that contains this file.
138 *
139 * @return The file system.
140 */
141 FileSystem getFileSystem();
142
143 /**
144 * Lists the children of this file.
145 *
146 * @return An array containing the children of this file. The array is
147 * unordered. If the file does not have any children, a zero-length
148 * array is returned. This method never returns null.
149 * @throws FileSystemException If this file does not exist, or is not a folder, or on error
150 * listing this file's children.
151 */
152 FileObject[] getChildren() throws FileSystemException;
153
154 /**
155 * Returns a child of this file. Note that this method returns <code>null</code>
156 * when the child does not exist. This differs from
157 * {@link #resolveFile( String, NameScope)} which never returns null.
158 *
159 * @param name The name of the child.
160 * @return The child, or null if there is no such child.
161 * @throws FileSystemException If this file does not exist, or is not a folder, or on error
162 * determining this file's children.
163 */
164 FileObject getChild(String name) throws FileSystemException;
165
166 /**
167 * Finds a file, relative to this file. Refer to {@link NameScope}
168 * for a description of how names are resolved in the different scopes.
169 *
170 * @param name The name to resolve.
171 * @param scope the NameScope for the file.
172 * @return The file.
173 * @throws FileSystemException On error parsing the path, or on error finding the file.
174 */
175 FileObject resolveFile(String name, NameScope scope)
176 throws FileSystemException;
177
178 /**
179 * Finds a file, relative to this file. Equivalent to calling
180 * <code>resolveFile( path, NameScope.FILE_SYSTEM )</code>.
181 *
182 * @param path The path of the file to locate. Can either be a relative
183 * path or an absolute path.
184 * @return The file.
185 * @throws FileSystemException On error parsing the path, or on error finding the file.
186 */
187 FileObject resolveFile(String path) throws FileSystemException;
188
189 /**
190 * Finds the set of matching descendents of this file, in depthwise order.
191 *
192 * @param selector The selector to use to select matching files.
193 * @return The matching files. The files are returned in depthwise order
194 * (that is, a child appears in the list before its parent).
195 * @throws FileSystemException if an error occurs.
196 */
197 FileObject[] findFiles(FileSelector selector) throws FileSystemException;
198
199 /**
200 * Finds the set of matching descendents of this file.
201 *
202 * @param selector the selector used to determine if the file should be selected
203 * @param depthwise controls the ordering in the list. e.g. deepest first
204 * @param selected container for selected files. list needs not to be empty.
205 * @throws FileSystemException if an error occurs.
206 */
207 void findFiles(FileSelector selector, boolean depthwise, List<FileObject> selected) throws FileSystemException;
208
209 /**
210 * Deletes this file. Does nothing if this file does not exist of if it is a
211 * folder that has children. Does not delete any descendents of this file,
212 * use {@link #delete(FileSelector)} for that.
213 *
214 * @return true if this object has been deleted
215 * @throws FileSystemException If this file is a non-empty folder, or if this file is read-only,
216 * or on error deleteing this file.
217 */
218 boolean delete() throws FileSystemException;
219
220 /**
221 * Deletes all descendents of this file that match a selector. Does
222 * nothing if this file does not exist.
223 * <p/>
224 * <p>This method is not transactional. If it fails and throws an
225 * exception, this file will potentially only be partially deleted.
226 *
227 * @param selector The selector to use to select which files to delete.
228 * @return the number of deleted objects
229 * @throws FileSystemException If this file or one of its descendents is read-only, or on error
230 * deleting this file or one of its descendents.
231 */
232 int delete(FileSelector selector) throws FileSystemException;
233
234 /**
235 * Creates this folder, if it does not exist. Also creates any ancestor
236 * folders which do not exist. This method does nothing if the folder
237 * already exists.
238 *
239 * @throws FileSystemException If the folder already exists with the wrong type, or the parent
240 * folder is read-only, or on error creating this folder or one of
241 * its ancestors.
242 */
243 void createFolder() throws FileSystemException;
244
245 /**
246 * Creates this file, if it does not exist. Also creates any ancestor
247 * folders which do not exist. This method does nothing if the file
248 * already exists and is a file.
249 *
250 * @throws FileSystemException If the file already exists with the wrong type, or the parent
251 * folder is read-only, or on error creating this file or one of
252 * its ancestors.
253 */
254 void createFile() throws FileSystemException;
255
256 /**
257 * Copies another file, and all its descendents, to this file.
258 * <p/>
259 * If this file does not exist, it is created. Its parent folder is also
260 * created, if necessary. If this file does exist, it is deleted first.
261 * <p/>
262 * <p>This method is not transactional. If it fails and throws an
263 * exception, this file will potentially only be partially copied.
264 *
265 * @param srcFile The source file to copy.
266 * @param selector The selector to use to select which files to copy.
267 * @throws FileSystemException If this file is read-only, or if the source file does not exist,
268 * or on error copying the file.
269 */
270 void copyFrom(FileObject srcFile, FileSelector selector)
271 throws FileSystemException;
272
273 /**
274 * Move this file.
275 * <p>If the destFile exists, it is deleted first</p>
276 *
277 * @param destFile the New filename.
278 * @throws FileSystemException If this file is read-only, or if the source file does not exist,
279 * or on error copying the file.
280 */
281 void moveTo(FileObject destFile)
282 throws FileSystemException;
283
284 /**
285 * Queries the file if it is possible to rename it to newfile.
286 *
287 * @param newfile the new file(-name)
288 * @return true it this is the case
289 */
290 boolean canRenameTo(FileObject newfile);
291
292 /**
293 * Returns this file's content. The {@link FileContent} returned by this
294 * method can be used to read and write the content of the file.
295 * <p/>
296 * <p>This method can be called if the file does not exist, and
297 * the returned {@link FileContent} can be used to create the file
298 * by writing its content.
299 *
300 * @return This file's content.
301 * @throws FileSystemException On error getting this file's content.
302 */
303 FileContent getContent() throws FileSystemException;
304
305 /**
306 * Closes this file, and its content. This method is a hint to the
307 * implementation that it can release any resources associated with
308 * the file.
309 * <p/>
310 * <p>The file object can continue to be used after this method is called.
311 *
312 * @throws FileSystemException On error closing the file.
313 * @see FileContent#close
314 */
315 void close() throws FileSystemException;
316
317 /**
318 * This will prepare the fileObject to get resynchronized with the underlaying filesystem if required.
319 * @throws FileSystemException if an error occurs.
320 */
321 void refresh() throws FileSystemException;
322
323 /**
324 * check if the fileObject is attaced.
325 * @return true if the FileObject is attached.
326 */
327 boolean isAttached();
328
329 /**
330 * check if someone reads/write to this file.
331 * @return true if the file content is open.
332 */
333 boolean isContentOpen();
334
335
336 // --- OPERATIONS --
337 /**
338 * @return FileOperations interface that provides access to the operations API.
339 * @throws FileSystemException if an error occurs.
340 */
341 FileOperations getFileOperations() throws FileSystemException;
342 }