View Javadoc

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 }