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 RefCountedMemory;
  19 class SequencedTaskRunner;
  20 }  // namespace base
  21
  22 namespace syncer {
  23
  24 class Attachment;
  25 class AttachmentId;
  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 base::RefCountedThreadSafe<AttachmentStore> {
  37  public:
  38   // TODO(maniscalco): Consider udpating Read and Write methods to support
  39   // resumable transfers (bug 353292).
  40
  41   // The result status of an attachment store operation.
  42   // Do not re-order or delete these entries; they are used in a UMA histogram.
  43   enum Result {
  44     SUCCESS = 0,            // No error, all completed successfully.
  45     UNSPECIFIED_ERROR = 1,  // An unspecified error occurred for >= 1 item.
  46     STORE_INITIALIZATION_FAILED = 2,  // AttachmentStore initialization failed.
  47     // When adding a value here, you must increment RESULT_SIZE below.
  48   };
  49   static const int RESULT_SIZE =
  50       10;  // Size of the Result enum; used for histograms.
  51
  52   typedef base::Callback<void(const Result&)> InitCallback;
  53   typedef base::Callback<void(const Result&,
  54                               scoped_ptr<AttachmentMap>,
  55                               scoped_ptr<AttachmentIdList>)> ReadCallback;
  56   typedef base::Callback<void(const Result&)> WriteCallback;
  57   typedef base::Callback<void(const Result&)> DropCallback;
  58   typedef base::Callback<void(const Result&,
  59                               scoped_ptr<AttachmentMetadataList>)>
  60       ReadMetadataCallback;
  61
  62   AttachmentStore();
  63
  64   // Asynchronously initializes attachment store.
  65   //
  66   // This method should not be called by consumer of this interface. It is
  67   // called by factory methods in AttachmentStore class. When initialization is
  68   // complete |callback| is invoked with result, in case of failure result is
  69   // UNSPECIFIED_ERROR.
  70   virtual void Init(const InitCallback& callback) = 0;
  71
  72   // Asynchronously reads the attachments identified by |ids|.
  73   //
  74   // |callback| will be invoked when finished. AttachmentStore will attempt to
  75   // read all attachments specified in ids. If any of the attachments do not
  76   // exist or could not be read, |callback|'s Result will be UNSPECIFIED_ERROR.
  77   // Callback's AttachmentMap will contain all attachments that were
  78   // successfully read, AttachmentIdList will contain attachment ids of
  79   // attachments that are unavailable in attachment store, these need to be
  80   // downloaded from server.
  81   //
  82   // Reads on individual attachments are treated atomically; |callback| will not
  83   // read only part of an attachment.
  84   virtual void Read(const AttachmentIdList& ids,
  85                     const ReadCallback& callback) = 0;
  86
  87   // Asynchronously writes |attachments| to the store.
  88   //
  89   // Will not overwrite stored attachments. Attempting to overwrite an
  90   // attachment that already exists is not an error.
  91   //
  92   // |callback| will be invoked when finished. If any of the attachments could
  93   // not be written |callback|'s Result will be UNSPECIFIED_ERROR. When this
  94   // happens, some or none of the attachments may have been written
  95   // successfully.
  96   virtual void Write(const AttachmentList& attachments,
  97                      const WriteCallback& callback) = 0;
  98
  99   // Asynchronously drops |attchments| from this store.
 100   //
 101   // This does not remove attachments from the server.
 102   //
 103   // |callback| will be invoked when finished. Attempting to drop an attachment
 104   // that does not exist is not an error. If any of the existing attachment
 105   // could not be dropped, |callback|'s Result will be UNSPECIFIED_ERROR. When
 106   // this happens, some or none of the attachments may have been dropped
 107   // successfully.
 108   virtual void Drop(const AttachmentIdList& ids,
 109                     const DropCallback& callback) = 0;
 110
 111   // Asynchronously reads metadata for the attachments identified by |ids|.
 112   //
 113   // |callback| will be invoked when finished. AttachmentStore will attempt to
 114   // read metadata for all attachments specified in ids. If any of the
 115   // metadata entries do not exist or could not be read, |callback|'s Result
 116   // will be UNSPECIFIED_ERROR.
 117   virtual void ReadMetadata(const AttachmentIdList& ids,
 118                             const ReadMetadataCallback& callback) = 0;
 119
 120   // Asynchronously reads metadata for all attachments in the store.
 121   //
 122   // |callback| will be invoked when finished. If any of the metadata entries
 123   // could not be read, |callback|'s Result will be UNSPECIFIED_ERROR.
 124   virtual void ReadAllMetadata(const ReadMetadataCallback& callback) = 0;
 125
 126   // Creates an AttachmentStoreHandle backed by in-memory implementation of
 127   // attachment store. For now frontend lives on the same thread as backend.
 128   static scoped_refptr<AttachmentStore> CreateInMemoryStore();
 129
 130   // Creates an AttachmentStoreHandle backed by on-disk implementation of
 131   // attachment store. Opens corresponding leveldb database located at |path|.
 132   // All backend operations are scheduled to |backend_task_runner|. Opening
 133   // attachment store is asynchronous, once it finishes |callback| will be
 134   // called on the thread that called CreateOnDiskStore. Calling Read/Write/Drop
 135   // before initialization completed is allowed.  Later if initialization fails
 136   // these operations will fail with STORE_INITIALIZATION_FAILED error.
 137   static scoped_refptr<AttachmentStore> CreateOnDiskStore(
 138       const base::FilePath& path,
 139       const scoped_refptr<base::SequencedTaskRunner>& backend_task_runner,
 140       const InitCallback& callback);
 141
 142  protected:
 143   friend class base::RefCountedThreadSafe<AttachmentStore>;
 144   virtual ~AttachmentStore();
 145 };
 146
 147 // Interface for AttachmentStore backends.
 148 //
 149 // AttachmentStoreBackend provides interface for different backends (on-disk,
 150 // in-memory). Factory methods in AttachmentStore create corresponding backend
 151 // and pass reference to AttachmentStoreHandle.
 152 // All functions in AttachmentStoreBackend mirror corresponding functions in
 153 // AttachmentStore.
 154 // All callbacks and result codes are used directly from AttachmentStore.
 155 // AttachmentStoreHandle only passes callbacks and results, there is no need to
 156 // declare separate set.
 157 class SYNC_EXPORT AttachmentStoreBackend {
 158  public:
 159   explicit AttachmentStoreBackend(
 160       const scoped_refptr<base::SequencedTaskRunner>& callback_task_runner);
 161   virtual ~AttachmentStoreBackend();
 162   virtual void Init(const AttachmentStore::InitCallback& callback) = 0;
 163   virtual void Read(const AttachmentIdList& ids,
 164                     const AttachmentStore::ReadCallback& callback) = 0;
 165   virtual void Write(const AttachmentList& attachments,
 166                      const AttachmentStore::WriteCallback& callback) = 0;
 167   virtual void Drop(const AttachmentIdList& ids,
 168                     const AttachmentStore::DropCallback& callback) = 0;
 169   virtual void ReadMetadata(
 170       const AttachmentIdList& ids,
 171       const AttachmentStore::ReadMetadataCallback& callback) = 0;
 172   virtual void ReadAllMetadata(
 173       const AttachmentStore::ReadMetadataCallback& callback) = 0;
 174
 175  protected:
 176   // Helper function to post callback on callback_task_runner.
 177   void PostCallback(const base::Closure& callback);
 178
 179  private:
 180   scoped_refptr<base::SequencedTaskRunner> callback_task_runner_;
 181
 182   DISALLOW_COPY_AND_ASSIGN(AttachmentStoreBackend);
 183 };
 184
 185 }  // namespace syncer
 186
 187 #endif  // SYNC_API_ATTACHMENTS_ATTACHMENT_STORE_H_