sync/api/sync_data.h

   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_