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.File;
020
021/**
022 * A file system, made up of a hierarchy of files.
023 */
024public interface FileSystem {
025
026    /**
027     * Adds a junction to this file system. A junction is a link that attaches the supplied file to a point in this file
028     * system, making it look like part of the file system.
029     *
030     * @param junctionPoint The point in this file system to add the junction.
031     * @param targetFile The file to link to.
032     * @throws FileSystemException If this file system does not support junctions, or the junction point or target file
033     *             is invalid (the file system may not support nested junctions, for example).
034     */
035    void addJunction(String junctionPoint, FileObject targetFile) throws FileSystemException;
036
037    /**
038     * Adds a listener on a file in this file system.
039     *
040     * @param file The file to attach the listener to.
041     * @param listener The listener to add.
042     */
043    void addListener(FileObject file, FileListener listener);
044
045    /**
046     * Gets the value of an attribute of the file system.
047     * <p>
048     * TODO - change to {@code Map getAttributes()} instead?
049     * </p>
050     * <p>
051     * TODO - define the standard attribute names, and define which attrs are guaranteed to be present.
052     * </p>
053     *
054     * @param attrName The name of the attribute.
055     * @return The value of the attribute.
056     * @throws org.apache.commons.vfs2.FileSystemException If the file does not exist, or is being written, or if the
057     *             attribute is unknown.
058     * @see org.apache.commons.vfs2.FileContent#getAttribute
059     */
060    Object getAttribute(String attrName) throws FileSystemException;
061
062    /**
063     * Returns a reference to the FileSystemManager.
064     *
065     * @return The FileSystemManager.
066     */
067    FileSystemManager getFileSystemManager();
068
069    /**
070     * Returns the FileSystemOptions used to instantiate this file system.
071     *
072     * @return The FileSystemOptions.
073     */
074    FileSystemOptions getFileSystemOptions();
075
076    /**
077     * Returns the accuracy of the last modification time in milliseconds.
078     * <p>
079     * The local file provider is not very smart in figuring this out, for remote access to file systems the providers
080     * typically don't know the value of the underlying real file system.
081     * </p>
082     *
083     * @return the accuracy of the last modification time in milliseconds. A value of 0 means perfectly accurate,
084     *         anything {@literal > 0} might be off by this value. For example, sftp has an accuracy of 1000
085     *         milliseconds.
086     */
087    double getLastModTimeAccuracy();
088
089    /**
090     * Returns the parent layer if this is a layered file system.
091     *
092     * @return The parent layer, or null if this is not a layered file system.
093     * @throws FileSystemException if an error occurs.
094     */
095    FileObject getParentLayer() throws FileSystemException;
096
097    /**
098     * Returns the root file of this file system.
099     *
100     * @return The root FileObject.
101     * @throws FileSystemException if an error occurs.
102     */
103    FileObject getRoot() throws FileSystemException;
104
105    /**
106     * Returns the name of the root file of this file system. The root name always contains a path String of "/".
107     *
108     * @return the root FileName.
109     */
110    FileName getRootName();
111
112    /**
113     * The root URI passed as a file system option or obtained from the rootName.
114     *
115     * @return The root URI.
116     */
117    String getRootURI();
118
119    /**
120     * Determines if this file system has a particular capability.
121     * <p>
122     * TODO - Move this to another interface, so that set of capabilities can be queried.
123     * </p>
124     *
125     * @param capability The capability to check for.
126     * @return true if this file system has the requested capability. Note that not all files in the file system may have
127     *         the capability.
128     */
129    boolean hasCapability(Capability capability);
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     * Removes a listener from a file in this file system.
141     *
142     * @param file The file to remove the listener from.
143     * @param listener The listener to remove.
144     */
145    void removeListener(FileObject file, FileListener listener);
146
147    /**
148     * Creates a temporary local copy of a file and its descendants. If this file is already a local file, a copy is not
149     * made.
150     * <p>
151     * Note that the local copy may include additional files, that were not selected by the given selector.
152     * </p>
153     * <p>
154     * TODO - Add options to indicate whether the caller is happy to deal with extra files being present locally (eg if
155     * the file has been replicated previously), or whether the caller expects only the selected files to be present.
156     * </p>
157     *
158     * @param file The file to replicate.
159     * @param selector The selector to use to select the files to replicate.
160     * @return The local copy of this file.
161     * @throws FileSystemException If this file does not exist, or on error replicating the file.
162     */
163    File replicateFile(FileObject file, FileSelector selector) throws FileSystemException;
164
165    /**
166     * Finds a file in this file system.
167     *
168     * @param name The name of the file.
169     * @return The file. Never returns null.
170     * @throws FileSystemException if an error occurs.
171     */
172    FileObject resolveFile(FileName name) throws FileSystemException;
173
174    /**
175     * Finds a file in this file system.
176     *
177     * @param name The name of the file. This must be an absolute path.
178     * @return The file. Never returns null.
179     * @throws FileSystemException if an error occurs.
180     */
181    FileObject resolveFile(String name) throws FileSystemException;
182
183    /**
184     * Sets the value of an attribute of the file's content. Creates the file if it does not exist.
185     *
186     * @param attrName The name of the attribute.
187     * @param value The value of the attribute.
188     * @throws FileSystemException If the file is read-only, or is being read, or if the attribute is not supported, or
189     *             on error setting the attribute.
190     * @see FileContent#setAttribute
191     */
192    void setAttribute(String attrName, Object value) throws FileSystemException;
193}