Index: /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 (revision 3358) +++ /FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/response/GetResponse.java (revision 3359) @@ -45,8 +45,8 @@ /** - * Creates an XML response for every GET request of the Connector - * servlet. This class maps directly to the XML layout described here. - * + * Represents the XML response for the File Browser's GET request.
+ * The XML response is described here in detail. + * * @version $Id$ */ @@ -57,8 +57,8 @@ protected Element foldersElement; protected Element filesElement; - + /** Error number OK */ public static final int EN_OK = 0; - + /** Error number CUSTOM ERROR */ public static final int EN_CUSTOM_ERROR = 1; @@ -75,14 +75,17 @@ /** Error number UNKNOWN ERROR */ public static final int EN_UKNOWN_CREATE_FOLDER_ERROR = 110; - - /** - * - * Use this constructor if want to respond a negative/error message with - * custom text. + + /** + * + * Constructs a response with a specific error number and message. * * @param number - * @param text - */ - public GetResponse(int number, String text) { + * error number + * @param message + * specific message + * @throws RuntimeException + * if creation of the underlying DOM object failed + */ + public GetResponse(int number, String message) { try { DocumentBuilderFactory factory = DocumentBuilderFactory @@ -96,18 +99,25 @@ Element root = document.createElement("Connector"); document.appendChild(root); - setError(number, text); - } - - /** - * Use this constructor if want to respond a positive message. + setError(number, message); + } + + /** + * Constructs a successful response for a specific command and resource + * type. * * @param command + * current command * @param resourceType + * current resource type * @param currentFolder + * current folder * @param constructedUrl - */ - public GetResponse(Command command, ResourceType resourceType, + * final url + * @throws RuntimeException + * if creation of the underlying DOM object failed + */ + public GetResponse(Command command, ResourceType resourceType, String currentFolder, String constructedUrl) { - + try { DocumentBuilderFactory factory = DocumentBuilderFactory @@ -118,34 +128,39 @@ throw new RuntimeException(e); } - + Element root = document.createElement("Connector"); document.appendChild(root); root.setAttribute("command", command.toString()); root.setAttribute("resourceType", resourceType.getName()); - + Element currentFolderElement = document.createElement("CurrentFolder"); currentFolderElement.setAttribute("path", currentFolder); - + currentFolderElement.setAttribute("url", constructedUrl); root.appendChild(currentFolderElement); - - } - - /** - * Use this constructor if want to respond a negative/error message only. + + } + + /** + * Constructs a response with a specific error number only. * * @param number + * error number + * @throws RuntimeException + * if creation of the underlying DOM object failed */ public GetResponse(int number) { this(number, null); } - - /** - * Sets an error number with a custom message. + + /** + * Sets an error number with a message. * * @param number - * @param text - */ - public void setError(int number, String text) { + * error number + * @param message + * specific message + */ + public void setError(int number, String message) { if (errorElement == null) { @@ -155,13 +170,14 @@ errorElement.setAttribute("number", String.valueOf(number)); - if (Utils.isNotEmpty(text)) - errorElement.setAttribute("text", text); - - } - - /** - * Sets an error number. + if (Utils.isNotEmpty(message)) + errorElement.setAttribute("text", message); + + } + + /** + * Sets an error number only. * * @param number + * error number */ public void setError(int number) { @@ -170,8 +186,10 @@ /** - * Lists all folders as XML tags. - * @param dir - */ - public void setFolders(final List dirs) { + * Sets folders associated with this response. + * + * @param folders + * list with folder names + */ + public void setFolders(final List folders) { if (foldersElement != null) { Element parent = (Element) foldersElement.getParentNode(); @@ -182,15 +200,17 @@ document.getDocumentElement().appendChild(foldersElement); - for (String file : dirs) { + for (String folder : folders) { Element folderElement = document.createElement("Folder"); - folderElement.setAttribute("name", file); + folderElement.setAttribute("name", folder); foldersElement.appendChild(folderElement); } } - - /** - * Lists all files XML tags. - * - * @param Map, key is the file name and value is the size of the file in bytes + + /** + * Sets files associated with this response. + * + * @param files + * list with maps. Each map represents a file with its specific + * attributes. */ public void setFiles(final List> files) { @@ -202,19 +222,26 @@ filesElement = document.createElement("Files"); document.getDocumentElement().appendChild(filesElement); - + long length = 1L; long tempLength; - + for (Map file : files) { Element fileElement = document.createElement("File"); - fileElement.setAttribute("name", (String) file.get(Connector.KEY_NAME)); + fileElement.setAttribute("name", (String) file + .get(Connector.KEY_NAME)); tempLength = (Long) file.get(Connector.KEY_SIZE); if (tempLength > 1024) - length = tempLength/1024; + length = tempLength / 1024; fileElement.setAttribute("size", String.valueOf(length)); filesElement.appendChild(fileElement); } } - + + /** + * Transforms the underlying DOM object to an XML string. + * + * @throws RuntimeException + * if transformation failed + */ @Override public String toString() { @@ -237,57 +264,98 @@ return sw.toString(); } - + + /** + * Creates an OK response. + */ public static GetResponse getOK() { return new GetResponse(EN_OK); } - + + /** + * Creates an INVALID COMMAND error. + */ public static GetResponse getInvalidCommandError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); return new GetResponse(EN_CUSTOM_ERROR, lm.getInvalidCommandSpecified()); } - + + /** + * Creates an INVALID RESOURCE TYPE error. + */ public static GetResponse getInvalidResourceTypeError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); - return new GetResponse(EN_CUSTOM_ERROR, lm.getInvalidResouceTypeSpecified()); - } - + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); + return new GetResponse(EN_CUSTOM_ERROR, lm + .getInvalidResouceTypeSpecified()); + } + + /** + * Creates an INVALID CURRENT FOLDER error. + */ public static GetResponse getInvalidCurrentFolderError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); - return new GetResponse(EN_CUSTOM_ERROR, lm.getInvalidCurrentFolderSpecified()); - } - + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); + return new GetResponse(EN_CUSTOM_ERROR, lm + .getInvalidCurrentFolderSpecified()); + } + // TODO which EN to respond? + /** + * Creates a GET RESOURCES DISABLED error. + */ public static GetResponse getGetResourcesDisabledError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); return new GetResponse(EN_CUSTOM_ERROR, lm.getGetResourcesDisabled()); } - + // TODO which EN to respond? + /** + * Creates a GET RESOURCES READ error. + */ public static GetResponse getGetResourcesReadError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); return new GetResponse(EN_CUSTOM_ERROR, lm.getGetResourcesReadError()); } - + // TODO which EN to respond? + /** + * Creates a CREATE FOLDER DISABLED error. + */ public static GetResponse getCreateFolderDisabledError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); return new GetResponse(EN_CUSTOM_ERROR, lm.getCreateFolderDisabled()); } - + + /** + * Creates an INVALID NEW FOLDER NAME error. + */ public static GetResponse getInvalidNewFolderNameError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); return new GetResponse(EN_INVALID_NEW_FOLDER_NAME_ERROR, lm .getInvalidNewFolderNameSpecified()); } - + + /** + * Creates a FOLDER ALREADY EXISTS error. + */ public static GetResponse getFolderAlreadyExistsError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); return new GetResponse(EN_FOLDER_ALREADY_EXISTS_ERROR, lm .getFolderAlreadyExistsError()); } - + // TODO which EN to respond? + /** + * Creates a CREATE FOLDER WRITE error. + */ public static GetResponse getCreateFolderWriteError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); return new GetResponse(EN_UKNOWN_CREATE_FOLDER_ERROR, lm .getCreateFolderWriteError()); Index: /FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/response/UploadResponse.java =================================================================== --- /FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/response/UploadResponse.java (revision 3358) +++ /FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/response/UploadResponse.java (revision 3359) @@ -26,19 +26,23 @@ /** - * Simply abstracts from the JavaScript callback to a Java object. - * + * Represents the HTML/JavaScript callback/response for the File Browser's + * POST request.
+ * The response is described here in detail. *

- * The usage is quite easy but can be tricky since varargs are used in the class - * constructor.
The requester expects a JS method callback with variable - * arguments size. + * This class utilizes varags to reflect the JavaScript callback function in an + * optimal way. However, varargs can be tricky. You can always omit passed + * parameters from right to left but any violation may result in an exception or + * a failed callback. *

*

- * e.g. - * window.parent.OnUploadCompleted(101,'some/url/file.img','file.img','no error'); + * For example: window.parent.OnUploadCompleted(101,'some/url/file.img','file.img','no error') can be mapped with + * + * UploadResponse ur = new UploadResponse(SC_SOME_ERROR,"/some/url/file.img","file.img","no error") + * . *

*

- * The UploadResponse constructor behaves the same way by simply calling it - * with:
- * UploadResponse ur = new UploadResponse(SC_SOME_ERROR,"/some/url/file.img","file.img","no error"): + * But window.parent.OnUploadCompleted(101,'some/url/file.img','no error') is an illegal callback and + * will fail. *

* @@ -54,8 +58,8 @@ /** Error number CUSTOM ERROR */ public static final int EN_CUSTOM_ERROR = 1; - + /** Error number CUSTOM WARNING */ public static final int EN_CUSTOM_WARNING = 101; - + /** Error number FILE RENAMED WARNING */ public static final int EN_FILE_RENAMED_WARNING = 201; @@ -68,22 +72,16 @@ /** - * Constructs the response with variable amount of parameters. + * Constructs a response with a varying amount of arguments. *

- * Put the desired parameters in the constructor. You may omit them from - * right to left but you have to remain the order.
e.g. - * UploadResponse(SC_OK,"/some/url/to/pic.jpg","pic") or - * UploadResponse(SC_OK) but not - * UploadResponse(SC_OK,"some error message") + * Use the predefined error numbers or upload responses, if possible.
+ * If you need to set error number and message only, use constructor with + * one argument and call {@link UploadResponse#setCustomMessage(String)}. *

*

- * Use, if possible, the predefined error numbers or upload responses. - *

- *

- * If you need to set error number and message only, use constructor with - * one parameter and call {@link UploadResponse#setCustomMessage(String)}. * * @param arguments * possible argument order: * int errorNumber, String fileUrl, String filename, String customMessage + * . Omit from right to left. * @throws IllegalArgumentException * if amount of arguments is less than 1 and above 4 @@ -106,5 +104,5 @@ /** - * Sets the message in the UploadResponse. + * Sets a custom message. * * Methods automatically determines how many arguments are set and puts the @@ -112,5 +110,5 @@ * * @param customMassage - * the message you want to pass to the user + * the message you want to respond to the user */ public void setCustomMessage(final String customMassage) { @@ -126,49 +124,86 @@ } } - - + + /** + * Creates an OK response. + */ public static UploadResponse getOK(String fileUrl) { return new UploadResponse(EN_OK, fileUrl); } - - public static UploadResponse getFileRenamedWarning(String fileUrl, String newFileName) { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); + + /** + * Creates a FILE RENAMED warning. + */ + public static UploadResponse getFileRenamedWarning(String fileUrl, + String newFileName) { + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); return new UploadResponse(EN_FILE_RENAMED_WARNING, fileUrl, newFileName, lm.getFileRenamedWarning(newFileName)); } - + + /** + * Creates a INVALID FILE TYPE error. + */ public static UploadResponse getInvalidFileTypeError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); - return new UploadResponse(EN_INVALID_FILE_TYPE_ERROR, lm.getInvalidFileTypeSpecified()); - } - + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); + return new UploadResponse(EN_INVALID_FILE_TYPE_ERROR, lm + .getInvalidFileTypeSpecified()); + } + + /** + * Creates a INVALID COMMAND error. + */ public static UploadResponse getInvalidCommandError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); - return new UploadResponse(EN_CUSTOM_ERROR, null, null, lm.getInvalidCommandSpecified()); - } - + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); + return new UploadResponse(EN_CUSTOM_ERROR, null, null, lm + .getInvalidCommandSpecified()); + } + + /** + * Creates a INVALID RESOURCE TYPE error. + */ public static UploadResponse getInvalidResourceTypeError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); - return new UploadResponse(EN_CUSTOM_ERROR, null, null, lm.getInvalidResouceTypeSpecified()); - } - + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); + return new UploadResponse(EN_CUSTOM_ERROR, null, null, lm + .getInvalidResouceTypeSpecified()); + } + + /** + * Creates a INVALID CURRENT FOLDER error. + */ public static UploadResponse getInvalidCurrentFolderError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); - return new UploadResponse(EN_CUSTOM_ERROR, null, null, lm.getInvalidCurrentFolderSpecified()); - } - + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); + return new UploadResponse(EN_CUSTOM_ERROR, null, null, lm + .getInvalidCurrentFolderSpecified()); + } + + /** + * Creates a FILE UPLOAD DISABLED error. + */ public static UploadResponse getFileUploadDisabledError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); - return new UploadResponse(EN_SECURITY_ERROR, null, null, lm.getFileUploadDisabled()); - } - + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); + return new UploadResponse(EN_SECURITY_ERROR, null, null, lm + .getFileUploadDisabled()); + } + // TODO which EN to respond? + /** + * Creates a FILE UPLOAD WRITE error. + */ public static UploadResponse getFileUploadWriteError() { - LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData.getRequest()); - return new UploadResponse(EN_CUSTOM_ERROR, null, null, lm.getFileUploadWriteError()); - } - - /** - * Assembles the JavaScript method for the user callback + LocalizedMessages lm = LocalizedMessages.getMessages(ThreadLocalData + .getRequest()); + return new UploadResponse(EN_CUSTOM_ERROR, null, null, lm + .getFileUploadWriteError()); + } + + /** + * Assembles the JavaScript callback. */ @Override @@ -177,6 +212,8 @@ sb.append("