001    package de.deepamehta.plugins.files.service;
002    
003    import de.deepamehta.plugins.files.DirectoryListing;
004    import de.deepamehta.plugins.files.ResourceInfo;
005    import de.deepamehta.plugins.files.StoredFile;
006    import de.deepamehta.plugins.files.UploadedFile;
007    
008    import de.deepamehta.core.Topic;
009    import de.deepamehta.core.service.ClientState;
010    import de.deepamehta.core.service.PluginService;
011    
012    import java.io.File;
013    import java.io.InputStream;
014    import java.net.URL;
015    
016    
017    
018    public interface FilesService extends PluginService {
019    
020    
021    
022        // === File System Representation ===
023    
024        /**
025         * Creates and returns a File topic representing the file at a given repository path.
026         * If such a File topic exists already that topic is returned.
027         *
028         * @param   path    A repository path. Relative to the repository base path.
029         *                  Must begin with slash, no slash at the end.
030         */
031        Topic createFileTopic(String path, ClientState clientState);
032    
033        /**
034         * Creates and returns a Folder topic representing the folder at a given repository path.
035         * If such a Folder topic exists already that topic is returned.
036         *
037         * @param   path    A repository path. Relative to the repository base path.
038         *                  Must begin with slash, no slash at the end.
039         */
040        Topic createFolderTopic(String path, ClientState clientState);
041    
042        // ---
043    
044        Topic createChildFileTopic(long folderTopicId, String path, ClientState clientState);
045    
046        Topic createChildFolderTopic(long folderTopicId, String path, ClientState clientState);
047    
048    
049    
050        // === File Repository ===
051    
052        /**
053         * Receives an uploaded file, stores it in the file repository, and creates a corresponding File topic.
054         *
055         * @param   path    The directory where to store the uploaded file.
056         *                  A repository path. Relative to the repository base path.
057         *                  Must begin with slash, no slash at the end.
058         *                  The directory must exist.
059         *
060         * @return  a StoredFile object which holds 2 information: the name of the uploaded file, and the ID
061         *          of the created File topic.
062         */
063        StoredFile storeFile(UploadedFile file, String path, ClientState clientState);
064    
065        /**
066         * Creates a file in the file repository, and creates a corresponding File topic.
067         *
068         * @param   in      The input stream the file content is read from.
069         * @param   path    The path and filename of the file to be created.
070         *                  A repository path. Relative to the repository base path.
071         *                  Must begin with slash, no slash at the end.
072         *                  If that file exists already it is overwritten. ### TODO: rethink overwriting
073         *
074         * @return  the File topic that corresponds to the created file.
075         */
076        Topic createFile(InputStream in, String path);
077    
078        /**
079         * Creates a folder in the file repository.
080         * Note: to corresponding Folder topic is created.
081         *
082         * @param   path    The directory where to create the folder.
083         *                  A repository path. Relative to the repository base path.
084         *                  Must begin with slash, no slash at the end.
085         */
086        void createFolder(String folderName, String path);
087    
088        // ---
089    
090        ResourceInfo getResourceInfo(String path);
091    
092        DirectoryListing getDirectoryListing(String path);
093    
094        /**
095         * Checks if the given URL refers to the file repository of this DeepaMehta installation.
096         *
097         * @return  the refered file's/directory's repository path, or <code>null</code> if the URL
098         *          does not refer to the file repository of this DeepaMehta installation.
099         */
100        String getRepositoryPath(URL url);
101    
102        // ---
103    
104        /**
105         * Accesses a file/directory in the file repository by the given repository path.
106         * Note: this method doesn't require the corresponding File/Folder topic to exist.
107         *
108         * @param   path    A repository path. Relative to the repository base path.
109         *                  Must begin with slash, no slash at the end.
110         */
111        File getFile(String path);
112    
113        /**
114         * Accesses a file/directory in the file repository that is represented by the given File/Folder topic.
115         */
116        File getFile(long fileTopicId);
117    
118        // ---
119    
120        void openFile(long fileTopicId);
121    }