001/*
002 * (C) Copyright 2012 Nuxeo SA (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Olivier Grisel <ogrisel@nuxeo.com>
016 *     Antoine Taillefer <ataillefer@nuxeo.com>
017 */
018package org.nuxeo.drive.service;
019
020import java.security.Principal;
021import java.util.Map;
022import java.util.Set;
023
024import org.nuxeo.ecm.core.api.CoreSession;
025import org.nuxeo.ecm.core.api.DocumentModel;
026import org.nuxeo.ecm.core.api.IdRef;
027
028/**
029 * Manage list of NuxeoDrive synchronization roots and devices for a given nuxeo user.
030 */
031public interface NuxeoDriveManager {
032
033    public static final String LOCALLY_EDITED_COLLECTION_NAME = "Locally Edited";
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(Principal principal, DocumentModel newRootContainer, CoreSession session);
042
043    /**
044     * @param principal the Nuxeo Drive user
045     * @param rootContainer the folderish document that should no longer be used as a synchronization root
046     */
047    public void unregisterSynchronizationRoot(Principal principal, DocumentModel rootContainer, CoreSession session);
048
049    /**
050     * Fetch the list of synchronization root refs for a given user and a given session repository. This list is assumed
051     * to be short enough (in the order of 100 folder max) so that no paging API is required. The user is taken from the
052     * session.getPrincipal() method.
053     *
054     * @param session active CoreSession instance to the repository hosting the roots.
055     * @return the ordered set of non deleted synchronization root references for that user
056     * @see #getSynchronizationRootPaths(String, CoreSession)
057     */
058    public Set<IdRef> getSynchronizationRootReferences(CoreSession session);
059
060    /**
061     * Fetch all the synchronization root references and paths for a given user. This list is assumed to be short enough
062     * (in the order of 100 folder max) so that no paging API is required.
063     *
064     * @param principal the user to fetch the roots for
065     * @return the map keyed by repository names all active roots definitions for the current user.
066     */
067    public Map<String, SynchronizationRoots> getSynchronizationRoots(Principal principal);
068
069    /**
070     * Fetch all the collection sync root member ids for a given user.
071     *
072     * @param principal the user to fetch the ids for
073     * @return the map keyed by repository names all collection sync root member ids for the current user.
074     */
075    public Map<String, Set<String>> getCollectionSyncRootMemberIds(Principal principal);
076
077    /**
078     * Checks if the given {@link DocumentModel} is a synchronization root for the given user.
079     */
080    public boolean isSynchronizationRoot(Principal principal, DocumentModel doc);
081
082    /**
083     * Method to be called by a CoreEvent listener monitoring documents deletions to cleanup references to recently
084     * deleted documents and invalidate the caches.
085     */
086    public void handleFolderDeletion(IdRef ref);
087
088    /**
089     * Gets a summary of document changes in all repositories for the given user's synchronization roots, since the
090     * user's device last successful synchronization date.
091     * <p>
092     * The summary includes:
093     * <ul>
094     * <li>The list of sync root paths</li>
095     * <li>A list of document changes</li>
096     * <li>The document models that have changed</li>
097     * <li>A status code</li>
098     * </ul>
099     *
100     * @param principal
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 lastSuccessfulSync the last successful synchronization date of the user's device. This time is expected to
104     *            be in milliseconds since 1970-01-01 UTC as measured on the Nuxeo server clock, typically set to the
105     *            value returned by {@link FileSystemChangeSummary#getSyncDate()} of the previous call to
106     *            {@link NuxeoDriveManager#getChangeSummary(Principal, Map, long)} or 0 for catching every event since
107     *            the repository initialization.
108     * @return the summary of document changes
109     */
110    public FileSystemChangeSummary getChangeSummary(Principal principal, Map<String, Set<IdRef>> lastSyncRootRefs,
111            long lastSuccessfulSync);
112
113    /**
114     * Gets a summary of document changes in all repositories for the given user's synchronization roots, from the lower
115     * bound sent by the user's device.
116     * <p>
117     * The summary includes:
118     * <ul>
119     * <li>The list of sync root paths</li>
120     * <li>A list of document changes</li>
121     * <li>The document models that have changed</li>
122     * <li>A status code</li>
123     * </ul>
124     *
125     * @param principal
126     * @param lastSyncRootRefs the map keyed by repository names of document refs for the synchronization roots that
127     *            were active during last synchronization
128     * @param lowerBound the lower bound sent by the user's device. Typically set to the value returned by
129     *            {@link FileSystemChangeSummary#getUpperBound()} of the previous call to
130     *            {@link NuxeoDriveManager#getChangeSummaryIntegerBounds(Principal, Map, long)} or 0 for catching every
131     *            event since the repository initialization.
132     * @return the summary of document changes
133     */
134    public FileSystemChangeSummary getChangeSummaryIntegerBounds(Principal principal,
135            Map<String, Set<IdRef>> lastSyncRootRefs, long lowerBound);
136
137    /**
138     * Gets the {@link FileSystemChangeFinder} member.
139     */
140    public FileSystemChangeFinder getChangeFinder();
141
142    /**
143     * Sets the {@link FileSystemChangeFinder} member.
144     *
145     * @deprecated since 7.3, use {@code changeFinder} extension point instead
146     */
147    @Deprecated
148    public void setChangeFinder(FileSystemChangeFinder changeFinder);
149
150    /**
151     * Invalidate the synchronization roots cache for a given user so as to query the repository next time
152     * {@link #getSynchronizationRoots(Principal)} is called.
153     *
154     * @param userName the principal name of the user to invalidate the cache for.
155     */
156    void invalidateSynchronizationRootsCache(String userName);
157
158    /**
159     * Invalidate the collection sync root member cache for a given user so as to query the repository next time
160     * {@link #getCollectionSyncRootMemberIds(Principal)} is called.
161     *
162     * @param userName the principal name of the user to invalidate the cache for.
163     */
164    void invalidateCollectionSyncRootMemberCache(String userName);
165
166    /**
167     * Invalidate the collection sync root member cache for all users so as to query the repository next time
168     * {@link #getCollectionSyncRootMemberIds(Principal)} is called.
169     */
170    void invalidateCollectionSyncRootMemberCache();
171
172    /**
173     * Adds the given {@link DocumentModel} to the {@link #LOCALLY_EDITED_COLLECTION_NAME} collection.
174     *
175     * @since 6.0
176     */
177    void addToLocallyEditedCollection(CoreSession session, DocumentModel doc);
178
179}