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