Index: /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 (revision 3576) +++ /FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/Connector.java (revision 3577) @@ -32,21 +32,29 @@ import net.fckeditor.connector.exception.ReadException; import net.fckeditor.connector.exception.WriteException; +import net.fckeditor.connector.impl.AbstractLocalFileSystemConnector; +import net.fckeditor.handlers.RequestCycleHandler; import net.fckeditor.handlers.ResourceType; +import net.fckeditor.requestcycle.ThreadLocalData; /** - * Interface for all Connectors.
- * A Connector has to implement all commands described in http://docs.fckeditor.net/FCKeditor_2.x/Developers_Guide/Server_Side_Integration#The_Commands . - * To get the 'big picture', refer the javadoc at {@link ConnectorServlet}.
- * The Connector will be initialized by the {@link Dispatcher}. If an error is - * happened there are well-defined exceptions which must be thrown. So the - * {@link Dispatcher} can react according to it.
- *
- * Keep in mind that the {@link Dispatcher} verifies the request and redirects - * the relevant parameters to the different methods of the connector and - * forwards the response to {@link ConnectorServlet}. Therefore you don't need - * to check the basic parameters 'type' and 'currentFolder' against - * null. - * - * @see ConnectorServlet + * Backend interface of the file browser. A connector serves and manages files + * and folders accessed through the file manager on an arbitrary backend system.
+ * The connector will receive a request if, and only if, the request was valid + * in terms of valid and reasonable parameters up to an abstract point which is + * independent from a specific connector implementation. + *

+ * Helpful classes and methods: + *

    + *
  1. If you need to access the request instance itself and/or the context + * parameters sent from the file browser, take a look at the + * {@link ThreadLocalData} object.
    2. + *
  2. Use + * {@link RequestCycleHandler#getUserFilesAbsolutePath(javax.servlet.http.HttpServletRequest) + * RequestCycleHandler.getUserFilesAbsolutePath}, + * {@link AbstractLocalFileSystemConnector#getRealUserFilesAbsolutePath(java.lang.String) + * AbstractLocalFileSystemConnector.getRealUserFilesAbsolutePath} (if use it) to + * resolve the real path or simply do it yourself.
    3. + *
+ *

* * @version $Id$ @@ -54,35 +62,39 @@ public interface Connector { - /** - * This key is to address a file's name in - * {@link #getFiles(ResourceType, String)} map. - */ + /** Key 'name' for a file's name */ public final static String KEY_NAME = "name"; - /** - * This key is to address a file's size in - * {@link #getFiles(ResourceType, String)} map. - */ + /** Key 'size' for a file's length */ public final static String KEY_SIZE = "size"; /** - * Initializes the connector. This method will be called at the start of the - * webapp. + * Initializes the connector. This method will be called at the + * {@link ConnectorServlet#init() init} of the connector servlet. * * @param servletContext - * eg. to get the real path of a file for example. + * reference to the {@link ServletContext} in which the caller is + * executing + * @throws Exception + * if an exception occurs that interrupts the connectors's + * normal operation */ public void init(final ServletContext servletContext) throws Exception; /** - * Returns a list of file attributes. which are inside the abstract path - * /[type-folder]/[currentFolder]. Filename, file size (in - * bytes). + * Returns a list of file attributes from the backend. Use the pre-defined + * keys to put file attributes into the file map. The file length can be any + * instance of {@link Number}, its long value will be taken as the final + * value. * * @param type + * the current resource type * @param currentFolder - * @return A list of folder names. + * the current folder + * @return a list of file attributes * @throws InvalidCurrentFolderException + * if the current folder name is invalid or does not exist + * within the underlying backend * @throws ReadException + * if the file attributes could not be read due to some reason */ public List> getFiles(final ResourceType type, @@ -91,12 +103,16 @@ /** - * Returns a list of folders which are inside the abstract path - * /[type-folder]/[currentFolder]. + * Returns a list of folders from the backend. * * @param type + * the current resource type * @param currentFolder - * @return A list of file names. + * the current folder + * @return a list of folder names * @throws InvalidCurrentFolderException + * if the current folder name is invalid or does not exist + * within the underlying backend * @throws ReadException + * if the folder names could not be read due to some reason */ public List getFolders(final ResourceType type, @@ -105,15 +121,21 @@ /** - * Creates a new folder inside inside the abstract path - * /[type-folder]/[currentFolder]. + * Creates a new folder on the backend. * * @param type + * the current resource type * @param currentFolder + * the current folder * @param newFolder - * Name of the new folder to create. + * name of the new folder * @throws InvalidCurrentFolderException + * if the current folder name is invalid or does not exist + * within the underlying backend * @throws InvalidNewFolderNameException + * if the new folder name is invalid due to some reason * @throws FolderAlreadyExistsException + * if the new folder already exists * @throws WriteException + * if the new folder could not be created due to some reason */ public void createFolder(final ResourceType type, @@ -124,19 +146,21 @@ /** - * Uploads a new file into the abstract path - * /[type-folder]/[currentFolder]. If there is already a file - * with the same name, the new one has to be renamed by the following - * pattern: basename(count).ext
- * FileUpload and QuickUpload will be handled the same way since QuickUpload - * is just a specialization of FileUpload. + * Uploads a new file on to the backend. You are not allowed to overwrite + * already existing files, rename the new file and return the new filename. * * @param type + * the current resource type * @param currentFolder + * the current folder * @param fileName + * the name of the new file * @param inputStream - * Content of the file. - * @return fileName or the name of the renamed file. + * input stream of the new file + * @return the (eventually renamed) name of the uploaded file * @throws InvalidCurrentFolderException + * if the current folder name is invalid or does not exist + * within the underlying backend * @throws WriteException + * if the new file could not be created due to some reason */ public String fileUpload(final ResourceType type, Index: /FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/ConnectorServlet.java =================================================================== --- /FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/ConnectorServlet.java (revision 3576) +++ /FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/ConnectorServlet.java (revision 3577) @@ -93,11 +93,8 @@ } - /* - * (non-Javadoc) - * - * @see javax.servlet.http.HttpServlet#doGet(javax.servlet.http.HttpServletRequest , javax.servlet.http.HttpServletResponse) - */ @Override - protected void doGet(final HttpServletRequest request, final HttpServletResponse response) throws ServletException, IOException { + protected void doGet(final HttpServletRequest request, + final HttpServletResponse response) throws ServletException, + IOException { request.setCharacterEncoding("UTF-8"); response.setCharacterEncoding("UTF-8"); @@ -121,11 +118,8 @@ } - /* - * (non-Javadoc) - * - * @see javax.servlet.http.HttpServlet#doPost(javax.servlet.http.HttpServletRequest , javax.servlet.http.HttpServletResponse) - */ @Override - protected void doPost(final HttpServletRequest request, final HttpServletResponse response) throws ServletException, IOException { + protected void doPost(final HttpServletRequest request, + final HttpServletResponse response) throws ServletException, + IOException { request.setCharacterEncoding("UTF-8"); response.setCharacterEncoding("UTF-8"); Index: /FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/impl/AbstractLocalFileSystemConnector.java =================================================================== --- /FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/impl/AbstractLocalFileSystemConnector.java (revision 3576) +++ /FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/connector/impl/AbstractLocalFileSystemConnector.java (revision 3577) @@ -63,9 +63,4 @@ protected ServletContext servletContext; - /* (non-Javadoc) - * - * @see net.fckeditor.connector.Connector#fileUpload(net.fckeditor.handlers. - * ResourceType, java.lang.String, java.lang.String, java.io.InputStream) - */ public String fileUpload(final ResourceType type, final String currentFolder, final String fileName, @@ -90,11 +85,4 @@ } - /* - * (non-Javadoc) - * - * @see - * net.fckeditor.connector.Connector#createFolder(net.fckeditor.handlers - * .ResourceType, java.lang.String, java.lang.String) - */ public void createFolder(final ResourceType type, final String currentFolder, final String newFolder) @@ -115,10 +103,4 @@ } - /* - * (non-Javadoc) - * - * @see net.fckeditor.connector.Connector#getFiles(net.fckeditor.handlers. - * ResourceType, java.lang.String) - */ public List> getFiles(ResourceType type, String currentFolder) throws InvalidCurrentFolderException { @@ -145,10 +127,4 @@ } - /* - * (non-Javadoc) - * - * @see net.fckeditor.connector.Connector#getFolders(net.fckeditor.handlers. - * ResourceType, java.lang.String) - */ public List getFolders(final ResourceType type, final String currentFolder) throws InvalidCurrentFolderException { 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 3576) +++ /FCKeditor.Java/trunk/java-core/src/main/java/net/fckeditor/response/GetResponse.java (revision 3577) @@ -191,4 +191,5 @@ * Sets the folders of this get response. * + * @see Connector#getFolders(ResourceType, String) * @param folders * the folders of this get response @@ -213,4 +214,5 @@ * Sets the folders of this get response. * + * @see Connector#getFiles(ResourceType, String) * @param files * the files of this get response Index: /FCKeditor.Java/trunk/java-core/src/main/javadoc/net/fckeditor/connector/exception/package.html =================================================================== --- /FCKeditor.Java/trunk/java-core/src/main/javadoc/net/fckeditor/connector/exception/package.html (revision 3576) +++ /FCKeditor.Java/trunk/java-core/src/main/javadoc/net/fckeditor/connector/exception/package.html (revision 3577) @@ -35,23 +35,4 @@ by the a localized message of the system. -

Additional Exceptions

- -More over you may throw following standard exceptions to indicate a -system failure: -
    -
  • IOException: Indicates that the failure of a file - write action. -
  • SecurityException: Indicates that the file or - folder action has been denied according to the underlying SecurityManager or the user has no rights to - perform this action according to a {@link - net.fckeditor.requestcycle.UserAction UserAction} implementation. -
-