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.adapter;
020
021import java.util.List;
022import java.util.concurrent.Semaphore;
023
024import org.nuxeo.drive.adapter.impl.DocumentBackedFolderItem;
025import org.nuxeo.drive.service.FileSystemItemAdapterService;
026import org.nuxeo.ecm.core.api.Blob;
027import org.nuxeo.ecm.core.api.DocumentModel;
028
029import com.fasterxml.jackson.annotation.JsonIgnore;
030
031/**
032 * Representation of a folder.
033 * <p>
034 * In the case of a {@link DocumentModel} backed implementation, the backing document is Folderish. Typically a Folder
035 * or a Workspace.
036 *
037 * @author Antoine Taillefer
038 * @see DocumentBackedFolderItem
039 */
040public interface FolderItem extends FileSystemItem {
041
042    @JsonIgnore
043    List<FileSystemItem> getChildren();
044
045    /**
046     * Returns {@code true} if the {@link #scrollDescendants(String, int, long)} API can be used.
047     *
048     * @since 8.3
049     */
050    boolean getCanScrollDescendants();
051
052    /**
053     * Retrieves at most {@code batchSize} {@link FileSystemItem} descendants for the given {@code scrollId}.
054     * <p>
055     * When passing a null {@code scrollId} the initial search request is executed and the first batch of results is
056     * returned along with a {@code scrollId} which should be passed to the next call in order to retrieve the next
057     * batch of results.
058     * <p>
059     * Ideally, the search context made available by the initial search request is kept alive during {@code keepAlive}
060     * milliseconds if {@code keepAlive} is positive.
061     * <p>
062     * Results are not necessarily sorted.
063     * <p>
064     * This method is protected by a {@link Semaphore}, made available by
065     * {@link FileSystemItemAdapterService#getScrollBatchSemaphore()}, to limit the number of concurrent executions and
066     * avoid too much memory pressure.
067     *
068     * @throws UnsupportedOperationException if {@link #getCanScrollDescendants()} returns {@code false}.
069     * @since 8.3
070     */
071    @JsonIgnore
072    ScrollFileSystemItemList scrollDescendants(String scrollId, int batchSize, long keepAlive);
073
074    boolean getCanCreateChild();
075
076    /**
077     * @deprecated since 9.1, use {@link #createFile(String, boolean)} instead
078     */
079    @Deprecated
080    default FileItem createFile(Blob blob) {
081        return createFile(blob, false);
082    }
083
084    /**
085     * @param overwrite allows to overwrite an existing file with the same title
086     * @since 9.1
087     */
088    FileItem createFile(Blob blob, boolean overwrite);
089
090    /**
091     * @deprecated since 9.1, use {@link #createFolder(String, boolean)} instead
092     */
093    @Deprecated
094    default FolderItem createFolder(String name) {
095        return createFolder(name, false);
096    }
097
098    /**
099     * @param overwrite allows to overwrite an existing folder with the same title
100     * @since 9.1
101     */
102    FolderItem createFolder(String name, boolean overwrite);
103
104}