sync_data.h revision e5d81f57cb97b3b6b7fccc9c5610d21eb81db09d 
1// Copyright 2012 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_API_SYNC_DATA_H_
6#define SYNC_API_SYNC_DATA_H_
7
8#include <iosfwd>
9#include <string>
10#include <vector>
11
12#include "base/basictypes.h"
13#include "base/callback.h"
14#include "base/stl_util.h"
15#include "base/time/time.h"
16#include "sync/api/attachments/attachment.h"
17#include "sync/api/attachments/attachment_service_proxy.h"
18#include "sync/base/sync_export.h"
19#include "sync/internal_api/public/base/model_type.h"
20#include "sync/internal_api/public/util/immutable.h"
21#include "sync/internal_api/public/util/weak_handle.h"
22
23namespace sync_pb {
24class EntitySpecifics;
25class SyncEntity;
26}  // namespace sync_pb
27
28namespace syncer {
29
30class AttachmentService;
31class SyncDataLocal;
32class SyncDataRemote;
33
34// A light-weight container for immutable sync data. Pass-by-value and storage
35// in STL containers are supported and encouraged if helpful.
36class SYNC_EXPORT SyncData {
37 public:
38  // Creates an empty and invalid SyncData.
39  SyncData();
40  ~SyncData();
41
42  // Default copy and assign welcome.
43
44  // Helper methods for creating SyncData objects for local data.
45  // The sync tag must be a string unique to this datatype and is used as a node
46  // identifier server-side.
47  // For deletes: |datatype| must specify the datatype who node is being
48  // deleted.
49  // For adds/updates: the specifics must be valid and the non-unique title (can
50  // be the same as sync tag) must be specfied.
51  // Note: the non_unique_title is primarily for debug purposes, and will be
52  // overwritten if the datatype is encrypted.
53  static SyncData CreateLocalDelete(
54      const std::string& sync_tag,
55      ModelType datatype);
56  static SyncData CreateLocalData(
57      const std::string& sync_tag,
58      const std::string& non_unique_title,
59      const sync_pb::EntitySpecifics& specifics);
60  static SyncData CreateLocalDataWithAttachments(
61      const std::string& sync_tag,
62      const std::string& non_unique_title,
63      const sync_pb::EntitySpecifics& specifics,
64      const AttachmentList& attachments);
65
66  // Helper method for creating SyncData objects originating from the syncer.
67  //
68  // TODO(maniscalco): Replace all calls to 3-arg CreateRemoteData with calls to
69  // the 5-arg version (bug 353296).
70  static SyncData CreateRemoteData(
71      int64 id,
72      const sync_pb::EntitySpecifics& specifics,
73      const base::Time& last_modified_time,
74      const AttachmentIdList& attachment_ids,
75      const syncer::AttachmentServiceProxy& attachment_service);
76  static SyncData CreateRemoteData(int64 id,
77                                   const sync_pb::EntitySpecifics& specifics,
78                                   const base::Time& last_modified_time);
79
80  // Whether this SyncData holds valid data. The only way to have a SyncData
81  // without valid data is to use the default constructor.
82  bool IsValid() const;
83
84  // Return the datatype we're holding information about. Derived from the sync
85  // datatype specifics.
86  ModelType GetDataType() const;
87
88  // Return the current sync datatype specifics.
89  const sync_pb::EntitySpecifics& GetSpecifics() const;
90
91  // Return the non unique title (for debugging). Currently only set for data
92  // going TO the syncer, not from.
93  const std::string& GetTitle() const;
94
95  // Whether this sync data is for local data or data coming from the syncer.
96  bool IsLocal() const;
97
98  std::string ToString() const;
99
100  // Return a list of this SyncData's attachment ids.
101  //
102  // The attachments may or may not be present on this device.
103  AttachmentIdList GetAttachmentIds() const;
104
105  // TODO(zea): Query methods for other sync properties: parent, successor, etc.
106
107 protected:
108  // These data members are protected so derived types like SyncDataLocal and
109  // SyncDataRemote can access them.
110
111  // Necessary since we forward-declare sync_pb::SyncEntity; see
112  // comments in immutable.h.
113  struct ImmutableSyncEntityTraits {
114    typedef sync_pb::SyncEntity* Wrapper;
115
116    static void InitializeWrapper(Wrapper* wrapper);
117
118    static void DestroyWrapper(Wrapper* wrapper);
119
120    static const sync_pb::SyncEntity& Unwrap(const Wrapper& wrapper);
121
122    static sync_pb::SyncEntity* UnwrapMutable(Wrapper* wrapper);
123
124    static void Swap(sync_pb::SyncEntity* t1, sync_pb::SyncEntity* t2);
125  };
126
127  typedef Immutable<sync_pb::SyncEntity, ImmutableSyncEntityTraits>
128      ImmutableSyncEntity;
129
130  // Equal to kInvalidId iff this is local.
131  int64 id_;
132
133  // This may be null if the SyncData represents a deleted item.
134  base::Time remote_modification_time_;
135
136  // The actual shared sync entity being held.
137  ImmutableSyncEntity immutable_entity_;
138
139  Immutable<AttachmentList> attachments_;
140
141  AttachmentServiceProxy attachment_service_;
142
143 private:
144  // Whether this SyncData holds valid data.
145  bool is_valid_;
146
147  // Clears |entity| and |attachments|.
148  SyncData(int64 id,
149           sync_pb::SyncEntity* entity,
150           AttachmentList* attachments,
151           const base::Time& remote_modification_time,
152           const syncer::AttachmentServiceProxy& attachment_service);
153};
154
155// A SyncData going to the syncer.
156class SYNC_EXPORT SyncDataLocal : public SyncData {
157 public:
158  // Construct a SyncDataLocal from a SyncData.
159  //
160  // |sync_data|'s IsLocal() must be true.
161  explicit SyncDataLocal(const SyncData& sync_data);
162  ~SyncDataLocal();
163
164  // Return a list of this SyncData's attachments.
165  const AttachmentList& GetLocalAttachmentsForUpload() const;
166
167  // Return the value of the unique client tag. This is only set for data going
168  // TO the syncer, not coming from.
169  const std::string& GetTag() const;
170};
171
172// A SyncData that comes from the syncer.
173class SYNC_EXPORT SyncDataRemote : public SyncData {
174 public:
175  // Construct a SyncDataRemote from a SyncData.
176  //
177  // |sync_data|'s IsLocal() must be false.
178  explicit SyncDataRemote(const SyncData& sync_data);
179  ~SyncDataRemote();
180
181  // Return the last motification time according to the server. This may be null
182  // if the SyncData represents a deleted item.
183  const base::Time& GetModifiedTime() const;
184
185  int64 GetId() const;
186
187  // Retrieve the attachments indentified by |attachment_ids|. Invoke
188  // |callback| with the requested attachments.
189  //
190  // |callback| will be invoked when the operation is complete (successfully
191  // or otherwise).
192  //
193  // Retrieving the requested attachments may require reading local storage or
194  // requesting the attachments from the network.
195  //
196  void GetOrDownloadAttachments(
197      const AttachmentIdList& attachment_ids,
198      const AttachmentService::GetOrDownloadCallback& callback);
199
200  // Drop (delete from local storage) the attachments associated with this
201  // SyncData specified in |attachment_ids|. This method will not delete
202  // attachments from the server.
203  //
204  // |callback| will be invoked when the operation is complete (successfully
205  // or otherwise).
206  void DropAttachments(const AttachmentIdList& attachment_ids,
207                       const AttachmentService::DropCallback& callback);
208};
209
210// gmock printer helper.
211void PrintTo(const SyncData& sync_data, std::ostream* os);
212
213typedef std::vector<SyncData> SyncDataList;
214
215}  // namespace syncer
216
217#endif  // SYNC_API_SYNC_DATA_H_
218