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