1/*
2 * Copyright 2008 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16package org.mockftpserver.fake.filesystem;
17
18import java.util.List;
19
20/**
21 * Interface for a file system for managing files and directories.
22 *
23 * @author Chris Mair
24 * @version $Revision$ - $Date$
25 */
26public interface FileSystem {
27
28    /**
29     * Add the specified file system entry (file or directory) to this file system
30     *
31     * @param entry - the FileSystemEntry to add
32     */
33    public void add(FileSystemEntry entry);
34
35    /**
36     * Return the List of FileSystemEntry objects for the files in the specified directory path. If the
37     * path does not refer to a valid directory, then an empty List is returned.
38     *
39     * @param path - the path of the directory whose contents should be returned
40     * @return the List of FileSystemEntry objects for all files in the specified directory may be empty
41     */
42    public List listFiles(String path);
43
44    /**
45     * Return the List of filenames in the specified directory path. The returned filenames do not
46     * include a path. If the path does not refer to a valid directory, then an empty List is
47     * returned.
48     *
49     * @param path - the path of the directory whose contents should be returned
50     * @return the List of filenames (not including paths) for all files in the specified directory
51     *         may be empty
52     * @throws AssertionError - if path is null
53     */
54    public List listNames(String path);
55
56    /**
57     * Delete the file or directory specified by the path. Return true if the file is successfully
58     * deleted, false otherwise. If the path refers to a directory, it must be empty. Return false
59     * if the path does not refer to a valid file or directory or if it is a non-empty directory.
60     *
61     * @param path - the path of the file or directory to delete
62     * @return true if the file or directory is successfully deleted
63     * @throws AssertionError - if path is null
64     */
65    public boolean delete(String path);
66
67    /**
68     * Rename the file or directory. Specify the FROM path and the TO path. Throw an exception if the FROM path or
69     * the parent directory of the TO path do not exist; or if the rename fails for another reason.
70     *
71     * @param fromPath - the source (old) path + filename
72     * @param toPath   - the target (new) path + filename
73     * @throws AssertionError      - if fromPath or toPath is null
74     * @throws FileSystemException - if the rename fails.
75     */
76    public void rename(String fromPath, String toPath);
77
78    /**
79     * Return the formatted directory listing entry for the file represented by the specified FileSystemEntry
80     *
81     * @param fileSystemEntry - the FileSystemEntry representing the file or directory entry to be formatted
82     * @return the the formatted directory listing entry
83     */
84    public String formatDirectoryListing(FileSystemEntry fileSystemEntry);
85
86    //-------------------------------------------------------------------------
87    // Path-related Methods
88    //-------------------------------------------------------------------------
89
90    /**
91     * Return true if there exists a file or directory at the specified path
92     *
93     * @param path - the path
94     * @return true if the file/directory exists
95     * @throws AssertionError - if path is null
96     */
97    public boolean exists(String path);
98
99    /**
100     * Return true if the specified path designates an existing directory, false otherwise
101     *
102     * @param path - the path
103     * @return true if path is a directory, false otherwise
104     * @throws AssertionError - if path is null
105     */
106    public boolean isDirectory(String path);
107
108    /**
109     * Return true if the specified path designates an existing file, false otherwise
110     *
111     * @param path - the path
112     * @return true if path is a file, false otherwise
113     * @throws AssertionError - if path is null
114     */
115    public boolean isFile(String path);
116
117    /**
118     * Return true if the specified path designates an absolute file path. What
119     * constitutes an absolute path is dependent on the file system implementation.
120     *
121     * @param path - the path
122     * @return true if path is absolute, false otherwise
123     * @throws AssertionError - if path is null
124     */
125    public boolean isAbsolute(String path);
126
127    /**
128     * Build a path from the two path components. Concatenate path1 and path2. Insert the file system-dependent
129     * separator character in between if necessary (i.e., if both are non-empty and path1 does not already
130     * end with a separator character AND path2 does not begin with one).
131     *
132     * @param path1 - the first path component may be null or empty
133     * @param path2 - the second path component may be null or empty
134     * @return the path resulting from concatenating path1 to path2
135     */
136    public String path(String path1, String path2);
137
138    /**
139     * Returns the FileSystemEntry object representing the file system entry at the specified path, or null
140     * if the path does not specify an existing file or directory within this file system.
141     *
142     * @param path - the path of the file or directory within this file system
143     * @return the FileSystemEntry containing the information for the file or directory, or else null
144     */
145    public FileSystemEntry getEntry(String path);
146
147    /**
148     * Return the parent path of the specified path. If <code>path</code> specifies a filename,
149     * then this method returns the path of the directory containing that file. If <code>path</code>
150     * specifies a directory, the this method returns its parent directory. If <code>path</code> is
151     * empty or does not have a parent component, then return an empty string.
152     * <p/>
153     * All path separators in the returned path are converted to the system-dependent separator character.
154     *
155     * @param path - the path
156     * @return the parent of the specified path, or null if <code>path</code> has no parent
157     * @throws AssertionError - if path is null
158     */
159    public String getParent(String path);
160
161}