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    public 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    public 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     * @see #getSynchronizationRootPaths(String, CoreSession)
059     */
060    public Set<IdRef> getSynchronizationRootReferences(CoreSession session);
061
062    /**
063     * Fetch all the synchronization root references and paths for a given user. This list is assumed to be short enough
064     * (in the order of 100 folder max) so that no paging API is required.
065     *
066     * @param principal the user to fetch the roots for
067     * @return the map keyed by repository names all active roots definitions for the current user.
068     */
069    public Map<String, SynchronizationRoots> getSynchronizationRoots(NuxeoPrincipal principal);
070
071    /**
072     * Fetch all the collection sync root member ids for a given user.
073     *
074     * @param principal the user to fetch the ids for
075     * @return the map keyed by repository names all collection sync root member ids for the current user.
076     */
077    public Map<String, Set<String>> getCollectionSyncRootMemberIds(NuxeoPrincipal principal);
078
079    /**
080     * Checks if the given {@link DocumentModel} is a synchronization root for the given user.
081     */
082    public boolean isSynchronizationRoot(NuxeoPrincipal principal, DocumentModel doc);
083
084    /**
085     * Method to be called by a CoreEvent listener monitoring documents deletions to cleanup references to recently
086     * deleted documents and invalidate the caches.
087     */
088    public void handleFolderDeletion(IdRef ref);
089
090    /**
091     * Gets a summary of document changes in all repositories for the given user's synchronization roots, from the lower
092     * bound sent by the user's device.
093     * <p>
094     * The summary includes:
095     * <ul>
096     * <li>The list of sync root paths</li>
097     * <li>A list of document changes</li>
098     * <li>The document models that have changed</li>
099     * <li>A status code</li>
100     * </ul>
101     *
102     * @param principal
103     * @param lastSyncRootRefs the map keyed by repository names of document refs for the synchronization roots that
104     *            were active during last synchronization
105     * @param lowerBound the lower bound sent by the user's device. Typically set to the value returned by
106     *            {@link FileSystemChangeSummary#getUpperBound()} of the previous call to
107     *            {@link NuxeoDriveManager#getChangeSummary(NuxeoPrincipal, Map, long)} or 0 for catching every event
108     *            since the repository initialization.
109     * @return the summary of document changes
110     */
111    public FileSystemChangeSummary getChangeSummary(NuxeoPrincipal principal, Map<String, Set<IdRef>> lastSyncRootRefs,
112            long lowerBound);
113
114    /**
115     * Gets the {@link FileSystemChangeFinder} member.
116     */
117    public FileSystemChangeFinder getChangeFinder();
118
119    /**
120     * Invalidate the synchronization roots cache for a given user so as to query the repository next time
121     * {@link #getSynchronizationRoots(NuxeoPrincipal)} is called.
122     *
123     * @param userName the principal name of the user to invalidate the cache for.
124     */
125    void invalidateSynchronizationRootsCache(String userName);
126
127    /**
128     * Invalidate the collection sync root member cache for a given user so as to query the repository next time
129     * {@link #getCollectionSyncRootMemberIds(NuxeoPrincipal)} is called.
130     *
131     * @param userName the principal name of the user to invalidate the cache for.
132     */
133    void invalidateCollectionSyncRootMemberCache(String userName);
134
135    /**
136     * Invalidate the collection sync root member cache for all users so as to query the repository next time
137     * {@link #getCollectionSyncRootMemberIds(NuxeoPrincipal)} is called.
138     */
139    void invalidateCollectionSyncRootMemberCache();
140
141    /**
142     * Adds the given {@link DocumentModel} to the {@link #LOCALLY_EDITED_COLLECTION_NAME} collection.
143     *
144     * @since 6.0
145     */
146    void addToLocallyEditedCollection(CoreSession session, DocumentModel doc);
147
148}