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_THREAD_SYNC_ENTITY_H_ 6 #define SYNC_ENGINE_MODEL_THREAD_SYNC_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 thread sync 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 ModelThreadSyncEntity { 33 public: 34 // Construct an instance representing a new locally-created item. 35 static scoped_ptr<ModelThreadSyncEntity> 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<ModelThreadSyncEntity> 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 ~ModelThreadSyncEntity(); 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 private: 110 ModelThreadSyncEntity(int64 sequence_number, 111 int64 commit_requested_sequence_number, 112 int64 acked_sequence_number, 113 int64 base_version, 114 bool is_dirty, 115 const std::string& id, 116 const std::string& client_tag_hash, 117 const std::string& non_unique_name, 118 const sync_pb::EntitySpecifics& specifics, 119 bool deleted, 120 base::Time ctime, 121 base::Time mtime); 122 123 // A sequence number used to track in-progress commits. Each local change 124 // increments this number. 125 int64 sequence_number_; 126 127 // The sequence number of the last item sent to the sync thread. 128 int64 commit_requested_sequence_number_; 129 130 // The sequence number of the last item known to be successfully committed. 131 int64 acked_sequence_number_; 132 133 // The server version on which this item is based. 134 // 135 // If there are no local changes, this is the version of the entity as we see 136 // it here. 137 // 138 // If there are local changes, this is the version of the entity on which 139 // those changes are based. 140 int64 base_version_; 141 142 // True if this entity is out of sync with local storage. 143 bool is_dirty_; 144 145 // The entity's ID. 146 // 147 // Most of the time, this is a server-assigned value. 148 // 149 // Prior to the item's first commit, we leave this value as an empty string. 150 // The initial ID for a newly created item has to meet certain uniqueness 151 // requirements, and we handle those on the sync thread. 152 std::string id_; 153 154 // A hash based on the client tag and model type. 155 // Used for various map lookups. Should always be available. 156 std::string client_tag_hash_; 157 158 // A non-unique name associated with this entity. 159 // 160 // It is sometimes used for debugging. It gets saved to and restored from 161 // the sync server. 162 // 163 // Its value is often related to the item's unhashed client tag, though this 164 // is not guaranteed and should not be relied on. May be hidden when 165 // encryption is enabled. 166 std::string non_unique_name_; 167 168 // A protobuf filled with type-specific information. Contains the most 169 // up-to-date specifics, whether it be from the server or a locally modified 170 // version. 171 sync_pb::EntitySpecifics specifics_; 172 173 // Whether or not the item is deleted. The |specifics_| field may be empty 174 // if this flag is true. 175 bool deleted_; 176 177 // Entity creation and modification timestamps. 178 // Assigned by the client and synced by the server, though the server usually 179 // doesn't bother to inspect their values. 180 base::Time ctime_; 181 base::Time mtime_; 182 }; 183 184 } // namespace syncer 185 186 #endif // SYNC_ENGINE_MODEL_THREAD_SYNC_ENTITY_H_ 187