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