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