sync/engine/model_type_entity.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_MODEL_TYPE_ENTITY_H_
   6 #define SYNC_ENGINE_MODEL_TYPE_ENTITY_H_
   7
   8 #include <string>
   9
  10 #include "base/memory/scoped_ptr.h"
  11 #include "base/time/time.h"
  12 #include "sync/base/sync_export.h"
  13 #include "sync/engine/non_blocking_sync_common.h"
  14 #include "sync/protocol/sync.pb.h"
  15
  16 namespace syncer {
  17
  18 // This is the model thread's representation of a SyncEntity.
  19 //
  20 // The model type entity receives updates from the model itself and
  21 // (asynchronously) from the sync server via the sync thread.  From the point
  22 // of view of this class, updates from the server take precedence over local
  23 // changes, though the model may be given an opportunity to overwrite this
  24 // decision later.
  25 //
  26 // Sync will try to commit this entity's data to the sync server and local
  27 // storage.
  28 //
  29 // Most of the logic related to those processes live outside this class.  This
  30 // class helps out a bit by offering some functions to serialize its data to
  31 // various formats and query the entity's status.
  32 class SYNC_EXPORT_PRIVATE ModelTypeEntity {
  33  public:
  34   // Construct an instance representing a new locally-created item.
  35   static scoped_ptr<ModelTypeEntity> NewLocalItem(
  36       const std::string& client_tag,
  37       const sync_pb::EntitySpecifics& specifics,
  38       base::Time now);
  39
  40   // Construct an instance representing an item newly received from the server.
  41   static scoped_ptr<ModelTypeEntity> FromServerUpdate(
  42       const std::string& id,
  43       const std::string& client_tag_hash,
  44       const std::string& non_unique_name,
  45       int64 version,
  46       const sync_pb::EntitySpecifics& specifics,
  47       bool deleted,
  48       base::Time ctime,
  49       base::Time mtime);
  50
  51   // TODO(rlarocque): Implement FromDisk constructor when we implement storage.
  52
  53   ~ModelTypeEntity();
  54
  55   // Returns true if this data is out of sync with local storage.
  56   bool IsWriteRequired() const;
  57
  58   // Returns true if this data is out of sync with the server.
  59   // A commit may or may not be in progress at this time.
  60   bool IsUnsynced() const;
  61
  62   // Returns true if this data is out of sync with the sync thread.
  63   //
  64   // There may or may not be a commit in progress for this item, but there's
  65   // definitely no commit in progress for this (most up to date) version of
  66   // this item.
  67   bool RequiresCommitRequest() const;
  68
  69   // Returns true if the specified update version does not contain new data.
  70   bool UpdateIsReflection(int64 update_version) const;
  71
  72   // Returns true if the specified update version conflicts with local changes.
  73   bool UpdateIsInConflict(int64 update_version) const;
  74
  75   // Applies an update from the sync server.
  76   //
  77   // Overrides any local changes.  Check UpdateIsInConflict() before calling
  78   // this function if you want to handle conflicts differently.
  79   void ApplyUpdateFromServer(int64 update_version,
  80                              bool deleted,
  81                              const sync_pb::EntitySpecifics& specifics,
  82                              base::Time mtime);
  83
  84   // Applies a local change to this item.
  85   void MakeLocalChange(const sync_pb::EntitySpecifics& specifics);
  86
  87   // Applies a local deletion to this item.
  88   void Delete();
  89
  90   // Initializes a message representing this item's uncommitted state
  91   // to be forwarded to the sync server for committing.
  92   void InitializeCommitRequestData(CommitRequestData* request) const;
  93
  94   // Notes that the current version of this item has been queued for commit.
  95   void SetCommitRequestInProgress();
  96
  97   // Receives a successful commit response.
  98   //
  99   // Sucssful commit responses can overwrite an item's ID.
 100   //
 101   // Note that the receipt of a successful commit response does not necessarily
 102   // unset IsUnsynced().  If many local changes occur in quick succession, it's
 103   // possible that the committed item was already out of date by the time it
 104   // reached the server.
 105   void ReceiveCommitResponse(const std::string& id,
 106                              int64 sequence_number,
 107                              int64 response_version);
 108
 109   // Clears any in-memory sync state associated with outstanding commits.
 110   void ClearTransientSyncState();
 111
 112   // Clears all sync state.  Invoked when a user signs out.
 113   void ClearSyncState();
 114
 115  private:
 116   ModelTypeEntity(int64 sequence_number,
 117                   int64 commit_requested_sequence_number,
 118                   int64 acked_sequence_number,
 119                   int64 base_version,
 120                   bool is_dirty,
 121                   const std::string& id,
 122                   const std::string& client_tag_hash,
 123                   const std::string& non_unique_name,
 124                   const sync_pb::EntitySpecifics& specifics,
 125                   bool deleted,
 126                   base::Time ctime,
 127                   base::Time mtime);
 128
 129   // A sequence number used to track in-progress commits.  Each local change
 130   // increments this number.
 131   int64 sequence_number_;
 132
 133   // The sequence number of the last item sent to the sync thread.
 134   int64 commit_requested_sequence_number_;
 135
 136   // The sequence number of the last item known to be successfully committed.
 137   int64 acked_sequence_number_;
 138
 139   // The server version on which this item is based.
 140   //
 141   // If there are no local changes, this is the version of the entity as we see
 142   // it here.
 143   //
 144   // If there are local changes, this is the version of the entity on which
 145   // those changes are based.
 146   int64 base_version_;
 147
 148   // True if this entity is out of sync with local storage.
 149   bool is_dirty_;
 150
 151   // The entity's ID.
 152   //
 153   // Most of the time, this is a server-assigned value.
 154   //
 155   // Prior to the item's first commit, we leave this value as an empty string.
 156   // The initial ID for a newly created item has to meet certain uniqueness
 157   // requirements, and we handle those on the sync thread.
 158   std::string id_;
 159
 160   // A hash based on the client tag and model type.
 161   // Used for various map lookups.  Should always be available.
 162   std::string client_tag_hash_;
 163
 164   // A non-unique name associated with this entity.
 165   //
 166   // It is sometimes used for debugging.  It gets saved to and restored from
 167   // the sync server.
 168   //
 169   // Its value is often related to the item's unhashed client tag, though this
 170   // is not guaranteed and should not be relied on.  May be hidden when
 171   // encryption is enabled.
 172   std::string non_unique_name_;
 173
 174   // A protobuf filled with type-specific information.  Contains the most
 175   // up-to-date specifics, whether it be from the server or a locally modified
 176   // version.
 177   sync_pb::EntitySpecifics specifics_;
 178
 179   // Whether or not the item is deleted.  The |specifics_| field may be empty
 180   // if this flag is true.
 181   bool deleted_;
 182
 183   // Entity creation and modification timestamps.
 184   // Assigned by the client and synced by the server, though the server usually
 185   // doesn't bother to inspect their values.
 186   base::Time ctime_;
 187   base::Time mtime_;
 188 };
 189
 190 }  // namespace syncer
 191
 192 #endif  // SYNC_ENGINE_MODEL_TYPE_ENTITY_H_