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 *     Olivier Grisel <ogrisel@nuxeo.com>
018 *     Antoine Taillefer <ataillefer@nuxeo.com>
019 */
020package org.nuxeo.drive.service;
021
022import java.util.Map;
023import java.util.Set;
024
025import org.nuxeo.ecm.core.api.CoreSession;
026import org.nuxeo.ecm.core.api.DocumentModel;
027import org.nuxeo.ecm.core.api.IdRef;
028import org.nuxeo.ecm.core.api.NuxeoPrincipal;
029
030/**
031 * Manage list of NuxeoDrive synchronization roots and devices for a given nuxeo user.
032 */
033public interface NuxeoDriveManager {
034
035    /**
036     * @param principal the Nuxeo Drive user
037     * @param newRootContainer the folderish document to be used as synchronization root: must be bound to an active
038     *            session
039     * @throws SecurityException if the user does not have write permissions to the container.
040     */
041    void registerSynchronizationRoot(NuxeoPrincipal principal, DocumentModel newRootContainer,
042            CoreSession session);
043
044    /**
045     * @param principal the Nuxeo Drive user
046     * @param rootContainer the folderish document that should no longer be used as a synchronization root
047     */
048    void unregisterSynchronizationRoot(NuxeoPrincipal principal, DocumentModel rootContainer,
049            CoreSession session);
050
051    /**
052     * Fetch the list of synchronization root refs for a given user and a given session repository. This list is assumed
053     * to be short enough (in the order of 100 folder max) so that no paging API is required. The user is taken from the
054     * session.getPrincipal() method.
055     *
056     * @param session active CoreSession instance to the repository hosting the roots.
057     * @return the ordered set of non deleted synchronization root references for that user
058     */
059    Set<IdRef> getSynchronizationRootReferences(CoreSession session);
060
061    /**
062     * Fetch all the synchronization root references and paths for a given user. This list is assumed to be short enough
063     * (in the order of 100 folder max) so that no paging API is required.
064     *
065     * @param principal the user to fetch the roots for
066     * @return the map keyed by repository names all active roots definitions for the current user.
067     */
068    Map<String, SynchronizationRoots> getSynchronizationRoots(NuxeoPrincipal principal);
069
070    /**
071     * Fetch all the collection sync root member ids for a given user.
072     *
073     * @param principal the user to fetch the ids for
074     * @return the map keyed by repository names all collection sync root member ids for the current user.
075     */
076    Map<String, Set<String>> getCollectionSyncRootMemberIds(NuxeoPrincipal principal);
077
078    /**
079     * Checks if the given {@link DocumentModel} is a synchronization root for the given user.
080     */
081    boolean isSynchronizationRoot(NuxeoPrincipal principal, DocumentModel doc);
082
083    /**
084     * Method to be called by a CoreEvent listener monitoring documents deletions to cleanup references to recently
085     * deleted documents and invalidate the caches.
086     */
087    void handleFolderDeletion(IdRef ref);
088
089    /**
090     * Gets a summary of document changes in all repositories for the given user's synchronization roots, from the lower
091     * bound sent by the user's device.
092     * <p>
093     * The summary includes:
094     * <ul>
095     * <li>The list of sync root paths</li>
096     * <li>A list of document changes</li>
097     * <li>The document models that have changed</li>
098     * <li>A status code</li>
099     * </ul>
100     *
101     * @param lastSyncRootRefs the map keyed by repository names of document refs for the synchronization roots that
102     *            were active during last synchronization
103     * @param lowerBound the lower bound sent by the user's device. Typically set to the value returned by
104     *            {@link FileSystemChangeSummary#getUpperBound()} of the previous call to
105     *            {@link NuxeoDriveManager#getChangeSummary(NuxeoPrincipal, Map, long)} or 0 for catching every event
106     *            since the repository initialization.
107     * @return the summary of document changes
108     */
109    FileSystemChangeSummary getChangeSummary(NuxeoPrincipal principal, Map<String, Set<IdRef>> lastSyncRootRefs,
110            long lowerBound);
111
112    /**
113     * Gets the {@link FileSystemChangeFinder} member.
114     */
115    FileSystemChangeFinder getChangeFinder();
116
117    /**
118     * Invalidate the synchronization roots cache for a given user so as to query the repository next time
119     * {@link #getSynchronizationRoots(NuxeoPrincipal)} is called.
120     *
121     * @param userName the principal name of the user to invalidate the cache for.
122     */
123    void invalidateSynchronizationRootsCache(String userName);
124
125    /**
126     * Invalidate the collection sync root member cache for a given user so as to query the repository next time
127     * {@link #getCollectionSyncRootMemberIds(NuxeoPrincipal)} is called.
128     *
129     * @param userName the principal name of the user to invalidate the cache for.
130     */
131    void invalidateCollectionSyncRootMemberCache(String userName);
132
133    /**
134     * Invalidate the collection sync root member cache for all users so as to query the repository next time
135     * {@link #getCollectionSyncRootMemberIds(NuxeoPrincipal)} is called.
136     */
137    void invalidateCollectionSyncRootMemberCache();
138
139    /**
140     * Adds the given {@link DocumentModel} to the {@code LOCALLY_EDITED_COLLECTION_NAME} collection.
141     *
142     * @since 6.0
143     */
144    void addToLocallyEditedCollection(CoreSession session, DocumentModel doc);
145
146}