FileObject


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