1 /*
2 * FCKeditor - The text editor for Internet - http://www.fckeditor.net
3 * Copyright (C) 2004-2010 Frederico Caldeira Knabben
4 *
5 * == BEGIN LICENSE ==
6 *
7 * Licensed under the terms of any of the following licenses at your
8 * choice:
9 *
10 * - GNU General Public License Version 2 or later (the "GPL")
11 * http://www.gnu.org/licenses/gpl.html
12 *
13 * - GNU Lesser General Public License Version 2.1 or later (the "LGPL")
14 * http://www.gnu.org/licenses/lgpl.html
15 *
16 * - Mozilla Public License Version 1.1 or later (the "MPL")
17 * http://www.mozilla.org/MPL/MPL-1.1.html
18 *
19 * == END LICENSE ==
20 */
21 package net.fckeditor.connector;
22
23 import java.io.InputStream;
24 import java.util.List;
25 import java.util.Map;
26
27 import javax.servlet.ServletContext;
28
29 import net.fckeditor.connector.exception.FolderAlreadyExistsException;
30 import net.fckeditor.connector.exception.InvalidCurrentFolderException;
31 import net.fckeditor.connector.exception.InvalidNewFolderNameException;
32 import net.fckeditor.connector.exception.ReadException;
33 import net.fckeditor.connector.exception.WriteException;
34 import net.fckeditor.connector.impl.AbstractLocalFileSystemConnector;
35 import net.fckeditor.handlers.RequestCycleHandler;
36 import net.fckeditor.handlers.ResourceType;
37 import net.fckeditor.requestcycle.ThreadLocalData;
38
39 /**
40 * Backend interface of a File Browser connector. A connector serves and manages
41 * files and folders accessed through the File Browser on an arbitrary backend
42 * system.<br />
43 * The connector will receive a request if, and only if, the request was valid
44 * in terms of valid and reasonable parameters up to an abstract point which is
45 * independent from a specific connector implementation.
46 * <p>
47 * Helpful classes and methods:
48 * <ol>
49 * <li>If you need to access the request instance itself and/or the context
50 * parameters sent from the File Browser, take a look at the
51 * {@link ThreadLocalData} class.</li>
52 * <li>Use
53 * {@link RequestCycleHandler#getUserFilesAbsolutePath(javax.servlet.http.HttpServletRequest)
54 * RequestCycleHandler.getUserFilesAbsolutePath},
55 * {@link AbstractLocalFileSystemConnector#getRealUserFilesAbsolutePath(java.lang.String)
56 * AbstractLocalFileSystemConnector.getRealUserFilesAbsolutePath} (if use it) to
57 * resolve the real path or simply do it yourself.</li>
58 * </ol>
59 * </p>
60 *
61 * @version $Id: Connector.java 4785 2009-12-21 20:10:28Z mosipov $
62 */
63 public interface Connector {
64
65 /** Key 'name' for a file's name */
66 public final static String KEY_NAME = "name";
67
68 /** Key 'size' for a file's length */
69 public final static String KEY_SIZE = "size";
70
71 /**
72 * Initializes this connector. Called at {@link Dispatcher dispatcher}
73 * initialization.
74 *
75 * @param servletContext
76 * reference to the {@link ServletContext} in which the caller is
77 * running
78 * @throws Exception
79 * if the connector initialization fails due to some reason
80 */
81 public void init(final ServletContext servletContext) throws Exception;
82
83 /**
84 * Returns a list of file attributes from the backend. Use the pre-defined
85 * keys ({@value #KEY_NAME}, {@value #KEY_SIZE}) to put file attributes into
86 * the file map. The file length can be any instance of {@link Number}, its
87 * long value will be taken as the final value.
88 *
89 * @param type
90 * the current resource type
91 * @param currentFolder
92 * the current folder
93 * @return a list of file attributes
94 * @throws InvalidCurrentFolderException
95 * if the current folder name is invalid or does not exist
96 * within the underlying backend
97 * @throws ReadException
98 * if the file attributes could not be read due to some reason
99 */
100 public List<Map<String, Object>> getFiles(final ResourceType type,
101 final String currentFolder) throws InvalidCurrentFolderException,
102 ReadException;
103
104 /**
105 * Returns a list of folders from the backend.
106 *
107 * @param type
108 * the current resource type
109 * @param currentFolder
110 * the current folder
111 * @return a list of folder names
112 * @throws InvalidCurrentFolderException
113 * if the current folder name is invalid or does not exist
114 * within the underlying backend
115 * @throws ReadException
116 * if the folder names could not be read due to some reason
117 */
118 public List<String> getFolders(final ResourceType type,
119 final String currentFolder) throws InvalidCurrentFolderException,
120 ReadException;
121
122 /**
123 * Creates a new folder on the backend.
124 *
125 * @param type
126 * the current resource type
127 * @param currentFolder
128 * the current folder
129 * @param newFolder
130 * name of the new folder
131 * @throws InvalidCurrentFolderException
132 * if the current folder name is invalid or does not exist
133 * within the underlying backend
134 * @throws InvalidNewFolderNameException
135 * if the new folder name is invalid due to some reason
136 * @throws FolderAlreadyExistsException
137 * if the new folder already exists
138 * @throws WriteException
139 * if the new folder could not be created due to some reason
140 */
141 public void createFolder(final ResourceType type,
142 final String currentFolder, final String newFolder)
143 throws InvalidCurrentFolderException,
144 InvalidNewFolderNameException, FolderAlreadyExistsException,
145 WriteException;
146
147 /**
148 * Uploads a new file on to the backend. You are not allowed to overwrite
149 * already existing files, rename the new file and return the new filename.
150 *
151 * @param type
152 * the current resource type
153 * @param currentFolder
154 * the current folder
155 * @param fileName
156 * the name of the new file
157 * @param inputStream
158 * input stream of the new file
159 * @return the (eventually renamed) name of the uploaded file
160 * @throws InvalidCurrentFolderException
161 * if the current folder name is invalid or does not exist
162 * within the underlying backend
163 * @throws WriteException
164 * if the new file could not be created due to some reason
165 */
166 public String fileUpload(final ResourceType type,
167 final String currentFolder, final String fileName,
168 final InputStream inputStream)
169 throws InvalidCurrentFolderException, WriteException;
170
171 }