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 *     Antoine Taillefer <ataillefer@nuxeo.com>
016 */
017package org.nuxeo.drive.service;
018
019import java.io.Serializable;
020import java.util.List;
021import java.util.Map;
022import java.util.Set;
023
024import org.nuxeo.ecm.core.api.CoreSession;
025import org.nuxeo.ecm.core.api.IdRef;
026
027/**
028 * Allows to find document changes.
029 *
030 * @author Antoine Taillefer
031 */
032public interface FileSystemChangeFinder extends Serializable {
033
034    /**
035     * Handles the parameters contributed through the {@code changeFinder} contribution.
036     */
037    void handleParameters(Map<String, String> parameters);
038
039    /**
040     * Gets the changes in the repository against which the given session is bound for the given synchronization root
041     * paths, since the given last successful synchronization date and without exceeding the given limit. The change
042     * summaries are mapped back to the file system view: the file system items might not always have the same tree
043     * layout as the backing documents in the repositories but this is a back-end detail that the client does not have
044     * to deal with.
045     *
046     * @param session the session bound to a specific repository
047     * @param lastActiveRootRefs docrefs of the roots as reported by the last successful synchronization (can be empty
048     *            or null)
049     * @param activeRoots the currently active synchronization roots
050     * @param lastSuccessfulSyncDate the last successful synchronization date as measured on the server for this user
051     *            device.
052     * @param syncDate the current synchronization date (upper bound on the date of the changes to return). This date is
053     *            typically obtained by calling {@link #getCurrentDate()}
054     * @param limit the maximum number of changes to fetch
055     * @return the list of document changes
056     * @throws TooManyChangesException if the number of changes found has exceeded the limit
057     */
058    List<FileSystemItemChange> getFileSystemChanges(CoreSession session, Set<IdRef> lastActiveRootRefs,
059            SynchronizationRoots activeRoots, long lastSuccessfulSyncDate, long syncDate, int limit)
060            throws TooManyChangesException;
061
062    /**
063     * Gets the changes in the repository against which the given session is bound for the given synchronization root
064     * paths, between the given lower and upper integer bounds and without exceeding the given limit. The change
065     * summaries are mapped back to the file system view: the file system items might not always have the same tree
066     * layout as the backing documents in the repositories but this is a back-end detail that the client does not have
067     * to deal with.
068     *
069     * @param session the session bound to a specific repository
070     * @param lastActiveRootRefs docrefs of the roots as reported by the last successful synchronization (can be empty
071     *            or null)
072     * @param activeRoots the currently active synchronization roots
073     * @param collectionSyncRootMemberIds the collection sync root member ids
074     * @param lowerBound the lower integer bound of the range clause in the change query
075     * @param upperBound the upper integer bound of the range clause in the change query. This id is typically obtained
076     *            by calling {@link #getUpperBound())}
077     * @param limit the maximum number of changes to fetch
078     * @return the list of document changes
079     * @throws TooManyChangesException if the number of changes found has exceeded the limit
080     */
081    List<FileSystemItemChange> getFileSystemChangesIntegerBounds(CoreSession session, Set<IdRef> lastActiveRootRefs,
082            SynchronizationRoots activeRoots, Set<String> collectionSyncRootMemberIds, long lowerBound,
083            long upperBound, int limit) throws TooManyChangesException;
084
085    /**
086     * Read the current time code to query for changes. The time is truncated to 0 milliseconds to have a consistent
087     * behavior across databases. Call to this method should be monotonic (or very nearly monotonic).
088     */
089    long getCurrentDate();
090
091    /**
092     * Return the upper bound of the range clause in the change query.
093     */
094    long getUpperBound();
095
096}