001/*
002 * (C) Copyright 2012 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Antoine Taillefer <ataillefer@nuxeo.com>
018 */
019package org.nuxeo.drive.service;
020
021import java.security.Principal;
022import java.util.List;
023
024import org.nuxeo.drive.adapter.FileItem;
025import org.nuxeo.drive.adapter.FileSystemItem;
026import org.nuxeo.drive.adapter.FolderItem;
027import org.nuxeo.drive.adapter.ScrollFileSystemItemList;
028import org.nuxeo.drive.service.impl.FileSystemItemManagerImpl;
029import org.nuxeo.ecm.core.api.Blob;
030import org.nuxeo.ecm.core.api.CoreInstance;
031import org.nuxeo.ecm.core.api.CoreSession;
032
033/**
034 * Provides an API to manage usual file system operations on a {@link FileSystemItem} given its id. Allows the following
035 * actions:
036 * <ul>
037 * <li>Read</li>
038 * <li>Read children</li>
039 * <li>Read descendants</li>
040 * <li>Create</li>
041 * <li>Update</li>
042 * <li>Delete</li>
043 * <li>Rename</li>
044 * <li>Move</li>
045 * </ul>
046 *
047 * @author Antoine Taillefer
048 * @see FileSystemItemManagerImpl
049 */
050public interface FileSystemItemManager {
051
052    /**
053     * Gets a session bound to the given repository for the given principal.
054     *
055     * @deprecated since 7.2, use {@link CoreInstance#openCoreSession(String, Principal)} instead.
056     */
057    @Deprecated
058    CoreSession getSession(String repositoryName, Principal principal);
059
060    /*------------- Read operations ----------------*/
061    /**
062     * Gets the children of the top level {@link FolderItem} for the given principal.
063     *
064     * @deprecated use getTopLevelFolder#getChildren instead
065     */
066    @Deprecated
067    List<FileSystemItem> getTopLevelChildren(Principal principal);
068
069    /**
070     * Gets the top level {@link FolderItem} for the given principal.
071     */
072    FolderItem getTopLevelFolder(Principal principal);
073
074    /**
075     * Returns true if a {@link FileSystemItem} with the given id exists for the given principal.
076     *
077     * @see FileSystemItemFactory#exists(String, Principal)
078     */
079    boolean exists(String id, Principal principal);
080
081    /**
082     * Gets the {@link FileSystemItem} with the given id for the given principal.
083     *
084     * @return the {@link FileSystemItem} or null if none matches the given id
085     * @see FileSystemItemFactory#getFileSystemItemById(String, Principal)
086     */
087    FileSystemItem getFileSystemItemById(String id, Principal principal);
088
089    /**
090     * Gets the {@link FileSystemItem} with the given id and parent id for the given principal.
091     *
092     * @return the {@link FileSystemItem} or null if none matches the given id and parent id
093     * @see #getFileSystemItemById(String, Principal)
094     * @since 6.0
095     */
096    FileSystemItem getFileSystemItemById(String id, String parentId, Principal principal);
097
098    /**
099     * Gets the children of the {@link FileSystemItem} with the given id for the given principal.
100     *
101     * @see FolderItem#getChildren()
102     */
103    List<FileSystemItem> getChildren(String id, Principal principal);
104
105    /**
106     * Retrieves at most {@code batchSize} descendants of the {@link FolderItem} with the given {@code id} for the given
107     * {@code principal} and the given {@code scrollId}.
108     * <p>
109     * When passing a null {@code scrollId} the initial search request is executed and the first batch of results is
110     * returned along with a {@code scrollId} which should be passed to the next call in order to retrieve the next
111     * batch of results.
112     * <p>
113     * Ideally, the search context made available by the initial search request is kept alive during {@code keepAlive}
114     * milliseconds if {@code keepAlive} is positive.
115     * <p>
116     * Results are not necessarily sorted.
117     *
118     * @see FolderItem#scrollDescendants(String, int, long)
119     * @since 8.3
120     */
121    ScrollFileSystemItemList scrollDescendants(String id, Principal principal, String scrollId, int batchSize,
122            long keepAlive);
123
124    /**
125     * Return true if the {@link FileSystemItem} with the given source id can be moved to the {@link FileSystemItem}
126     * with the given destination id for the given principal.
127     *
128     * @see FileSystemItem#getCanMove(String)
129     */
130    boolean canMove(String srcId, String destId, Principal principal);
131
132    /*------------- Write operations ----------------*/
133    /**
134     * Creates a folder with the given name in the {@link FileSystemItem} with the given id for the given principal.
135     *
136     * @see FolderItem#createFolder(String)
137     * @deprecated since 9.1, use {@link #createFolder(String, String, Principal, boolean)} instead
138     */
139    @Deprecated
140    default FolderItem createFolder(String parentId, String name, Principal principal) {
141        return createFolder(parentId, name, principal, false);
142    }
143
144    /**
145     * Creates a folder with the given name in the {@link FileSystemItem} with the given id for the given principal.
146     *
147     * @param overwrite allows to overwrite an existing folder with the same title
148     * @see FolderItem#createFolder(String, boolean)
149     * @since 9.1
150     */
151    FolderItem createFolder(String parentId, String name, Principal principal, boolean overwrite);
152
153    /**
154     * Creates a file with the given blob in the {@link FileSystemItem} with the given id for the given principal.
155     *
156     * @see FolderItem#createFile(Blob)
157     * @deprecated since 9.1, use {@link #createFile(String, Blob, Principal, boolean)} instead
158     */
159    @Deprecated
160    default FileItem createFile(String parentId, Blob blob, Principal principal) {
161        return createFile(parentId, blob, principal, false);
162    }
163
164    /**
165     * Creates a file with the given blob in the {@link FileSystemItem} with the given id for the given principal.
166     *
167     * @param overwrite allows to overwrite an existing folder with the same title
168     * @see FolderItem#createFile(Blob, boolean)
169     * @since 9.1
170     */
171    FileItem createFile(String parentId, Blob blob, Principal principal, boolean overwrite);
172
173    /**
174     * Updates the {@link FileSystemItem} with the given id with the given blob for the given principal.
175     *
176     * @see FileItem#setBlob(Blob)
177     */
178    FileItem updateFile(String id, Blob blob, Principal principal);
179
180    /**
181     * Updates the {@link FileSystemItem} with the given id and parent id with the given blob for the given principal.
182     *
183     * @see #updateFile(String, Blob, Principal)
184     * @since 6.0
185     */
186    FileItem updateFile(String id, String parentId, Blob blob, Principal principal);
187
188    /**
189     * Deletes the {@link FileSystemItem} with the given id for the given principal.
190     *
191     * @see FileSystemItem#delete()
192     */
193    void delete(String id, Principal principal);
194
195    /**
196     * Deletes the {@link FileSystemItem} with the given id and parent id for the given principal.
197     *
198     * @see #delete(String, Principal)
199     * @since 6.0
200     */
201    void delete(String id, String parentId, Principal principal);
202
203    /**
204     * Renames the {@link FileSystemItem} with the given id with the given name for the given principal.
205     *
206     * @see FileSystemItem#rename(String)
207     */
208    FileSystemItem rename(String id, String name, Principal principal);
209
210    /**
211     * Moves the {@link FileSystemItem} with the given source id to the {@link FileSystemItem} with the given
212     * destination id for the given principal.
213     *
214     * @see FileSystemItem#move(String)
215     */
216    FileSystemItem move(String srcId, String destId, Principal principal);
217
218}