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}