[FCKeditor-Commits] r3580 - in FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor: connector response

[<com...@fc...>]

Author: mosipov
Date: 2009-05-31 16:45:48 +0200 (Sun, 31 May 2009)
New Revision: 3580

Modified:
   FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/Connector.java
   FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/Dispatcher.java
   FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/response/GetResponse.java
Log:
- Reworked Dispatcher JavaDoc
- Small JavaDocs fixes

Modified: FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/Connector.java
===================================================================
--- FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/Connector.java	2009-05-30 23:21:07 UTC (rev 3579)
+++ FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/Connector.java	2009-05-31 14:45:48 UTC (rev 3580)
@@ -68,14 +68,14 @@
 	public final static String KEY_SIZE = "size";
 
 	/**
-	 * Initializes the connector. This method will be called at the
+	 * Initializes this connector. This method will be called at the
 	 * {@link ConnectorServlet#init() init} of the connector servlet.
 	 * 
 	 * @param servletContext
 	 *            reference to the {@link ServletContext} in which the caller is
 	 *            executing
 	 * @throws Exception
-	 *             if an exception occurs that interrupts the connectors's
+	 *             if an exception occurs that interrupts the connector's
 	 *             normal operation
 	 */
 	public void init(final ServletContext servletContext) throws Exception;

Modified: FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/Dispatcher.java
===================================================================
--- FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/Dispatcher.java	2009-05-30 23:21:07 UTC (rev 3579)
+++ FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/Dispatcher.java	2009-05-31 14:45:48 UTC (rev 3580)
@@ -54,45 +54,48 @@
 import org.slf4j.LoggerFactory;
 
 /**
- * The 'man in the middle' between the {@link ConnectorServlet} and the current implementation
- * of the {@link Connector}. It verifies the request parameters and forwards them to the corresponding
- * {@link Connector} methods. Dependent on the verification of the request parameters and the method calls,
- * {@link GetResponse} or {@link UploadResponse} will be initialized. These response objects will be used later in
- * {@link ConnectorServlet} to build the HttpServletResponse. If an error has
- * occurred inside the implementation of the {@link Connector} methods, well-defined exceptions from
- * {@link net.fckeditor.connector.exception} will be thrown. Dependent on these 
- * exceptions the response objects are initialized.
+ * File browser request dispatcher. This class is the validating instance
+ * between the {@link ConnectorServlet connector servlet} and a
+ * {@link Connector connector}. It receives the requests, parses the parameters,
+ * validates/sanitizes them and mandates them to the connector. After the
+ * connector has processed the requests, this dispatcher passes the response
+ * back to the connector servlet. More over, it intercepts all
+ * {@link net.fckeditor.connector.exception specified exceptions} from the
+ * connector and emits appropriate messages to the user.
  * 
- * @see ConnectorServlet 
- * 
  * @version $Id$
  */
 public class Dispatcher {
 	private final Logger logger = LoggerFactory.getLogger(Dispatcher.class);
-	private Connector connector = null;
+	private Connector connector;
 	
 	/**
-	 * Initializes the {@link Connector}.
+	 * Initializes this dispatcher. This method will be called at the
+	 * {@link ConnectorServlet#init() init} of the connector servlet.
 	 * 
 	 * @param servletContext
+	 *            reference to the {@link ServletContext} in which the caller is
+	 *            executing
+	 * @throws Exception
+	 *             if an exception occurs that interrupts the dispatcher's
+	 *             normal operation
 	 */
-	protected Dispatcher(final ServletContext servletContext) throws Exception {
-		this.connector = ConnectorHandler.getConnector();
-		this.connector.init(servletContext);
+	Dispatcher(final ServletContext servletContext) throws Exception {
+		connector = ConnectorHandler.getConnector();
+		connector.init(servletContext);
 	}
 
 	/**
-	 * Manages <code>GET</code> requests (<code>GetFolders</code>,
-	 * <code>GetFoldersAndFiles</code>, <code>CreateFolder</code>).<br/>
+	 * Called by the connector servlet to handle a {@code GET} request. In
+	 * particular, it handles the {@link Command#GET_FOLDERS GetFolders},
+	 * {@link Command#GET_FOLDERS_AND_FILES GetFoldersAndFiles} and
+	 * {@link Command#CREATE_FOLDER CreateFolder} commands.
 	 * 
-	 * The method accepts commands sent in the following format:<br/>
-	 * <code>connector?Command=&lt;CommandName&gt;&Type=&lt;ResourceType&gt;&CurrentFolder=&lt;FolderPath&gt;</code>
-	 * <p>
-	 * It executes the relevant commands and then returns the result to the
-	 * client in XML format.
-	 * </p>
+	 * @param request
+	 *            the current request instance
+	 * @return the get response instance associated with this request
 	 */
-	public GetResponse doGet(final HttpServletRequest request) {
+	GetResponse doGet(final HttpServletRequest request) {
 		logger.debug("Entering Dispatcher#doGet");
 		
 		Context context = ThreadLocalData.getContext();
@@ -171,45 +174,48 @@
 	}
 	
 	/**
-	 * Helper to make the right {@link Connector}-calls for
-	 * <code>GetFolders</code> and <code>GetFoldersAndFiles</code>.
+	 * Returns get response for the {@code GetFolders*} commands. This is simply
+	 * a helper method.
 	 * 
 	 * @param command
-	 *            should be only {@link Command#GET_FOLDERS} or
-	 *            {@link Command#GET_FOLDERS_AND_FILES}!!
-	 * @param type
-	 * @param currentFolderStr
-	 * @param url
-	 * @return
+	 *            the current command, should be only GetFolders or
+	 *            GetFoldersAndFiles
+	 * @param the
+	 *            current resource type
+	 * @param currentFolder
+	 *            the current folder
+	 * @param constructedUrl
+	 *            the final URL
+	 * @return the get response instance associated with this request
 	 * @throws InvalidCurrentFolderException
-	 * @throws ReadException 
+	 *             if the current folder name is invalid or does not exist
+	 *             within the underlying backend
+	 * @throws ReadException
+	 *             if the file attributes and/or folder names could not be read
+	 *             due to some reason
 	 */
 	private GetResponse getFoldersAndOrFiles(final Command command,
-			final ResourceType type, final String currentFolderStr,
-			final String url) throws InvalidCurrentFolderException,
+			final ResourceType type, final String currentFolder,
+			final String constructedUrl) throws InvalidCurrentFolderException,
 			ReadException {
 		GetResponse getResponse = new GetResponse(command, type,
-				currentFolderStr, url);
-		getResponse.setFolders(connector.getFolders(type, currentFolderStr));
+				currentFolder, constructedUrl);
+		getResponse.setFolders(connector.getFolders(type, currentFolder));
 		if (command.equals(Command.GET_FOLDERS_AND_FILES))
-			getResponse.setFiles(connector.getFiles(type, currentFolderStr));
+			getResponse.setFiles(connector.getFiles(type, currentFolder));
 		return getResponse;
 	}
 
 	/**
-	 * Manage the <code>POST</code> requests (<code>FileUpload</code>).<br />
+	 * Called by the connector servlet to handle a {@code POST} request. In
+	 * particular, it handles the {@link Command#FILE_UPLOAD FileUpload} and
+	 * {@link Command#QUICK_UPLOAD QuickUpload} commands.
 	 * 
-	 * The method accepts commands sent in the following format:<br />
-	 * <code>connector?Command=&lt;(File|Quick)Upload&gt;&Type=&lt;ResourceType&gt;&CurrentFolder=&lt;FolderPath&gt;</code>
-	 * with the file in the <code>POST</code> body.<br />
-	 * <br />
-	 * The Connector stores an uploaded file (renames a file if another exists
-	 * with the same name) and then returns the JavaScript callback.
-	 * 
-	 * @throws IOException
-	 *             if some unpredictable write error happens
+	 * @param request
+	 *            the current request instance
+	 * @return the upload response instance associated with this request
 	 */
-	public UploadResponse doPost(final HttpServletRequest request) {
+	UploadResponse doPost(final HttpServletRequest request) {
 		logger.debug("Entering Dispatcher#doPost");
 		
 		Context context = ThreadLocalData.getContext();
@@ -269,6 +275,7 @@
 								newFileName);
 					}
 				}
+				
 				uplFile.delete();
 			} catch (InvalidCurrentFolderException e) {
 				uploadResponse = UploadResponse.getInvalidCurrentFolderError();
@@ -285,5 +292,4 @@
 		return uploadResponse;
 	}
 	
-	
-}
+}
\ No newline at end of file

Modified: FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/response/GetResponse.java
===================================================================
--- FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/response/GetResponse.java	2009-05-30 23:21:07 UTC (rev 3579)
+++ FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/response/GetResponse.java	2009-05-31 14:45:48 UTC (rev 3580)
@@ -110,7 +110,7 @@
 	 * 
 	 * @param command
 	 *            the current command of the new get response
-	 * @param resourceType
+	 * @param type
 	 *            the current resource type of the new get response
 	 * @param currentFolder
 	 *            the current folder of the new get response
@@ -119,7 +119,7 @@
 	 * @throws RuntimeException
 	 *             if creation of the underlying DOM document failed
 	 */
-	public GetResponse(Command command, ResourceType resourceType,
+	public GetResponse(Command command, ResourceType type,
 			String currentFolder, String constructedUrl) {
 
 		try {
@@ -134,7 +134,7 @@
 		Element root = document.createElement("Connector");
 		document.appendChild(root);
 		root.setAttribute("command", command.getName());
-		root.setAttribute("resourceType", resourceType.getName());
+		root.setAttribute("resourceType", type.getName());
 
 		Element currentFolderElement = document.createElement("CurrentFolder");
 		currentFolderElement.setAttribute("path", currentFolder);