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 }