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 <[email protected]>
018 */
019package org.nuxeo.drive.service;
020
021import java.util.List;
022
023import org.nuxeo.drive.adapter.FileItem;
024import org.nuxeo.drive.adapter.FileSystemItem;
025import org.nuxeo.drive.adapter.FolderItem;
026import org.nuxeo.drive.adapter.ScrollFileSystemItemList;
027import org.nuxeo.drive.service.impl.FileSystemItemManagerImpl;
028import org.nuxeo.ecm.core.api.Blob;
029import org.nuxeo.ecm.core.api.NuxeoPrincipal;
030
031/**
032 * Provides an API to manage usual file system operations on a {@link FileSystemItem} given its id. Allows the following
033 * actions:
034 * <ul>
035 * <li>Read</li>
036 * <li>Read children</li>
037 * <li>Read descendants</li>
038 * <li>Create</li>
039 * <li>Update</li>
040 * <li>Delete</li>
041 * <li>Rename</li>
042 * <li>Move</li>
043 * </ul>
044 *
045 * @author Antoine Taillefer
046 * @see FileSystemItemManagerImpl
047 */
048public interface FileSystemItemManager {
049
050    /*------------- Read operations ----------------*/
051    /**
052     * Gets the top level {@link FolderItem} for the given principal.
053     */
054    FolderItem getTopLevelFolder(NuxeoPrincipal principal);
055
056    /**
057     * Returns true if a {@link FileSystemItem} with the given id exists for the given principal.
058     *
059     * @see FileSystemItemFactory#exists(String, NuxeoPrincipal)
060     */
061    boolean exists(String id, NuxeoPrincipal principal);
062
063    /**
064     * Gets the {@link FileSystemItem} with the given id for the given principal.
065     *
066     * @return the {@link FileSystemItem} or null if none matches the given id
067     * @see FileSystemItemFactory#getFileSystemItemById(String, NuxeoPrincipal)
068     */
069    FileSystemItem getFileSystemItemById(String id, NuxeoPrincipal principal);
070
071    /**
072     * Gets the {@link FileSystemItem} with the given id and parent id for the given principal.
073     *
074     * @return the {@link FileSystemItem} or null if none matches the given id and parent id
075     * @see #getFileSystemItemById(String, NuxeoPrincipal)
076     * @since 6.0
077     */
078    FileSystemItem getFileSystemItemById(String id, String parentId, NuxeoPrincipal principal);
079
080    /**
081     * Gets the children of the {@link FileSystemItem} with the given id for the given principal.
082     *
083     * @see FolderItem#getChildren()
084     */
085    List<FileSystemItem> getChildren(String id, NuxeoPrincipal principal);
086
087    /**
088     * Retrieves at most {@code batchSize} descendants of the {@link FolderItem} with the given {@code id} for the given
089     * {@code principal} and the given {@code scrollId}.
090     * <p>
091     * When passing a null {@code scrollId} the initial search request is executed and the first batch of results is
092     * returned along with a {@code scrollId} which should be passed to the next call in order to retrieve the next
093     * batch of results.
094     * <p>
095     * Ideally, the search context made available by the initial search request is kept alive during {@code keepAlive}
096     * milliseconds if {@code keepAlive} is positive.
097     * <p>
098     * Results are not necessarily sorted.
099     *
100     * @see FolderItem#scrollDescendants(String, int, long)
101     * @since 8.3
102     */
103    ScrollFileSystemItemList scrollDescendants(String id, NuxeoPrincipal principal, String scrollId, int batchSize,
104            long keepAlive);
105
106    /**
107     * Return true if the {@link FileSystemItem} with the given source id can be moved to the {@link FileSystemItem}
108     * with the given destination id for the given principal.
109     *
110     * @see FileSystemItem#getCanMove(String)
111     */
112    boolean canMove(String srcId, String destId, NuxeoPrincipal principal);
113
114    /*------------- Write operations ----------------*/
115    /**
116     * Creates a folder with the given name in the {@link FileSystemItem} with the given id for the given principal.
117     *
118     * @see FolderItem#createFolder(String)
119     * @deprecated since 9.1, use {@link #createFolder(String, String, NuxeoPrincipal, boolean)} instead
120     */
121    @Deprecated
122    default FolderItem createFolder(String parentId, String name, NuxeoPrincipal principal) {
123        return createFolder(parentId, name, principal, false);
124    }
125
126    /**
127     * Creates a folder with the given name in the {@link FileSystemItem} with the given id for the given principal.
128     *
129     * @param overwrite allows to overwrite an existing folder with the same title
130     * @see FolderItem#createFolder(String, boolean)
131     * @since 9.1
132     */
133    FolderItem createFolder(String parentId, String name, NuxeoPrincipal principal, boolean overwrite);
134
135    /**
136     * Creates a file with the given blob in the {@link FileSystemItem} with the given id for the given principal.
137     *
138     * @see FolderItem#createFile(Blob)
139     * @deprecated since 9.1, use {@link #createFile(String, Blob, NuxeoPrincipal, boolean)} instead
140     */
141    @Deprecated
142    default FileItem createFile(String parentId, Blob blob, NuxeoPrincipal principal) {
143        return createFile(parentId, blob, principal, false);
144    }
145
146    /**
147     * Creates a file with the given blob in the {@link FileSystemItem} with the given id for the given principal.
148     *
149     * @param overwrite allows to overwrite an existing file with the same title
150     * @see FolderItem#createFile(Blob, boolean)
151     * @since 9.1
152     */
153    FileItem createFile(String parentId, Blob blob, NuxeoPrincipal principal, boolean overwrite);
154
155    /**
156     * Updates the {@link FileSystemItem} with the given id with the given blob for the given principal.
157     *
158     * @see FileItem#setBlob(Blob)
159     */
160    FileItem updateFile(String id, Blob blob, NuxeoPrincipal principal);
161
162    /**
163     * Updates the {@link FileSystemItem} with the given id and parent id with the given blob for the given principal.
164     *
165     * @see #updateFile(String, Blob, NuxeoPrincipal)
166     * @since 6.0
167     */
168    FileItem updateFile(String id, String parentId, Blob blob, NuxeoPrincipal principal);
169
170    /**
171     * Deletes the {@link FileSystemItem} with the given id for the given principal.
172     *
173     * @see FileSystemItem#delete()
174     */
175    void delete(String id, NuxeoPrincipal principal);
176
177    /**
178     * Deletes the {@link FileSystemItem} with the given id and parent id for the given principal.
179     *
180     * @see #delete(String, NuxeoPrincipal)
181     * @since 6.0
182     */
183    void delete(String id, String parentId, NuxeoPrincipal principal);
184
185    /**
186     * Renames the {@link FileSystemItem} with the given id with the given name for the given principal.
187     *
188     * @see FileSystemItem#rename(String)
189     */
190    FileSystemItem rename(String id, String name, NuxeoPrincipal principal);
191
192    /**
193     * Moves the {@link FileSystemItem} with the given source id to the {@link FileSystemItem} with the given
194     * destination id for the given principal.
195     *
196     * @see FileSystemItem#move(String)
197     */
198    FileSystemItem move(String srcId, String destId, NuxeoPrincipal principal);
199
200}