michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: package org.mozilla.gecko.sync.repositories;
michael@0: 
michael@0: import java.util.Iterator;
michael@0: 
michael@0: /**
michael@0:  * Our hacky version of transactional semantics. The goal is to prevent
michael@0:  * the following situation:
michael@0:  *
michael@0:  * * AAA is not modified locally.
michael@0:  * * A modified AAA is downloaded during the storing phase. Its local
michael@0:  *   timestamp is advanced.
michael@0:  * * The direction of syncing changes, and AAA is now uploaded to the server.
michael@0:  *
michael@0:  * The following situation should still be supported:
michael@0:  *
michael@0:  * * AAA is not modified locally.
michael@0:  * * A modified AAA is downloaded and merged with the local AAA.
michael@0:  * * The merged AAA is uploaded to the server.
michael@0:  *
michael@0:  * As should:
michael@0:  *
michael@0:  * * AAA is modified locally.
michael@0:  * * A modified AAA is downloaded, and discarded or merged.
michael@0:  * * The current version of AAA is uploaded to the server.
michael@0:  *
michael@0:  * We achieve this by tracking GUIDs during the storing phase. If we
michael@0:  * apply a record such that the local copy is substantially the same
michael@0:  * as the record we just downloaded, we add it to a list of records
michael@0:  * to avoid uploading. The definition of "substantially the same"
michael@0:  * depends on the particular repository. The only consideration is "do we
michael@0:  * want to upload this record in this sync?".
michael@0:  *
michael@0:  * Note that items are removed from this list when a fetch that
michael@0:  * considers them for upload completes successfully. The entire list
michael@0:  * is discarded when the session is completed.
michael@0:  *
michael@0:  * This interface exposes methods to:
michael@0:  *
michael@0:  * * During a store, recording that a record has been stored, and should
michael@0:  *   thus not be returned in subsequent fetches;
michael@0:  * * During a fetch, checking whether a record should be returned.
michael@0:  *
michael@0:  * In the future this might also grow self-persistence.
michael@0:  *
michael@0:  * See also RepositorySession.trackRecord.
michael@0:  *
michael@0:  * @author rnewman
michael@0:  *
michael@0:  */
michael@0: public interface StoreTracker {
michael@0: 
michael@0:   /**
michael@0:    * @param guid
michael@0:    *        The GUID of the item to track.
michael@0:    * @return
michael@0:    *        Whether the GUID was a newly tracked value.
michael@0:    */
michael@0:   public boolean trackRecordForExclusion(String guid);
michael@0: 
michael@0:   /**
michael@0:    * @param guid
michael@0:    *        The GUID of the item to check.
michael@0:    * @return
michael@0:    *        true if the item is already tracked.
michael@0:    */
michael@0:   public boolean isTrackedForExclusion(String guid);
michael@0: 
michael@0:   /**
michael@0:   *
michael@0:   * @param guid
michael@0:   * @return true if the specified GUID was removed from the tracked set.
michael@0:   */
michael@0:   public boolean untrackStoredForExclusion(String guid);
michael@0: 
michael@0:   public RecordFilter getFilter();
michael@0: 
michael@0:   public Iterator<String> recordsTrackedForExclusion();
michael@0: }