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