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 }