• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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/memory/ref_counted.h"
15 #include "base/stl_util.h"
16 #include "base/time/time.h"
17 #include "sync/api/attachments/attachment_id.h"
18 #include "sync/base/sync_export.h"
19 #include "sync/internal_api/public/attachments/attachment_service_proxy.h"
20 #include "sync/internal_api/public/base/model_type.h"
21 #include "sync/internal_api/public/util/immutable.h"
22 #include "sync/internal_api/public/util/weak_handle.h"
23 
24 namespace sync_pb {
25 class EntitySpecifics;
26 class SyncEntity;
27 }  // namespace sync_pb
28 
29 namespace syncer {
30 
31 class AttachmentService;
32 class SyncDataLocal;
33 class SyncDataRemote;
34 
35 // A light-weight container for immutable sync data. Pass-by-value and storage
36 // in STL containers are supported and encouraged if helpful.
37 class SYNC_EXPORT SyncData {
38  public:
39   // Creates an empty and invalid SyncData.
40   SyncData();
41   ~SyncData();
42 
43   // Default copy and assign welcome.
44 
45   // Helper methods for creating SyncData objects for local data.
46   //
47   // |sync_tag| Must be a string unique to this datatype and is used as a node
48   // identifier server-side.
49   //
50   // For deletes: |datatype| must specify the datatype who node is being
51   // deleted.
52   //
53   // For adds/updates: |specifics| must be valid and |non_unique_title| (can be
54   // the same as |sync_tag|) must be specfied.  Note: |non_unique_title| is
55   // primarily for debug purposes, and will be overwritten if the datatype is
56   // encrypted.
57   //
58   // For data with attachments: |attachment_ids| must not contain duplicates.
59   static SyncData CreateLocalDelete(
60       const std::string& sync_tag,
61       ModelType datatype);
62   static SyncData CreateLocalData(
63       const std::string& sync_tag,
64       const std::string& non_unique_title,
65       const sync_pb::EntitySpecifics& specifics);
66   static SyncData CreateLocalDataWithAttachments(
67       const std::string& sync_tag,
68       const std::string& non_unique_title,
69       const sync_pb::EntitySpecifics& specifics,
70       const AttachmentIdList& attachment_ids);
71 
72   // Helper method for creating SyncData objects originating from the syncer.
73   static SyncData CreateRemoteData(
74       int64 id,
75       const sync_pb::EntitySpecifics& specifics,
76       const base::Time& last_modified_time,
77       const AttachmentIdList& attachment_ids,
78       const syncer::AttachmentServiceProxy& attachment_service);
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 SYNC_EXPORT 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   AttachmentServiceProxy attachment_service_;
140 
141  private:
142   // Whether this SyncData holds valid data.
143   bool is_valid_;
144 
145   // Clears |entity| and |attachments|.
146   SyncData(int64 id,
147            sync_pb::SyncEntity* entity,
148            const base::Time& remote_modification_time,
149            const syncer::AttachmentServiceProxy& attachment_service);
150 };
151 
152 // A SyncData going to the syncer.
153 class SYNC_EXPORT SyncDataLocal : public SyncData {
154  public:
155   // Construct a SyncDataLocal from a SyncData.
156   //
157   // |sync_data|'s IsLocal() must be true.
158   explicit SyncDataLocal(const SyncData& sync_data);
159   ~SyncDataLocal();
160 
161   // Return the value of the unique client tag. This is only set for data going
162   // TO the syncer, not coming from.
163   const std::string& GetTag() const;
164 };
165 
166 // A SyncData that comes from the syncer.
167 class SYNC_EXPORT SyncDataRemote : public SyncData {
168  public:
169   // Construct a SyncDataRemote from a SyncData.
170   //
171   // |sync_data|'s IsLocal() must be false.
172   explicit SyncDataRemote(const SyncData& sync_data);
173   ~SyncDataRemote();
174 
175   // Return the last motification time according to the server. This may be null
176   // if the SyncData represents a deleted item.
177   const base::Time& GetModifiedTime() const;
178 
179   int64 GetId() const;
180 
181   // Retrieve the attachments indentified by |attachment_ids|. Invoke
182   // |callback| with the requested attachments.
183   //
184   // |callback| will be invoked when the operation is complete (successfully
185   // or otherwise).
186   //
187   // Retrieving the requested attachments may require reading local storage or
188   // requesting the attachments from the network.
189   //
190   void GetOrDownloadAttachments(
191       const AttachmentIdList& attachment_ids,
192       const AttachmentService::GetOrDownloadCallback& callback);
193 
194   // Drop (delete from local storage) the attachments associated with this
195   // SyncData specified in |attachment_ids|. This method will not delete
196   // attachments from the server.
197   //
198   // |callback| will be invoked when the operation is complete (successfully
199   // or otherwise).
200   void DropAttachments(const AttachmentIdList& attachment_ids,
201                        const AttachmentService::DropCallback& callback);
202 };
203 
204 // gmock printer helper.
205 void PrintTo(const SyncData& sync_data, std::ostream* os);
206 
207 typedef std::vector<SyncData> SyncDataList;
208 
209 }  // namespace syncer
210 
211 #endif  // SYNC_API_SYNC_DATA_H_
212