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