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  import java.net.URL;
20  import java.util.List;
21  
22  import org.apache.commons.vfs.operations.FileOperations;
23  
24  /***
25   * Represents a file, and is used to access the content and
26   * structure of the file.
27   * <p/>
28   * <p>Files are arranged in a hierarchy.  Each hierachy forms a
29   * <i>file system</i>.  A file system represents things like a local OS
30   * file system, a windows share, an HTTP server, or the contents of a Zip file.
31   * <p/>
32   * <p>There are two types of files: <i>Folders</i>, which contain other files,
33   * and <i>normal files</i>, which contain data, or <i>content</i>.  A folder may
34   * not have any content, and a normal file cannot contain other files.
35   * <p/>
36   * <h4>File Naming</h4>
37   * <p/>
38   * <p>TODO - write this.
39   * <p/>
40   * <h4>Reading and Writing a File</h4>
41   * <p/>
42   * <p>Reading and writing a file, and all other operations on the file's
43   * <i>content</i>, is done using the {@link FileContent} object returned
44   * by {@link #getContent}.
45   * <p/>
46   * <h4>Creating and Deleting a File</h4>
47   * <p/>
48   * <p>A file is created using either {@link #createFolder}, {@link #createFile},
49   * or by writing to the file using one of the {@link FileContent} methods.
50   * <p/>
51   * <p>A file is deleted using {@link #delete}.  Recursive deletion can be
52   * done using {@link #delete(FileSelector)}.
53   * <p/>
54   * <h4>Finding Files</h4>
55   * <p/>
56   * <p>Other files in the <i>same</i> file system as this file can be found
57   * using:
58   * <ul>
59   * <li>{@link #resolveFile} to find another file relative to this file.
60   * <li>{@link #getChildren} and {@link #getChild} to find the children of this file.
61   * <li>{@link #getParent} to find the folder containing this file.
62   * <li>{@link #getFileSystem} to find another file in the same file system.
63   * </ul>
64   * <p/>
65   * <p>To find files in another file system, use a {@link FileSystemManager}.
66   *
67   * @author <a href="mailto:adammurdoch@apache.org">Adam Murdoch</a>
68   * @version $Revision: 483899 $ $Date: 2006-12-08 10:47:09 +0100 (Fr, 08 Dez 2006) $
69   * @see FileSystemManager
70   * @see FileContent
71   * @see FileName
72   */
73  public interface FileObject
74  {
75      /***
76       * Returns the name of this file.
77       */
78      public FileName getName();
79  
80      /***
81       * Returns a URL representing this file.
82       */
83      public URL getURL() throws FileSystemException;
84  
85      /***
86       * Determines if this file exists.
87       *
88       * @return <code>true</code> if this file exists, <code>false</code> if not.
89       * @throws FileSystemException On error determining if this file exists.
90       */
91      public boolean exists() throws FileSystemException;
92  
93      /***
94       * Determines if this file is hidden.
95       *
96       * @return <code>true</code> if this file is hidden, <code>false</code> if not.
97       * @throws FileSystemException On error determining if this file exists.
98       */
99      public boolean isHidden() throws FileSystemException;
100 
101     /***
102      * Determines if this file can be read.
103      *
104      * @return <code>true</code> if this file is readable, <code>false</code> if not.
105      * @throws FileSystemException On error determining if this file exists.
106      */
107     public boolean isReadable() throws FileSystemException;
108 
109     /***
110      * Determines if this file can be written to.
111      *
112      * @return <code>true</code> if this file is writeable, <code>false</code> if not.
113      * @throws FileSystemException On error determining if this file exists.
114      */
115     public boolean isWriteable() throws FileSystemException;
116 
117     /***
118      * Returns this file's type.
119      *
120      * @return One of the {@link FileType} constants.  Never returns null.
121      * @throws FileSystemException On error determining the file's type.
122      */
123     public FileType getType() throws FileSystemException;
124 
125     /***
126      * Returns the folder that contains this file.
127      *
128      * @return The folder that contains this file.  Returns null if this file is
129      *         the root of a file system.
130      * @throws FileSystemException On error finding the file's parent.
131      */
132     public FileObject getParent() throws FileSystemException;
133 
134     /***
135      * Returns the file system that contains this file.
136      *
137      * @return The file system.
138      */
139     public FileSystem getFileSystem();
140 
141     /***
142      * Lists the children of this file.
143      *
144      * @return An array containing the children of this file.  The array is
145      *         unordered.  If the file does not have any children, a zero-length
146      *         array is returned.  This method never returns null.
147      * @throws FileSystemException If this file does not exist, or is not a folder, or on error
148      *                             listing this file's children.
149      */
150     public FileObject[] getChildren() throws FileSystemException;
151 
152     /***
153      * Returns a child of this file.  Note that this method returns <code>null</code>
154      * when the child does not exist.  This differs from
155      * {@link #resolveFile( String, NameScope)} which never returns null.
156      *
157      * @param name The name of the child.
158      * @return The child, or null if there is no such child.
159      * @throws FileSystemException If this file does not exist, or is not a folder, or on error
160      *                             determining this file's children.
161      */
162     public FileObject getChild(String name) throws FileSystemException;
163 
164     /***
165      * Finds a file, relative to this file.  Refer to {@link NameScope}
166      * for a description of how names are resolved in the different scopes.
167      *
168      * @param name The name to resolve.
169      * @return The file.
170      * @throws FileSystemException On error parsing the path, or on error finding the file.
171      */
172     public FileObject resolveFile(String name, NameScope scope)
173         throws FileSystemException;
174 
175     /***
176      * Finds a file, relative to this file.  Equivalent to calling
177      * <code>resolveFile( path, NameScope.FILE_SYSTEM )</code>.
178      *
179      * @param path The path of the file to locate.  Can either be a relative
180      *             path or an absolute path.
181      * @return The file.
182      * @throws FileSystemException On error parsing the path, or on error finding the file.
183      */
184     public FileObject resolveFile(String path) throws FileSystemException;
185 
186     /***
187      * Finds the set of matching descendents of this file, in depthwise order.
188      *
189      * @param selector The selector to use to select matching files.
190      * @return The matching files.  The files are returned in depthwise order
191      *         (that is, a child appears in the list before its parent).
192      */
193     public FileObject[] findFiles(FileSelector selector) throws FileSystemException;
194 
195     /***
196          * Finds the set of matching descendents of this file.
197          *
198          * @param selector  the selector used to determine if the file should be selected
199          * @param depthwise controls the ordering in the list. e.g. deepest first
200          * @param selected  container for selected files. list needs not to be empty.
201          * @throws FileSystemException
202          */
203     public void findFiles(FileSelector selector,
204                    boolean depthwise,
205                    List selected) throws FileSystemException;
206 
207     /***
208      * Deletes this file.  Does nothing if this file does not exist of if it is a
209      * folder that has children.  Does not delete any descendents of this file,
210      * use {@link #delete(FileSelector)} for that.
211      *
212      * @return true if this object has been deleted
213      * @throws FileSystemException If this file is a non-empty folder, or if this file is read-only,
214      *                             or on error deleteing this file.
215      */
216     public boolean delete() throws FileSystemException;
217 
218     /***
219      * Deletes all descendents of this file that match a selector.  Does
220      * nothing if this file does not exist.
221      * <p/>
222      * <p>This method is not transactional.  If it fails and throws an
223      * exception, this file will potentially only be partially deleted.
224      *
225      * @param selector The selector to use to select which files to delete.
226      * @return the number of deleted objects
227      * @throws FileSystemException If this file or one of its descendents is read-only, or on error
228      *                             deleting this file or one of its descendents.
229      */
230     public int delete(FileSelector selector) throws FileSystemException;
231 
232     /***
233      * Creates this folder, if it does not exist.  Also creates any ancestor
234      * folders which do not exist.  This method does nothing if the folder
235      * already exists.
236      *
237      * @throws FileSystemException If the folder already exists with the wrong type, or the parent
238      *                             folder is read-only, or on error creating this folder or one of
239      *                             its ancestors.
240      */
241     public void createFolder() throws FileSystemException;
242 
243     /***
244      * Creates this file, if it does not exist.  Also creates any ancestor
245      * folders which do not exist.  This method does nothing if the file
246      * already exists and is a file.
247      *
248      * @throws FileSystemException If the file already exists with the wrong type, or the parent
249      *                             folder is read-only, or on error creating this file or one of
250      *                             its ancestors.
251      */
252     public void createFile() throws FileSystemException;
253 
254     /***
255      * Copies another file, and all its descendents, to this file.
256      * <p/>
257      * If this file does not exist, it is created.  Its parent folder is also
258      * created, if necessary.  If this file does exist, it is deleted first.
259      * <p/>
260      * <p>This method is not transactional.  If it fails and throws an
261      * exception, this file will potentially only be partially copied.
262      *
263      * @param srcFile  The source file to copy.
264      * @param selector The selector to use to select which files to copy.
265      * @throws FileSystemException If this file is read-only, or if the source file does not exist,
266      *                             or on error copying the file.
267      */
268     public void copyFrom(FileObject srcFile, FileSelector selector)
269         throws FileSystemException;
270 
271     /***
272      * Move this file.
273      * <p>If the destFile exists, it is deleted first</b> 
274      *
275      * @param destFile the New filename.
276      * @throws FileSystemException If this file is read-only, or if the source file does not exist,
277      *                             or on error copying the file.
278      */
279     public void moveTo(FileObject destFile)
280         throws FileSystemException;
281 
282     /***
283      * Queries the file if it is possible to rename it to newfile.
284      *
285      * @param newfile the new file(-name)
286      * @return true it this is the case
287      */
288     public boolean canRenameTo(FileObject newfile);
289 
290     /***
291      * Returns this file's content.  The {@link FileContent} returned by this
292      * method can be used to read and write the content of the file.
293      * <p/>
294      * <p>This method can be called if the file does not exist, and
295      * the returned {@link FileContent} can be used to create the file
296      * by writing its content.
297      *
298      * @return This file's content.
299      * @throws FileSystemException On error getting this file's content.
300      */
301     public FileContent getContent() throws FileSystemException;
302 
303     /***
304      * Closes this file, and its content.  This method is a hint to the
305      * implementation that it can release any resources associated with
306      * the file.
307      * <p/>
308      * <p>The file object can continue to be used after this method is called.
309      *
310      * @throws FileSystemException On error closing the file.
311      * @see FileContent#close
312      */
313     public void close() throws FileSystemException;
314 
315     /***
316      * This will prepare the fileObject to get resynchronized with the underlaying filesystem if required 
317      */
318     public void refresh() throws FileSystemException;
319 
320     /***
321      * check if the fileObject is attaced
322      */
323 	public boolean isAttached();
324 
325 	/***
326 	 * check if someone reads/write to this file
327 	 */
328 	public boolean isContentOpen();
329 
330 	
331 	// --- OPERATIONS --
332 	/***
333 	 * @return FileOperations interface that provides access to the operations API.
334 	 * @throws FileSystemException
335 	 */
336 	FileOperations getFileOperations() throws FileSystemException;
337 }