001package systems.dmx.files;
002
003import systems.dmx.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>dmx.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>dmx.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>dmx.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>dmx.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>dmx.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>dmx.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>dmx.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 DMX 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 DMX 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>dmx.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>dmx.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>dmx.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>dmx.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    int openFile(long fileTopicId);
276}