sync/engine/entity_tracker.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef SYNC_ENGINE_ENTITY_TRACKER_H_
   6 #define SYNC_ENGINE_ENTITY_TRACKER_H_
   7
   8 #include <string>
   9
  10 #include "base/basictypes.h"
  11 #include "base/memory/scoped_ptr.h"
  12 #include "base/time/time.h"
  13 #include "sync/base/sync_export.h"
  14 #include "sync/protocol/sync.pb.h"
  15
  16 namespace syncer_v2 {
  17 struct UpdateResponseData;
  18
  19 // Manages the pending commit and update state for an entity on the sync
  20 // thread.
  21 //
  22 // It should be considered a helper class internal to the
  23 // ModelTypeSyncWorker.
  24 //
  25 // Maintains the state associated with a particular sync entity which is
  26 // necessary for decision-making on the sync thread.  It can track pending
  27 // commit state, received update state, and can detect conflicts.
  28 //
  29 // This object may or may not contain state associated with a pending commit.
  30 // If no commit is pending, the |is_commit_pending_| flag will be set to false
  31 // and many of this object's fields will be cleared.
  32 class SYNC_EXPORT EntityTracker {
  33  public:
  34   ~EntityTracker();
  35
  36   // Initialize a new entity based on an update response.
  37   static scoped_ptr<EntityTracker> FromServerUpdate(
  38       const std::string& id_string,
  39       const std::string& client_tag_hash,
  40       int64 version);
  41
  42   // Initialize a new entity based on a commit request.
  43   static scoped_ptr<EntityTracker> FromCommitRequest(
  44       const std::string& id_string,
  45       const std::string& client_tag_hash,
  46       int64 sequence_number,
  47       int64 base_version,
  48       base::Time ctime,
  49       base::Time mtime,
  50       const std::string& non_unique_name,
  51       bool deleted,
  52       const sync_pb::EntitySpecifics& specifics);
  53
  54   // Returns true if this entity should be commited to the server.
  55   bool IsCommitPending() const;
  56
  57   // Populates a sync_pb::SyncEntity for a commit.  Also sets the
  58   // |sequence_number|, so we can track it throughout the commit process.
  59   void PrepareCommitProto(sync_pb::SyncEntity* commit_entity,
  60                           int64* sequence_number) const;
  61
  62   // Updates this entity with data from the latest version that the
  63   // model asked us to commit.  May clobber state related to the
  64   // model's previous commit attempt(s).
  65   void RequestCommit(const std::string& id,
  66                      const std::string& client_tag_hash,
  67                      int64 sequence_number,
  68                      int64 base_version,
  69                      base::Time ctime,
  70                      base::Time mtime,
  71                      const std::string& non_unique_name,
  72                      bool deleted,
  73                      const sync_pb::EntitySpecifics& specifics);
  74
  75   // Handles the receipt of a commit response.
  76   //
  77   // Since commits happen entirely on the sync thread, we can safely assume
  78   // that our item's state at the end of the commit is the same as it was at
  79   // the start.
  80   void ReceiveCommitResponse(const std::string& response_id,
  81                              int64 response_version,
  82                              int64 sequence_number);
  83
  84   // Handles receipt of an update from the server.
  85   void ReceiveUpdate(int64 version);
  86
  87   // Handles the receipt of an pending update from the server.
  88   //
  89   // Returns true if the tracker decides this item is worth keeping.  Returns
  90   // false if the item is discarded, which could happen if the version number
  91   // is out of date.
  92   bool ReceivePendingUpdate(const UpdateResponseData& data);
  93
  94   // Functions to fetch the latest pending update.
  95   bool HasPendingUpdate() const;
  96   UpdateResponseData GetPendingUpdate() const;
  97
  98   // Clears the pending update.  Allows us to resume regular commit behavior.
  99   void ClearPendingUpdate();
 100
 101  private:
 102   // Initializes received update state.  Does not initialize state related to
 103   // pending commits and sets |is_commit_pending_| to false.
 104   EntityTracker(const std::string& id,
 105                 const std::string& client_tag_hash,
 106                 int64 highest_commit_response_version,
 107                 int64 highest_gu_response_version);
 108
 109   // Initializes all fields.  Sets |is_commit_pending_| to true.
 110   EntityTracker(const std::string& id,
 111                 const std::string& client_tag_hash,
 112                 int64 highest_commit_response_version,
 113                 int64 highest_gu_response_version,
 114                 bool is_commit_pending,
 115                 int64 sequence_number,
 116                 int64 base_version,
 117                 base::Time ctime,
 118                 base::Time mtime,
 119                 const std::string& non_unique_name,
 120                 bool deleted,
 121                 const sync_pb::EntitySpecifics& specifics);
 122
 123   // Checks if the current state indicates a conflict.
 124   //
 125   // This can be true only while a call to this object is in progress.
 126   // Conflicts are always cleared before the method call ends.
 127   bool IsInConflict() const;
 128
 129   // Checks if the server knows about this item.
 130   bool IsServerKnown() const;
 131
 132   // Clears flag and optionally clears state associated with a pending commit.
 133   void ClearPendingCommit();
 134
 135   // The ID for this entry.  May be empty if the entry has never been committed.
 136   std::string id_;
 137
 138   // The hashed client tag for this entry.
 139   std::string client_tag_hash_;
 140
 141   // The highest version seen in a commit response for this entry.
 142   int64 highest_commit_response_version_;
 143
 144   // The highest version seen in a GU response for this entry.
 145   int64 highest_gu_response_version_;
 146
 147   // Flag that indicates whether or not we're waiting for a chance to commit
 148   // this item.
 149   bool is_commit_pending_;
 150
 151   // Used to track in-flight commit requests on the model thread.  All we need
 152   // to do here is return it back to the model thread when the pending commit
 153   // is completed and confirmed.  Not valid if no commit is pending.
 154   int64 sequence_number_;
 155
 156   // The following fields are valid only when a commit is pending.
 157   // This is where we store the data that is to be sent up to the server
 158   // at the next possible opportunity.
 159   int64 base_version_;
 160   base::Time ctime_;
 161   base::Time mtime_;
 162   std::string non_unique_name_;
 163   bool deleted_;
 164   sync_pb::EntitySpecifics specifics_;
 165
 166   // An update for this item which can't be applied right now.  The presence of
 167   // an pending update prevents commits.  As of this writing, the only source
 168   // of pending updates is updates we can't decrypt right now.
 169   scoped_ptr<UpdateResponseData> pending_update_;
 170
 171   DISALLOW_COPY_AND_ASSIGN(EntityTracker);
 172 };
 173
 174 }  // namespace syncer
 175
 176 #endif  // SYNC_ENGINE_ENTITY_TRACKER_H_