001package de.deepamehta.files; 002 003import de.deepamehta.core.Topic; 004 005import java.io.File; 006import java.io.InputStream; 007import java.net.URL; 008 009 010 011public interface FilesService { 012 013 014 015 // === File System Representation === 016 017 /** 018 * Returns the File topic representing the file at a given repository path. 019 * If no such File topic exists it is created. 020 * 021 * @param repoPath A repository path. Relative to the repository base path. 022 * Must begin with slash, no slash at the end. 023 * <p> 024 * If per-workspace file repos are active (<code>dm4.filerepo.per_workspace=true</code>) 025 * the repository path must contain the workspace prefix as the first path segment, 026 * e.g. <code>"/workspace-1234"</code> where <code>1234</code> is the workspace ID. 027 * <p> 028 * However there is one exception to that rule: if and only if <code>"/"</code> is passed 029 * as the repository path the workspace prefix is determined automatically with the 030 * semantics of <i>current workspace</i>, based on the request's workspace cookie. 031 * <p> 032 * For support with constructing a repository path see the {@link pathPrefix} methods. 033 * 034 * @return The File topic. Its child topics ("File Name", "Path", "Media Type", "Size") are included. 035 */ 036 Topic getFileTopic(String repoPath); 037 038 /** 039 * Returns the Folder topic representing the folder at a given repository path. 040 * If no such Folder topic exists it is created. 041 * 042 * @param repoPath A repository path. Relative to the repository base path. 043 * Must begin with slash, no slash at the end. 044 * <p> 045 * If per-workspace file repos are active (<code>dm4.filerepo.per_workspace=true</code>) 046 * the repository path must contain the workspace prefix as the first path segment, 047 * e.g. <code>"/workspace-1234"</code> where <code>1234</code> is the workspace ID. 048 * <p> 049 * However there is one exception to that rule: if and only if <code>"/"</code> is passed 050 * as the repository path the workspace prefix is determined automatically with the 051 * semantics of <i>current workspace</i>, based on the request's workspace cookie. 052 * <p> 053 * For support with constructing a repository path see the {@link pathPrefix} methods. 054 * 055 * @return The Folder topic. Its child topics ("Folder Name", "Path") are included. 056 */ 057 Topic getFolderTopic(String repoPath); 058 059 // --- 060 061 /** 062 * Returns the File topic representing the file at a given repository path. 063 * If no such File topic exists it is created. 064 * <p> 065 * Creates an association (type "Aggregation") between the File topic (role type "Child") 066 * and its parent Folder topic (role type "Parent"), if not exists already. 067 * 068 * @param repoPath A repository path. Relative to the repository base path. 069 * Must begin with slash, no slash at the end. 070 * <p> 071 * If per-workspace file repos are active (<code>dm4.filerepo.per_workspace=true</code>) 072 * the repository path must contain the workspace prefix as the first path segment, 073 * e.g. <code>"/workspace-1234"</code> where <code>1234</code> is the workspace ID. 074 * <p> 075 * However there is one exception to that rule: if and only if <code>"/"</code> is passed 076 * as the repository path the workspace prefix is determined automatically with the 077 * semantics of <i>current workspace</i>, based on the request's workspace cookie. 078 * <p> 079 * For support with constructing a repository path see the {@link pathPrefix} methods. 080 * 081 * @param folderTopicId ID of the parent Folder topic. 082 * 083 * @return The File topic. Its child topics ("File Name", "Path", "Media Type", "Size") are included. 084 */ 085 Topic getChildFileTopic(long folderTopicId, String repoPath); 086 087 /** 088 * Returns the Folder topic representing the folder at a given repository path. 089 * If no such Folder topic exists it is created. 090 * <p> 091 * Creates an association (type "Aggregation") between the Folder topic (role type "Child") 092 * and its parent Folder topic (role type "Parent"), if not exists already. 093 * 094 * @param repoPath A repository path. Relative to the repository base path. 095 * Must begin with slash, no slash at the end. 096 * <p> 097 * If per-workspace file repos are active (<code>dm4.filerepo.per_workspace=true</code>) 098 * the repository path must contain the workspace prefix as the first path segment, 099 * e.g. <code>"/workspace-1234"</code> where <code>1234</code> is the workspace ID. 100 * <p> 101 * However there is one exception to that rule: if and only if <code>"/"</code> is passed 102 * as the repository path the workspace prefix is determined automatically with the 103 * semantics of <i>current workspace</i>, based on the request's workspace cookie. 104 * <p> 105 * For support with constructing a repository path see the {@link pathPrefix} methods. 106 * 107 * @param folderTopicId ID of the parent Folder topic. 108 * 109 * @return The Folder topic. Its child topics ("Folder Name", "Path") are included. 110 */ 111 Topic getChildFolderTopic(long folderTopicId, String repoPath); 112 113 114 115 // === File Repository === 116 117 /** 118 * Receives an uploaded file, stores it in the file repository, and creates a corresponding File topic. 119 * 120 * @param repoPath The directory where to store the uploaded file. 121 * The directory must exist. 122 * <p> 123 * A repository path. Relative to the repository base path. 124 * Must begin with slash, no slash at the end. 125 * <p> 126 * If per-workspace file repos are active (<code>dm4.filerepo.per_workspace=true</code>) 127 * the repository path must contain the workspace prefix as the first path segment, 128 * e.g. <code>"/workspace-1234"</code> where <code>1234</code> is the workspace ID. 129 * <p> 130 * However there is one exception to that rule: if and only if <code>"/"</code> is passed 131 * as the repository path the workspace prefix is determined automatically with the 132 * semantics of <i>current workspace</i>, based on the request's workspace cookie. 133 * <p> 134 * For support with constructing a repository path see the {@link pathPrefix} methods. 135 * 136 * @return a StoredFile object which holds 2 information: the name of the uploaded file, and the ID 137 * of the created File topic. 138 */ 139 StoredFile storeFile(UploadedFile file, String repoPath); 140 141 /** 142 * Creates a file in the file repository and a corresponding File topic. 143 * 144 * @param in The input stream the file content is read from. 145 * @param repoPath The path and filename of the file to be created. 146 * If that file exists already it is overwritten. ### TODO: rethink overwriting 147 * <p> 148 * A repository path. Relative to the repository base path. 149 * Must begin with slash, no slash at the end. 150 * <p> 151 * If per-workspace file repos are active (<code>dm4.filerepo.per_workspace=true</code>) 152 * the repository path must contain the workspace prefix as the first path segment, 153 * e.g. <code>"/workspace-1234"</code> where <code>1234</code> is the workspace ID. 154 * <p> 155 * However there is one exception to that rule: if and only if <code>"/"</code> is passed 156 * as the repository path the workspace prefix is determined automatically with the 157 * semantics of <i>current workspace</i>, based on the request's workspace cookie. 158 * <p> 159 * For support with constructing a repository path see the {@link pathPrefix} methods. 160 * 161 * @return the File topic that corresponds to the created file. 162 */ 163 Topic createFile(InputStream in, String repoPath); 164 165 /** 166 * Creates a folder in the file repository. 167 * Note: no corresponding Folder topic is created. 168 * 169 * @param repoPath The directory where to create the folder. 170 * <p> 171 * A repository path. Relative to the repository base path. 172 * Must begin with slash, no slash at the end. 173 * <p> 174 * If per-workspace file repos are active (<code>dm4.filerepo.per_workspace=true</code>) 175 * the repository path must contain the workspace prefix as the first path segment, 176 * e.g. <code>"/workspace-1234"</code> where <code>1234</code> is the workspace ID. 177 * <p> 178 * However there is one exception to that rule: if and only if <code>"/"</code> is passed 179 * as the repository path the workspace prefix is determined automatically with the 180 * semantics of <i>current workspace</i>, based on the request's workspace cookie. 181 * <p> 182 * For support with constructing a repository path see the {@link pathPrefix} methods. 183 */ 184 void createFolder(String folderName, String repoPath); 185 186 // --- 187 188 ResourceInfo getResourceInfo(String repoPath); 189 190 DirectoryListing getDirectoryListing(String repoPath); 191 192 /** 193 * Checks if the given URL refers to the file repository of this DeepaMehta installation. 194 * 195 * @return the refered file's/directory's repository path, or <code>null</code> if the URL 196 * does not refer to the file repository of this DeepaMehta installation. 197 */ 198 String getRepositoryPath(URL url); 199 200 // --- 201 202 /** 203 * Accesses a file/directory in the file repository by the given repository path. 204 * If no such file/directory exists a FileRepositoryException is thrown. 205 * <p> 206 * Note: this method does not require the corresponding File/Folder <i>topic</i> to exist. 207 * 208 * @param repoPath A repository path. Relative to the repository base path. 209 * Must begin with slash, no slash at the end. 210 * <p> 211 * If per-workspace file repos are active (<code>dm4.filerepo.per_workspace=true</code>) 212 * the repository path must contain the workspace prefix as the first path segment, 213 * e.g. <code>"/workspace-1234"</code> where <code>1234</code> is the workspace ID. 214 * <p> 215 * However there is one exception to that rule: if and only if <code>"/"</code> is passed 216 * as the repository path the workspace prefix is determined automatically with the 217 * semantics of <i>current workspace</i>, based on the request's workspace cookie. 218 * <p> 219 * For support with constructing a repository path see the {@link pathPrefix} methods. 220 * 221 * @throws FileRepositoryException with status code 404 if no such file/directory exists in the file repository. 222 */ 223 File getFile(String repoPath); 224 225 /** 226 * Convenience method to access the file/directory in the file repository that is represented by the given 227 * File/Folder topic. 228 * 229 * @param fileTopicId ID of a File/Folder topic. 230 */ 231 File getFile(long fileTopicId); 232 233 // --- 234 235 /** 236 * Checks if a file/directory with the given repository path exists in the file repository. 237 * 238 * @param repoPath A repository path. Relative to the repository base path. 239 * Must begin with slash, no slash at the end. 240 * <p> 241 * If per-workspace file repos are active (<code>dm4.filerepo.per_workspace=true</code>) 242 * the repository path must contain the workspace prefix as the first path segment, 243 * e.g. <code>"/workspace-1234"</code> where <code>1234</code> is the workspace ID. 244 * <p> 245 * However there is one exception to that rule: if and only if <code>"/"</code> is passed 246 * as the repository path the workspace prefix is determined automatically with the 247 * semantics of <i>current workspace</i>, based on the request's workspace cookie. 248 * <p> 249 * For support with constructing a repository path see the {@link pathPrefix} methods. 250 * 251 * @return <code>true</code> if the file exists, <code>false</code> otherwise. 252 */ 253 boolean fileExists(String repoPath); 254 255 // --- 256 257 /** 258 * Returns a prefix that can be used for constructing a repository path. 259 * In case of per-workspace file repos are active (<code>dm4.filerepo.per_workspace=true</code>) the prefix 260 * represents the <i>current</i> workspace (e.g. <code>"/workspace-1234"</code>), based on the workspace cookie. 261 * In case of per-workspace file repos are <i>not</i> active an empty string is returned. 262 */ 263 String pathPrefix(); 264 265 /** 266 * Returns a prefix that can be used for constructing a repository path. 267 * In case of per-workspace file repos are active (<code>dm4.filerepo.per_workspace=true</code>) the prefix 268 * represents the <i>given</i> workspace (e.g. <code>"/workspace-1234"</code>). 269 * In case of per-workspace file repos are <i>not</i> active an empty string is returned. 270 */ 271 String pathPrefix(long workspaceId); 272 273 // --- 274 275 void openFile(long fileTopicId); 276}