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}