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/internal_api/public/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       const std::string& encryption_key_name);
  51
  52   // TODO(rlarocque): Implement FromDisk constructor when we implement storage.
  53
  54   ~ModelTypeEntity();
  55
  56   // Returns true if this data is out of sync with local storage.
  57   bool IsWriteRequired() const;
  58
  59   // Returns true if this data is out of sync with the server.
  60   // A commit may or may not be in progress at this time.
  61   bool IsUnsynced() const;
  62
  63   // Returns true if this data is out of sync with the sync thread.
  64   //
  65   // There may or may not be a commit in progress for this item, but there's
  66   // definitely no commit in progress for this (most up to date) version of
  67   // this item.
  68   bool RequiresCommitRequest() const;
  69
  70   // Returns true if the specified update version does not contain new data.
  71   bool UpdateIsReflection(int64 update_version) const;
  72
  73   // Returns true if the specified update version conflicts with local changes.
  74   bool UpdateIsInConflict(int64 update_version) const;
  75
  76   // Applies an update from the sync server.
  77   //
  78   // Overrides any local changes.  Check UpdateIsInConflict() before calling
  79   // this function if you want to handle conflicts differently.
  80   void ApplyUpdateFromServer(int64 update_version,
  81                              bool deleted,
  82                              const sync_pb::EntitySpecifics& specifics,
  83                              base::Time mtime,
  84                              const std::string& encryption_key_name);
  85
  86   // Applies a local change to this item.
  87   void MakeLocalChange(const sync_pb::EntitySpecifics& specifics);
  88
  89   // Schedule a commit if the |name| does not match this item's last known
  90   // encryption key.  The worker that performs the commit is expected to
  91   // encrypt the item using the latest available key.
  92   void UpdateDesiredEncryptionKey(const std::string& name);
  93
  94   // Applies a local deletion to this item.
  95   void Delete();
  96
  97   // Initializes a message representing this item's uncommitted state
  98   // to be forwarded to the sync server for committing.
  99   void InitializeCommitRequestData(CommitRequestData* request) const;
 100
 101   // Notes that the current version of this item has been queued for commit.
 102   void SetCommitRequestInProgress();
 103
 104   // Receives a successful commit response.
 105   //
 106   // Sucssful commit responses can overwrite an item's ID.
 107   //
 108   // Note that the receipt of a successful commit response does not necessarily
 109   // unset IsUnsynced().  If many local changes occur in quick succession, it's
 110   // possible that the committed item was already out of date by the time it
 111   // reached the server.
 112   void ReceiveCommitResponse(const std::string& id,
 113                              int64 sequence_number,
 114                              int64 response_version,
 115                              const std::string& encryption_key_name);
 116
 117   // Clears any in-memory sync state associated with outstanding commits.
 118   void ClearTransientSyncState();
 119
 120   // Clears all sync state.  Invoked when a user signs out.
 121   void ClearSyncState();
 122
 123  private:
 124   ModelTypeEntity(int64 sequence_number,
 125                   int64 commit_requested_sequence_number,
 126                   int64 acked_sequence_number,
 127                   int64 base_version,
 128                   bool is_dirty,
 129                   const std::string& id,
 130                   const std::string& client_tag_hash,
 131                   const std::string& non_unique_name,
 132                   const sync_pb::EntitySpecifics& specifics,
 133                   bool deleted,
 134                   base::Time ctime,
 135                   base::Time mtime,
 136                   const std::string& encryption_key_name);
 137
 138   // A sequence number used to track in-progress commits.  Each local change
 139   // increments this number.
 140   int64 sequence_number_;
 141
 142   // The sequence number of the last item sent to the sync thread.
 143   int64 commit_requested_sequence_number_;
 144
 145   // The sequence number of the last item known to be successfully committed.
 146   int64 acked_sequence_number_;
 147
 148   // The server version on which this item is based.
 149   //
 150   // If there are no local changes, this is the version of the entity as we see
 151   // it here.
 152   //
 153   // If there are local changes, this is the version of the entity on which
 154   // those changes are based.
 155   int64 base_version_;
 156
 157   // True if this entity is out of sync with local storage.
 158   bool is_dirty_;
 159
 160   // The entity's ID.
 161   //
 162   // Most of the time, this is a server-assigned value.
 163   //
 164   // Prior to the item's first commit, we leave this value as an empty string.
 165   // The initial ID for a newly created item has to meet certain uniqueness
 166   // requirements, and we handle those on the sync thread.
 167   std::string id_;
 168
 169   // A hash based on the client tag and model type.
 170   // Used for various map lookups.  Should always be available.
 171   std::string client_tag_hash_;
 172
 173   // A non-unique name associated with this entity.
 174   //
 175   // It is sometimes used for debugging.  It gets saved to and restored from
 176   // the sync server.
 177   //
 178   // Its value is often related to the item's unhashed client tag, though this
 179   // is not guaranteed and should not be relied on.  May be hidden when
 180   // encryption is enabled.
 181   std::string non_unique_name_;
 182
 183   // A protobuf filled with type-specific information.  Contains the most
 184   // up-to-date specifics, whether it be from the server or a locally modified
 185   // version.
 186   sync_pb::EntitySpecifics specifics_;
 187
 188   // Whether or not the item is deleted.  The |specifics_| field may be empty
 189   // if this flag is true.
 190   bool deleted_;
 191
 192   // Entity creation and modification timestamps.
 193   // Assigned by the client and synced by the server, though the server usually
 194   // doesn't bother to inspect their values.
 195   base::Time ctime_;
 196   base::Time mtime_;
 197
 198   // The name of the encryption key used to encrypt this item on the server.
 199   // Empty when no encryption is in use.
 200   std::string encryption_key_name_;
 201 };
 202
 203 }  // namespace syncer
 204
 205 #endif  // SYNC_ENGINE_MODEL_TYPE_ENTITY_H_