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_ 206
