fakeftpserver-filesystems.apt revision 704509c40a45eeb811fbe5ed7ffcf7bf0aea7901 
1		--------------------------------------------------
2				FakeFtpServer Filesystems
3		--------------------------------------------------
4
5FakeFtpServer Filesystems
6
7  <<FakeFtpServer>> provides a simulated server file system, including support for file and directory permissions
8  and owner and group authorization based on Unix. This file system can be populated at startup (or thereafter) with
9  directories and files (including arbitrary content) to be retrieved by an FTP client. Any files sent to the server
10  by an FTP client exist within that file system as well, and can be accessed through the file system API, or
11  can even be subsequently retrieved by an FTP client.
12
13  The filesystem abstraction is accessed through the <<<FileSystem>>> interface in the
14  <<<org.mockftpserver.fake.filesystem>>> package. Two implementations of this interface are provided:
15  <<<WindowsFakeFileSystem>>> and <<<UnixFakeFileSystem>>>. They both manage the files and directories in memory,
16  simulating a real file system. You are also free to implement your own <<<FileSystem>>> implementation.
17
18  Note that both <<<WindowsFakeFileSystem>>> and <<<UnixFakeFileSystem>>> are <virtual> file systems, and do
19  not depend on the <real> operating systems or file systems on which <<FakeFtpServer>> is running. In other
20  words, you can configure and run a <<FakeFtpServer>> with a <<<WindowsFakeFileSystem>>> on top of a <real>
21  Unix system, or run a <<FakeFtpServer>> with a <<<UnixFakeFileSystem>>> on top of a <real> Windows system.
22
23  See the javadoc for these classes for more information.
24
25* WindowsFakeFileSystem
26
27  <<WindowsFakeFileSystem>> is an implementation of the <<<FileSystem>>> interface that simulates a Microsoft
28  Windows file system. The rules for file and directory names include:
29
30    * Filenames are case-insensitive
31
32    * Either forward slashes (/) or backward slashes (\) are valid path separators (but are normalized to '\')
33
34    * An absolute path starts with a drive specifier (e.g. 'a:' or 'c:') followed by '\' or '/',
35      or else it starts with "\\"</li>
36
37
38* UnixFakeFileSystem
39
40  <<UnixFakeFileSystem>> is an implementation of the <<<FileSystem>>> interface that simulates a Unix
41  file system. The rules for file and directory names include:
42
43    * Filenames are case-sensitive
44
45    * Forward slashes (/) are the only valid path separators
46
47* WindowsFakeFileSystem and UnixFakeFileSystem: Common Behavior and Configuration
48
49  Both <<<WindowsFakeFileSystem>>> and <<<UnixFakeFileSystem>>> are subclasses of <<<AbstractFakeFileSystem>>>. They
50  manage the files and directories in memory, simulating a real file system.
51
52  If the <createParentDirectoriesAutomatically> property is set to <true>,
53  then creating a directory or file will automatically create any parent directories (recursively)
54  that do not already exist. If <false>, then creating a directory or file throws an
55  exception if its parent directory does not exist. This value defaults to <true>.
56
57  The <directoryListingFormatter> property holds an instance of <<DirectoryListingFormatter>>,
58  used by the <formatDirectoryListing> method to format directory listings in a
59  filesystem-specific manner. This property is initialized by concrete subclasses.
60
61* File Permissions, Owners and Groups
62
63  Each <file> or <directory> entry within a <<<FileSystem>>> has associated <owner>, <group> and <permissions>
64  attributes. All of these attributes are optional. If none are specified for a file or directory, then full
65  access by all users is the default.
66
67  If, however, these values are specified for a filesystem entry, then they affect whether a file can be created,
68  read, written or deleted, and whether a directory can be created, listed or deleted.
69
70  This approach for access control is conceptually (and somewhat loosely) based on the Unix file system, but
71  don't expect a comprehensive implementation fully matching Unix's capabilities.
72
73** Permissions
74
75  The permissions for a file or directory entry in the filesystem are represented by a 9-character string of
76  the form "rwxrwxrwx", consisting of three "rwx" triples. Each triple indicates the READ ("r"), WRITE ("w") and
77  EXECUTE ("x") permissions for a specific set of users. Each position can alternatively contain a "-" to
78  indicate no READ/WRITE/EXECUTE access, depending on its position.
79
80  The first "rwx" triple indicates the READ, WRITE and EXECUTE permissions for the owner of the file. The
81  second triple indicates the permissions for the group associated with the file. The third triple
82  indicates the permissions for the rest of the world.
83
84  For example, the permissions string "rwx--xrw-" is interpreted to mean that users have READ/WRITE/EXECUTE access,
85  the group has only EXECUTE, and the world has only READ and WRITE.
86
87  There are plenty of good tutorials and references for understanding Unix file permissions, including
88  {{{http://www.dartmouth.edu/~rc/help/faq/permissions.html}this one}}.
89
90  The <<<Permissions>>> class represents and encapsulates the read/write/execute permissions for a file or
91  directory. Its constructor takes a 9-character "rwx" String as described above.
92
93  The <<<AbstractFileSystemEntry>>> contains a <permissions> attribute, so that every file and directory in the
94  file system can be assigned a unique set of permissions from a <<<Permissions>>> object. There is also a
95  <<<setPermissionsFromString()>>> convenience setter that allows setting the permissions directly from a String.
96
97**  FileSystem Access Rules
98
99***  When Are READ, WRITE or EXECUTE Access Required?
100
101  If the <permissions> are configured for a file or directory within the <<<FileSystem>>>, then
102  those permissions affect whether and how that file/directory can be accessed.
103  Here are the rules for applying permissions for file access:
104
105*------------------------*-------------------------------------------------------------------*
106| <<Operation>>          | <<Required Permissions>>                                          |
107*------------------------*-------------------------------------------------------------------*
108| Create a new file      | EXECUTE access to the directory and WRITE access to the directory |
109*------------------------*-------------------------------------------------------------------*
110| Read a file            | EXECUTE access to the directory and READ access to the file       |
111*------------------------*-------------------------------------------------------------------*
112| Write a file           | EXECUTE access to the directory and WRITE access to the file      |
113*------------------------*-------------------------------------------------------------------*
114| Delete a file          | WRITE access to the directory                                     |
115*------------------------*-------------------------------------------------------------------*
116| Rename a file          | READ access to the FROM file and WRITE access to the directory    |
117*------------------------*-------------------------------------------------------------------*
118| Create a directory     | WRITE and EXECUTE acccess to the parent directory                 |
119*------------------------*-------------------------------------------------------------------*
120| List a directory       | READ acccess to the directory/file                                |
121*------------------------*-------------------------------------------------------------------*
122| CD to a directory      | EXECUTE acccess to the directory                                  |
123*------------------------*-------------------------------------------------------------------*
124| Delete a directory     | WRITE acccess to the parent directory                             |
125*------------------------*-------------------------------------------------------------------*
126
127*** How Do Owner and Group Affect Access?
128
129  Each file and directory in the filesystem (subclass of <<<AbstractFileSystemEntry>>>) contains <owner>
130  and <group> attributes. These attributes are optional.
131
132  If the <owner> is configured for a file/directory, AND the <permissions> are configured as well,
133  then the <<owner>> triple from the <permissions> are applied if and only if the <<<UserAccount>>> for the
134  currently logged in FTP user (client) matches the <owner> configured for the file/directory.
135
136  Similarly, if the <group> is configured for a file/directory, AND the <permissions> are configured as well,
137  then the <<group>> triple from the <permissions> are applied if and only if <groups> configured for the
138  <<<UserAccount>>> for the currently logged in FTP user (client) contain the <group> configured for the file/directory.
139
140  Otherwise, the <<world>> triple from the <permissions> are applied.
141
142* Example Code
143
144  This example illustrates setting the permissions, owner and group for a file and directory within the
145  <<<FakeFtpServer>>> filesystem.
146
147  TBD...
148
149