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.vfs;
018:
019: import java.net.URL;
020: import java.util.List;
021:
022: import org.apache.commons.vfs.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="mailto:adammurdoch@apache.org">Adam Murdoch</a>
068: * @version $Revision: 483899 $ $Date: 2006-12-08 01:47:09 -0800 (Fri, 08 Dec 2006) $
069: * @see FileSystemManager
070: * @see FileContent
071: * @see FileName
072: */
073: public interface FileObject {
074: /**
075: * Returns the name of this file.
076: */
077: public FileName getName();
078:
079: /**
080: * Returns a URL representing this file.
081: */
082: public URL getURL() throws FileSystemException;
083:
084: /**
085: * Determines if this file exists.
086: *
087: * @return <code>true</code> if this file exists, <code>false</code> if not.
088: * @throws FileSystemException On error determining if this file exists.
089: */
090: public boolean exists() throws FileSystemException;
091:
092: /**
093: * Determines if this file is hidden.
094: *
095: * @return <code>true</code> if this file is hidden, <code>false</code> if not.
096: * @throws FileSystemException On error determining if this file exists.
097: */
098: public boolean isHidden() throws FileSystemException;
099:
100: /**
101: * Determines if this file can be read.
102: *
103: * @return <code>true</code> if this file is readable, <code>false</code> if not.
104: * @throws FileSystemException On error determining if this file exists.
105: */
106: public boolean isReadable() throws FileSystemException;
107:
108: /**
109: * Determines if this file can be written to.
110: *
111: * @return <code>true</code> if this file is writeable, <code>false</code> if not.
112: * @throws FileSystemException On error determining if this file exists.
113: */
114: public boolean isWriteable() throws FileSystemException;
115:
116: /**
117: * Returns this file's type.
118: *
119: * @return One of the {@link FileType} constants. Never returns null.
120: * @throws FileSystemException On error determining the file's type.
121: */
122: public FileType getType() throws FileSystemException;
123:
124: /**
125: * Returns the folder that contains this file.
126: *
127: * @return The folder that contains this file. Returns null if this file is
128: * the root of a file system.
129: * @throws FileSystemException On error finding the file's parent.
130: */
131: public FileObject getParent() throws FileSystemException;
132:
133: /**
134: * Returns the file system that contains this file.
135: *
136: * @return The file system.
137: */
138: public FileSystem getFileSystem();
139:
140: /**
141: * Lists the children of this file.
142: *
143: * @return An array containing the children of this file. The array is
144: * unordered. If the file does not have any children, a zero-length
145: * array is returned. This method never returns null.
146: * @throws FileSystemException If this file does not exist, or is not a folder, or on error
147: * listing this file's children.
148: */
149: public FileObject[] getChildren() throws FileSystemException;
150:
151: /**
152: * Returns a child of this file. Note that this method returns <code>null</code>
153: * when the child does not exist. This differs from
154: * {@link #resolveFile( String, NameScope)} which never returns null.
155: *
156: * @param name The name of the child.
157: * @return The child, or null if there is no such child.
158: * @throws FileSystemException If this file does not exist, or is not a folder, or on error
159: * determining this file's children.
160: */
161: public FileObject getChild(String name) throws FileSystemException;
162:
163: /**
164: * Finds a file, relative to this file. Refer to {@link NameScope}
165: * for a description of how names are resolved in the different scopes.
166: *
167: * @param name The name to resolve.
168: * @return The file.
169: * @throws FileSystemException On error parsing the path, or on error finding the file.
170: */
171: public FileObject resolveFile(String name, NameScope scope)
172: throws FileSystemException;
173:
174: /**
175: * Finds a file, relative to this file. Equivalent to calling
176: * <code>resolveFile( path, NameScope.FILE_SYSTEM )</code>.
177: *
178: * @param path The path of the file to locate. Can either be a relative
179: * path or an absolute path.
180: * @return The file.
181: * @throws FileSystemException On error parsing the path, or on error finding the file.
182: */
183: public FileObject resolveFile(String path)
184: 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)
194: throws FileSystemException;
195:
196: /**
197: * Finds the set of matching descendents of this file.
198: *
199: * @param selector the selector used to determine if the file should be selected
200: * @param depthwise controls the ordering in the list. e.g. deepest first
201: * @param selected container for selected files. list needs not to be empty.
202: * @throws FileSystemException
203: */
204: public void findFiles(FileSelector selector, 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) throws FileSystemException;
280:
281: /**
282: * Queries the file if it is possible to rename it to newfile.
283: *
284: * @param newfile the new file(-name)
285: * @return true it this is the case
286: */
287: public boolean canRenameTo(FileObject newfile);
288:
289: /**
290: * Returns this file's content. The {@link FileContent} returned by this
291: * method can be used to read and write the content of the file.
292: * <p/>
293: * <p>This method can be called if the file does not exist, and
294: * the returned {@link FileContent} can be used to create the file
295: * by writing its content.
296: *
297: * @return This file's content.
298: * @throws FileSystemException On error getting this file's content.
299: */
300: public FileContent getContent() throws FileSystemException;
301:
302: /**
303: * Closes this file, and its content. This method is a hint to the
304: * implementation that it can release any resources associated with
305: * the file.
306: * <p/>
307: * <p>The file object can continue to be used after this method is called.
308: *
309: * @throws FileSystemException On error closing the file.
310: * @see FileContent#close
311: */
312: public void close() throws FileSystemException;
313:
314: /**
315: * This will prepare the fileObject to get resynchronized with the underlaying filesystem if required
316: */
317: public void refresh() throws FileSystemException;
318:
319: /**
320: * check if the fileObject is attaced
321: */
322: public boolean isAttached();
323:
324: /**
325: * check if someone reads/write to this file
326: */
327: public boolean isContentOpen();
328:
329: // --- OPERATIONS --
330: /**
331: * @return FileOperations interface that provides access to the operations API.
332: * @throws FileSystemException
333: */
334: FileOperations getFileOperations() throws FileSystemException;
335: }
|