sync/api/attachments/attachment_store.h

   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_API_ATTACHMENTS_ATTACHMENT_STORE_H_
   6 #define SYNC_API_ATTACHMENTS_ATTACHMENT_STORE_H_
   7
   8 #include "base/callback.h"
   9 #include "base/memory/ref_counted.h"
  10 #include "base/memory/scoped_ptr.h"
  11 #include "sync/api/attachments/attachment.h"
  12 #include "sync/api/attachments/attachment_id.h"
  13 #include "sync/api/attachments/attachment_metadata.h"
  14 #include "sync/base/sync_export.h"
  15
  16 namespace base {
  17 class FilePath;
  18 class SequencedTaskRunner;
  19 }  // namespace base
  20
  21 namespace syncer {
  22
  23 class AttachmentStoreBackend;
  24 class AttachmentStoreForSync;
  25 class AttachmentStoreFrontend;
  26
  27 // AttachmentStore is a place to locally store and access Attachments.
  28 //
  29 // AttachmentStore class is an interface exposed to data type and
  30 // AttachmentService code.
  31 // It also contains factory methods for default attachment store
  32 // implementations.
  33 // Destroying this object does not necessarily cancel outstanding async
  34 // operations. If you need cancel like semantics, use WeakPtr in the callbacks.
  35 class SYNC_EXPORT AttachmentStore {
  36  public:
  37   // TODO(maniscalco): Consider udpating Read and Write methods to support
  38   // resumable transfers (bug 353292).
  39
  40   // The result status of an attachment store operation.
  41   // Do not re-order or delete these entries; they are used in a UMA histogram.
  42   enum Result {
  43     SUCCESS = 0,            // No error, all completed successfully.
  44     UNSPECIFIED_ERROR = 1,  // An unspecified error occurred for >= 1 item.
  45     STORE_INITIALIZATION_FAILED = 2,  // AttachmentStore initialization failed.
  46     // When adding a value here, you must increment RESULT_SIZE below.
  47   };
  48   static const int RESULT_SIZE =
  49       10;  // Size of the Result enum; used for histograms.
  50
  51   // Each attachment can have references from sync or model type. Tracking these
  52   // references is needed for lifetime management of attachment, it can only be
  53   // deleted from the store when it doesn't have references.
  54   enum Component {
  55     MODEL_TYPE,
  56     SYNC,
  57   };
  58
  59   typedef base::Callback<void(const Result&)> InitCallback;
  60   typedef base::Callback<void(const Result&,
  61                               scoped_ptr<AttachmentMap>,
  62                               scoped_ptr<AttachmentIdList>)> ReadCallback;
  63   typedef base::Callback<void(const Result&)> WriteCallback;
  64   typedef base::Callback<void(const Result&)> DropCallback;
  65   typedef base::Callback<void(const Result&,
  66                               scoped_ptr<AttachmentMetadataList>)>
  67       ReadMetadataCallback;
  68
  69   ~AttachmentStore();
  70
  71   // Asynchronously reads the attachments identified by |ids|.
  72   //
  73   // |callback| will be invoked when finished. AttachmentStore will attempt to
  74   // read all attachments specified in ids. If any of the attachments do not
  75   // exist or could not be read, |callback|'s Result will be UNSPECIFIED_ERROR.
  76   // Callback's AttachmentMap will contain all attachments that were
  77   // successfully read, AttachmentIdList will contain attachment ids of
  78   // attachments that are unavailable in attachment store, these need to be
  79   // downloaded from server.
  80   //
  81   // Reads on individual attachments are treated atomically; |callback| will not
  82   // read only part of an attachment.
  83   void Read(const AttachmentIdList& ids, const ReadCallback& callback);
  84
  85   // Asynchronously writes |attachments| to the store.
  86   //
  87   // Will not overwrite stored attachments. Attempting to overwrite an
  88   // attachment that already exists is not an error.
  89   //
  90   // |callback| will be invoked when finished. If any of the attachments could
  91   // not be written |callback|'s Result will be UNSPECIFIED_ERROR. When this
  92   // happens, some or none of the attachments may have been written
  93   // successfully.
  94   void Write(const AttachmentList& attachments, const WriteCallback& callback);
  95
  96   // Asynchronously drops |attchments| from this store.
  97   //
  98   // This does not remove attachments from the server.
  99   //
 100   // |callback| will be invoked when finished. Attempting to drop an attachment
 101   // that does not exist is not an error. If any of the existing attachment
 102   // could not be dropped, |callback|'s Result will be UNSPECIFIED_ERROR. When
 103   // this happens, some or none of the attachments may have been dropped
 104   // successfully.
 105   void Drop(const AttachmentIdList& ids, const DropCallback& callback);
 106
 107   // Asynchronously reads metadata for the attachments identified by |ids|.
 108   //
 109   // |callback| will be invoked when finished. AttachmentStore will attempt to
 110   // read metadata for all attachments specified in ids. If any of the
 111   // metadata entries do not exist or could not be read, |callback|'s Result
 112   // will be UNSPECIFIED_ERROR.
 113   void ReadMetadataById(const AttachmentIdList& ids,
 114                         const ReadMetadataCallback& callback);
 115
 116   // Asynchronously reads metadata for all attachments with |component_|
 117   // reference in the store.
 118   //
 119   // |callback| will be invoked when finished. If any of the metadata entries
 120   // could not be read, |callback|'s Result will be UNSPECIFIED_ERROR.
 121   void ReadMetadata(const ReadMetadataCallback& callback);
 122
 123   // Given current AttachmentStore (this) creates separate AttachmentStore that
 124   // will be used by sync components (AttachmentService). Resulting
 125   // AttachmentStore is backed by the same frontend/backend.
 126   scoped_ptr<AttachmentStoreForSync> CreateAttachmentStoreForSync() const;
 127
 128   // Creates an AttachmentStore backed by in-memory implementation of attachment
 129   // store. For now frontend lives on the same thread as backend.
 130   static scoped_ptr<AttachmentStore> CreateInMemoryStore();
 131
 132   // Creates an AttachmentStore backed by on-disk implementation of attachment
 133   // store. Opens corresponding leveldb database located at |path|. All backend
 134   // operations are scheduled to |backend_task_runner|. Opening attachment store
 135   // is asynchronous, once it finishes |callback| will be called on the thread
 136   // that called CreateOnDiskStore. Calling Read/Write/Drop before
 137   // initialization completed is allowed.  Later if initialization fails these
 138   // operations will fail with STORE_INITIALIZATION_FAILED error.
 139   static scoped_ptr<AttachmentStore> CreateOnDiskStore(
 140       const base::FilePath& path,
 141       const scoped_refptr<base::SequencedTaskRunner>& backend_task_runner,
 142       const InitCallback& callback);
 143
 144   // Creates set of AttachmentStore/AttachmentStoreFrontend instances for tests
 145   // that provide their own implementation of AttachmentstoreBackend for
 146   // mocking.
 147   static scoped_ptr<AttachmentStore> CreateMockStoreForTest(
 148       scoped_ptr<AttachmentStoreBackend> backend);
 149
 150  protected:
 151   AttachmentStore(const scoped_refptr<AttachmentStoreFrontend>& frontend,
 152                   Component component);
 153
 154   const scoped_refptr<AttachmentStoreFrontend>& frontend() { return frontend_; }
 155   Component component() const { return component_; }
 156
 157  private:
 158   scoped_refptr<AttachmentStoreFrontend> frontend_;
 159   // Modification operations with attachment store will be performed on behalf
 160   // of |component_|.
 161   const Component component_;
 162
 163   DISALLOW_COPY_AND_ASSIGN(AttachmentStore);
 164 };
 165
 166 // AttachmentStoreForSync extends AttachmentStore and provides additional
 167 // functions necessary for AttachmentService. These are needed when
 168 // AttachmentService writes attachment on behalf of model type after download
 169 // and takes reference on attachment for the duration of upload.
 170 // Model type implementation shouldn't use this interface.
 171 class SYNC_EXPORT_PRIVATE AttachmentStoreForSync : public AttachmentStore {
 172  public:
 173   ~AttachmentStoreForSync();
 174
 175   // Asynchronously adds reference from sync to attachments.
 176   void SetSyncReference(const AttachmentIdList& ids);
 177
 178   // Asynchronously adds reference from model type to attachments.
 179   // Needed in GetOrDownloadAttachments when attachment is in local store but
 180   // doesn't have model type reference.
 181   void SetModelTypeReference(const AttachmentIdList& ids);
 182
 183   // Asynchronously drops sync reference from attachments.
 184   void DropSyncReference(const AttachmentIdList& ids);
 185
 186   // Asynchronously reads metadata for all attachments with |sync_component_|
 187   // reference in the store.
 188   //
 189   // |callback| will be invoked when finished. If any of the metadata entries
 190   // could not be read, |callback|'s Result will be UNSPECIFIED_ERROR.
 191   void ReadMetadataForSync(const ReadMetadataCallback& callback);
 192
 193  private:
 194   friend class AttachmentStore;
 195   AttachmentStoreForSync(const scoped_refptr<AttachmentStoreFrontend>& frontend,
 196                          Component consumer_component,
 197                          Component sync_component);
 198
 199   // |sync_component_| is passed to frontend when sync related operations are
 200   // perfromed.
 201   const Component sync_component_;
 202
 203   DISALLOW_COPY_AND_ASSIGN(AttachmentStoreForSync);
 204 };
 205
 206 }  // namespace syncer
 207
 208 #endif  // SYNC_API_ATTACHMENTS_ATTACHMENT_STORE_H_