001package de.deepamehta.plugins.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 path A repository path. Relative to the repository base path. 022 * Must begin with slash, no slash at the end. 023 * 024 * @return The File topic. Its child topics ("File Name", "Path", "Media Type", "Size") are included. 025 */ 026 Topic getFileTopic(String path); 027 028 /** 029 * Returns the Folder topic representing the folder at a given repository path. 030 * If no such Folder topic exists it is created. 031 * 032 * @param path A repository path. Relative to the repository base path. 033 * Must begin with slash, no slash at the end. 034 * 035 * @return The Folder topic. Its child topics ("Folder Name", "Path") are included. 036 */ 037 Topic getFolderTopic(String path); 038 039 // --- 040 041 /** 042 * Returns the File topic representing the file at a given repository path. 043 * If no such File topic exists it is created. 044 * <p> 045 * Creates an association (type "Aggregation") between the File topic (role type "Child") 046 * and its parent Folder topic (role type "Parent"), if not exists already. 047 * 048 * @param path A repository path. Relative to the repository base path. 049 * Must begin with slash, no slash at the end. 050 * @param folderTopicId ID of the parent Folder topic. 051 * 052 * @return The File topic. Its child topics ("File Name", "Path", "Media Type", "Size") are included. 053 */ 054 Topic getChildFileTopic(long folderTopicId, String path); 055 056 /** 057 * Returns the Folder topic representing the folder at a given repository path. 058 * If no such Folder topic exists it is created. 059 * <p> 060 * Creates an association (type "Aggregation") between the Folder topic (role type "Child") 061 * and its parent Folder topic (role type "Parent"), if not exists already. 062 * 063 * @param path A repository path. Relative to the repository base path. 064 * Must begin with slash, no slash at the end. 065 * @param folderTopicId ID of the parent Folder topic. 066 * 067 * @return The Folder topic. Its child topics ("Folder Name", "Path") are included. 068 */ 069 Topic getChildFolderTopic(long folderTopicId, String path); 070 071 072 073 // === File Repository === 074 075 /** 076 * Receives an uploaded file, stores it in the file repository, and creates a corresponding File topic. 077 * 078 * @param path The directory where to store the uploaded file. 079 * A repository path. Relative to the repository base path. 080 * Must begin with slash, no slash at the end. 081 * The directory must exist. 082 * 083 * @return a StoredFile object which holds 2 information: the name of the uploaded file, and the ID 084 * of the created File topic. 085 */ 086 StoredFile storeFile(UploadedFile file, String path); 087 088 /** 089 * Creates a file in the file repository, and creates a corresponding File topic. 090 * 091 * @param in The input stream the file content is read from. 092 * @param path The path and filename of the file to be created. 093 * A repository path. Relative to the repository base path. 094 * Must begin with slash, no slash at the end. 095 * If that file exists already it is overwritten. ### TODO: rethink overwriting 096 * 097 * @return the File topic that corresponds to the created file. 098 */ 099 Topic createFile(InputStream in, String path); 100 101 /** 102 * Creates a folder in the file repository. 103 * Note: to corresponding Folder topic is created. 104 * 105 * @param path The directory where to create the folder. 106 * A repository path. Relative to the repository base path. 107 * Must begin with slash, no slash at the end. 108 */ 109 void createFolder(String folderName, String path); 110 111 // --- 112 113 ResourceInfo getResourceInfo(String path); 114 115 DirectoryListing getDirectoryListing(String path); 116 117 /** 118 * Checks if the given URL refers to the file repository of this DeepaMehta installation. 119 * 120 * @return the refered file's/directory's repository path, or <code>null</code> if the URL 121 * does not refer to the file repository of this DeepaMehta installation. 122 */ 123 String getRepositoryPath(URL url); 124 125 // --- 126 127 /** 128 * Accesses a file/directory in the file repository by the given repository path. 129 * Note: this method doesn't require the corresponding File/Folder topic to exist. 130 * 131 * @param path A repository path. Relative to the repository base path. 132 * Must begin with slash, no slash at the end. 133 */ 134 File getFile(String path); 135 136 /** 137 * Accesses a file/directory in the file repository that is represented by the given File/Folder topic. 138 */ 139 File getFile(long fileTopicId); 140 141 // --- 142 143 void openFile(long fileTopicId); 144}