FileSystem


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.io.File  ;
19  
20  /**
21   * A file system, made up of a hierarchy of files.
22   *
23   * @author <a HREF="mailto:adammurdoch@apache.org">Adam Murdoch</a>
24   */
25  public interface FileSystem
26  {
27      /**
28       * Returns the root file of this file system.
29       */
30      FileObject getRoot() throws FileSystemException;
31  
32      /**
33       * Returns the name of the root file of this file system.
34       */
35      FileName getRootName();
36  
37      /**
38       * Determines if this file system has a particular capability.
39       *
40       * @param capability The capability to check for.
41       * @return true if this filesystem has the requested capability.
42       *         Note that not all files in the file system may have the
43       *         capability.
44       * @todo Move this to another interface, so that set of capabilities can be queried.
45       */
46      boolean hasCapability(Capability capability);
47  
48      /**
49       * Returns the parent layer if this is a layered file system.
50       *
51       * @return The parent layer, or null if this is not a layered file system.
52       */
53      FileObject getParentLayer() throws FileSystemException;
54  
55      /**
56       * Gets the value of an attribute of the file system.
57       * <p/>
58       * <p>TODO - change to <code>Map getAttributes()</code> instead?
59       * <p/>
60       * <p>TODO - define the standard attribute names, and define which attrs
61       * are guaranteed to be present.
62       *
63       * @param attrName The name of the attribute.
64       * @return The value of the attribute.
65       * @throws org.apache.commons.vfs.FileSystemException
66       *          If the file does not exist, or is being written, or if the
67       *          attribute is unknown.
68       * @see org.apache.commons.vfs.FileContent#getAttribute
69       */
70      Object   getAttribute(String   attrName) throws FileSystemException;
71  
72      /**
73       * Sets the value of an attribute of the file's content.  Creates the
74       * file if it does not exist.
75       *
76       * @param attrName The name of the attribute.
77       * @param value    The value of the attribute.
78       * @throws FileSystemException If the file is read-only, or is being read, or if the attribute
79       *                             is not supported, or on error setting the attribute.
80       * @see FileContent#setAttribute
81       */
82      void setAttribute(String   attrName, Object   value)
83          throws FileSystemException;
84  
85      /**
86       * Finds a file in this file system.
87       *
88       * @param name The name of the file.
89       * @return The file.  Never returns null.
90       */
91      FileObject resolveFile(FileName name) throws FileSystemException;
92  
93      /**
94       * Finds a file in this file system.
95       *
96       * @param name The name of the file.  This must be an absolute path.
97       * @return The file.  Never returns null.
98       */
99      FileObject resolveFile(String   name) throws FileSystemException;
100 
101     /**
102      * Adds a listener on a file in this file system.
103      *
104      * @param file     The file to attach the listener to.
105      * @param listener The listener to add.
106      */
107     void addListener(FileObject file, FileListener listener);
108 
109     /**
110      * Removes a listener from a file in this file system.
111      *
112      * @param file     The file to remove the listener from.
113      * @param listener The listener to remove.
114      */
115     void removeListener(FileObject file, FileListener listener);
116 
117     /**
118      * Adds a junction to this file system.  A junction is a link that attaches
119      * the supplied file to a point in this file system, making it look like
120      * part of the file system.
121      *
122      * @param junctionPoint The point in this file system to add the junction.
123      * @param targetFile    The file to link to.
124      * @throws FileSystemException If this file system does not support junctions, or the junction
125      *                             point or target file is invalid (the file system may not support
126      *                             nested junctions, for example).
127      */
128     void addJunction(String   junctionPoint, FileObject targetFile)
129         throws FileSystemException;
130 
131     /**
132      * Removes a junction from this file system.
133      *
134      * @param junctionPoint The junction to remove.
135      * @throws FileSystemException On error removing the junction.
136      */
137     void removeJunction(String   junctionPoint) throws FileSystemException;
138 
139     /**
140      * Creates a temporary local copy of a file and its descendents.  If
141      * this file is already a local file, a copy is not made.
142      * <p/>
143      * <p>Note that the local copy may include additonal files, that were
144      * not selected by the given selector.
145      *
146      * @param file     The file to replicate.
147      * @param selector The selector to use to select the files to replicate.
148      * @return The local copy of this file.
149      * @throws FileSystemException If this file does not exist, or on error replicating the file.
150      * @todo Add options to indicate whether the caller is happy to deal with
151      * extra files being present locally (eg if the file has been
152      * replicated previously), or whether the caller expects only
153      * the selected files to be present.
154      */
155     File   replicateFile(FileObject file, FileSelector selector)
156         throws FileSystemException;
157 
158     /**
159      * Returns the FileSystemOptions used to instantiate this filesystem
160      */
161     FileSystemOptions getFileSystemOptions();
162 
163     /**
164      * Returns a reference to the FileSytemManager
165      */
166     FileSystemManager getFileSystemManager();
167 
168     /**
169      * Returns the accuracy of the last modification time
170      *
171      * @return ms 0 perfectly accurate, >0 might be off by this value e.g. sftp 1000ms
172      */
173     double getLastModTimeAccuracy();
174 }
175
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags