Enhance javadoc
git-svn-id: svn://svn.code.sf.net/p/mockftpserver/code@181 531de8e6-9941-0410-b38b-9a92acbe0330
diff --git a/MockFtpServer/src/main/java/org/mockftpserver/core/server/AbstractFtpServer.java b/MockFtpServer/src/main/java/org/mockftpserver/core/server/AbstractFtpServer.java
index b8c2a8b..0cec4b1 100644
--- a/MockFtpServer/src/main/java/org/mockftpserver/core/server/AbstractFtpServer.java
+++ b/MockFtpServer/src/main/java/org/mockftpserver/core/server/AbstractFtpServer.java
@@ -35,51 +35,28 @@
import java.util.ResourceBundle;
/**
- * <b>StubFtpServer</b> is the top-level class for a "stub" implementation of an FTP Server,
+ * This is the abstract superclass for "mock" implementations of an FTP Server,
* suitable for testing FTP client code or standing in for a live FTP server. It supports
* the main FTP commands by defining handlers for each of the corresponding low-level FTP
* server commands (e.g. RETR, DELE, LIST). These handlers implement the {@link org.mockftpserver.core.command.CommandHandler}
* interface.
* <p/>
- * <b>StubFtpServer</b> works out of the box with default command handlers that return
- * success reply codes and empty data (for retrieved files, directory listings, etc.).
- * The command handler for any command can be easily configured to return custom data
- * or reply codes. Or it can be replaced with a custom {@link org.mockftpserver.core.command.CommandHandler}
- * implementation. This allows simulation of a complete range of both success and
- * failure scenarios. The command handlers can also be interrogated to verify command
- * invocation data such as command parameters and timestamps.
+ * By default, mock FTP Servers bind to the server control port of 21. You can use a different server
+ * control port by setting the the <code>serverControlPort</code> property. This is usually necessary
+ * when running on Unix or some other system where that port number is already in use or cannot be bound
+ * from a user process.
* <p/>
- * <b>StubFtpServer</b> can be fully configured programmatically or within a Spring Framework
- * (http://www.springframework.org/) or similar container.
- * <p/>
- * <h4>Starting the StubFtpServer</h4>
- * Here is how to start the <b>StubFtpServer</b> with the default configuration.
- * <pre><code>
- * StubFtpServer stubFtpServer = new StubFtpServer();
- * stubFtpServer.start();
- * </code></pre>
- * <p/>
- * <h4>Retrieving Command Handlers</h4>
- * You can retrieve the existing {@link org.mockftpserver.core.command.CommandHandler} defined for an FTP server command
- * by calling the {@link #getCommandHandler(String)} method, passing in the FTP server
- * command name. For example:
- * <pre><code>
- * PwdCommandHandler pwdCommandHandler = (PwdCommandHandler) stubFtpServer.getCommandHandler("PWD");
- * </code></pre>
- * <p/>
- * <h4>Replacing Command Handlers</h4>
- * You can replace the existing {@link org.mockftpserver.core.command.CommandHandler} defined for an FTP server command
- * by calling the {@link #setCommandHandler(String, org.mockftpserver.core.command.CommandHandler)} method, passing
- * in the FTP server command name and {@link org.mockftpserver.core.command.CommandHandler} instance. For example:
- * <pre><code>
- * PwdCommandHandler pwdCommandHandler = new PwdCommandHandler();
- * pwdCommandHandler.setDirectory("some/dir");
- * stubFtpServer.setCommandHandler("PWD", pwdCommandHandler);
- * </code></pre>
- * You can also replace multiple command handlers at once by using the {@link #setCommandHandlers(java.util.Map)}
+ * <h4>Command Handlers</h4>
+ * You can set the existing {@link CommandHandler} defined for an FTP server command
+ * by calling the {@link #setCommandHandler(String, CommandHandler)} method, passing
+ * in the FTP server command name and {@link CommandHandler} instance.
+ * You can also replace multiple command handlers at once by using the {@link #setCommandHandlers(Map)}
* method. That is especially useful when configuring the server through the <b>Spring Framework</b>.
- * <h4>FTP Command Reply Text ResourceBundle</h4>
* <p/>
+ * You can retrieve the existing {@link CommandHandler} defined for an FTP server command by
+ * calling the {@link #getCommandHandler(String)} method, passing in the FTP server command name.
+ * <p/>
+ * <h4>FTP Command Reply Text ResourceBundle</h4>
* The default text asociated with each FTP command reply code is contained within the
* "ReplyText.properties" ResourceBundle file. You can customize these messages by providing a
* locale-specific ResourceBundle file on the CLASSPATH, according to the normal lookup rules of
@@ -89,6 +66,8 @@
*
* @author Chris Mair
* @version $Revision$ - $Date$
+ * @see org.mockftpserver.fake.FakeFtpServer
+ * @see org.mockftpserver.stub.StubFtpServer
*/
public abstract class AbstractFtpServer implements Runnable {
diff --git a/MockFtpServer/src/main/java/org/mockftpserver/fake/FakeFtpServer.java b/MockFtpServer/src/main/java/org/mockftpserver/fake/FakeFtpServer.java
index 9a17c12..9c3ac3a 100644
--- a/MockFtpServer/src/main/java/org/mockftpserver/fake/FakeFtpServer.java
+++ b/MockFtpServer/src/main/java/org/mockftpserver/fake/FakeFtpServer.java
@@ -40,7 +40,7 @@
* including file and directory permissions, if they have been configured.
* <p/>
* <b>FakeFtpServer</b> can be fully configured programmatically or within the
- * <b>Spring Framework</b> or other dependency-injection container.
+ * <a href="http://www.springframework.org/">Spring Framework</a> or other dependency-injection container.
* <p/>
* In general the steps for setting up and starting the <b>FakeFtpServer</b> are:
* <ol>
@@ -50,23 +50,42 @@
* </ol>
* <h4>Example Code</h4>
* <pre><code>
+ * FakeFtpServer fakeFtpServer = new FakeFtpServer();
+ * <p/>
* FileSystem fileSystem = new WindowsFakeFileSystem();
- * DirectoryEntry directoryEntry1 = new DirectoryEntry("c:\\");
+ * fileSystem.add(new DirectoryEntry("c:\\"));
+ * fileSystem.add(new DirectoryEntry("c:\\data"));
+ * fileSystem.add(new FileEntry("c:\\data\\file1.txt", "abcdef 1234567890"));
+ * fileSystem.add(new FileEntry("c:\\data\\run.exe"));
+ * fakeFtpServer.setFileSystem(fileSystem);
+ * <p/>
+ * // Create UserAccount with username, password, home-directory
+ * UserAccount userAccount = new UserAccount("joe", "joe123", "c:\\");
+ * fakeFtpServer.addUserAccounts(userAccount);
+ * <p/>
+ * fakeFtpServer.start();
+ * </code></pre>
+ * <p/>
+ * <h4>Example Code with Permissions</h4>
+ * You can optionally set the permissions and owner/group for each file and directory, as in the following example.
+ * <pre><code>
+ * FileSystem fileSystem = new UnixFakeFileSystem();
+ * DirectoryEntry directoryEntry1 = new DirectoryEntry("/");
* directoryEntry1.setPermissions(new Permissions("rwxrwx---"));
* directoryEntry1.setOwner("joe");
* directoryEntry1.setGroup("dev");
* <p/>
- * DirectoryEntry directoryEntry2 = new DirectoryEntry("c:\\data");
+ * DirectoryEntry directoryEntry2 = new DirectoryEntry("/data");
* directoryEntry2.setPermissions(Permissions.ALL);
* directoryEntry2.setOwner("joe");
* directoryEntry2.setGroup("dev");
* <p/>
- * FileEntry fileEntry1 = new FileEntry("c:\\data\\file1.txt", "abcdef 1234567890");
+ * FileEntry fileEntry1 = new FileEntry("/data/file1.txt", "abcdef 1234567890");
* fileEntry1.setPermissionsFromString("rw-rw-rw-");
* fileEntry1.setOwner("joe");
* fileEntry1.setGroup("dev");
* <p/>
- * FileEntry fileEntry2 = new FileEntry("c:\\data\\run.exe");
+ * FileEntry fileEntry2 = new FileEntry("/data/run.exe");
* fileEntry2.setPermissionsFromString("rwxrwx---");
* fileEntry2.setOwner("mary");
* fileEntry2.setGroup("dev");
@@ -79,18 +98,30 @@
* FakeFtpServer fakeFtpServer = new FakeFtpServer();
* fakeFtpServer.setFileSystem(fileSystem);
* <p/>
- * UserAccount userAccount = new UserAccount();
- * userAccount.setUsername("joe");
- * userAccount.setPassword("joe123");
- * userAccount.setHomeDirectory("c:\\");
- * List userAccounts = Collections.singletonList(userAccount);
- * fakeFtpServer.setUserAccounts(userAccounts);
+ * // Create UserAccount with username, password, home-directory
+ * UserAccount userAccount = new UserAccount("joe", "joe123", "/");
+ * fakeFtpServer.addUserAccounts(userAccount);
* <p/>
* fakeFtpServer.start();
* </code></pre>
* <p/>
- * <h4>FTP Command Reply Text ResourceBundle</h4>
+ * <h4>FTP Server Control Port</h4>
+ * By default, <b>MockFtpServer</b> binds to the server control port of 21. You can use a different server
+ * control port by setting the the <code>serverControlPort</code> property. This is usually necessary
+ * when running on Unix or some other system where that port number is already in use or cannot be bound
+ * from a user process.
* <p/>
+ * <h4>Other Configuration</h4>
+ * The <code>systemName</code> property specifies the value returned by the <code>SYST</code>
+ * command. Note that this is typically used by an FTP client to determine how to parse
+ * system-dependent reply text, such as directory listings. This value defaults to <code>"WINDOWS"</code>.
+ * <p/>
+ * The <code>helpText</code> property specifies a <i>Map</i> of help text replies sent by the
+ * <code>HELP</code> command. The keys in that <i>Map</i> correspond to the command names passed as
+ * parameters to the <code>HELP</code> command. An entry with the key of an empty string ("") indicates the
+ * text used as the default help text when no command name parameter is specified for the <code>HELP</code> command.
+ * <p/>
+ * <h4>FTP Command Reply Text ResourceBundle</h4>
* The default text asociated with each FTP command reply code is contained within the
* "ReplyText.properties" ResourceBundle file. You can customize these messages by providing a
* locale-specific ResourceBundle file on the CLASSPATH, according to the normal lookup rules of
diff --git a/MockFtpServer/src/main/java/org/mockftpserver/fake/command/HelpCommandHandler.java b/MockFtpServer/src/main/java/org/mockftpserver/fake/command/HelpCommandHandler.java
index dc209d0..f6f9c2d 100644
--- a/MockFtpServer/src/main/java/org/mockftpserver/fake/command/HelpCommandHandler.java
+++ b/MockFtpServer/src/main/java/org/mockftpserver/fake/command/HelpCommandHandler.java
@@ -31,6 +31,8 @@
* <li>Otherwise, reply with 214 along with the configured default help text that has been configured
* (or empty if none)</li>
* </ol>
+ * <p/>
+ * The help text is configured within the {@link org.mockftpserver.fake.FakeFtpServer}.
*
* @author Chris Mair
* @version $Revision: 89 $ - $Date: 2008-08-02 08:07:44 -0400 (Sat, 02 Aug 2008) $
@@ -45,7 +47,6 @@
String help = getServerConfiguration().getHelpText(key);
if (help == null) {
sendReply(session, ReplyCodes.HELP_OK, "help.noHelpTextDefined", list(key));
- ;
} else {
sendReply(session, ReplyCodes.HELP_OK, "help", list(help));
}
diff --git a/MockFtpServer/src/main/java/org/mockftpserver/stub/StubFtpServer.java b/MockFtpServer/src/main/java/org/mockftpserver/stub/StubFtpServer.java
index 0c38f04..401368b 100644
--- a/MockFtpServer/src/main/java/org/mockftpserver/stub/StubFtpServer.java
+++ b/MockFtpServer/src/main/java/org/mockftpserver/stub/StubFtpServer.java
@@ -38,8 +38,8 @@
* failure scenarios. The command handlers can also be interrogated to verify command
* invocation data such as command parameters and timestamps.
* <p/>
- * <b>StubFtpServer</b> can be fully configured programmatically or within a Spring Framework
- * ({@link http://www.springframework.org/}) or similar container.
+ * <b>StubFtpServer</b> can be fully configured programmatically or within the
+ * <a href="http://www.springframework.org/">Spring Framework</a> or similar container.
* <p/>
* <h4>Starting the StubFtpServer</h4>
* Here is how to start the <b>StubFtpServer</b> with the default configuration.
@@ -48,6 +48,11 @@
* stubFtpServer.start();
* </code></pre>
* <p/>
+ * <h4>FTP Server Control Port</h4>
+ * By default, <b>StubFtpServer</b> binds to the server control port of 21. You can use a different server
+ * control port by setting the the <code>serverControlPort</code> property. This is usually necessary
+ * when running on Unix or some other system where that port number is already in use or cannot be bound
+ * from a user process.
* <h4>Retrieving Command Handlers</h4>
* You can retrieve the existing {@link CommandHandler} defined for an FTP server command
* by calling the {@link #getCommandHandler(String)} method, passing in the FTP server