chrome/browser/value_store/value_store.h

   1 // Copyright (c) 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 CHROME_BROWSER_VALUE_STORE_VALUE_STORE_H_
   6 #define CHROME_BROWSER_VALUE_STORE_VALUE_STORE_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/memory/scoped_ptr.h"
  12 #include "base/values.h"
  13 #include "chrome/browser/value_store/value_store_change.h"
  14
  15 // Interface for a storage area for Value objects.
  16 class ValueStore {
  17  public:
  18   // Error codes returned from storage methods.
  19   enum ErrorCode {
  20     OK,
  21
  22     // The failure was due to some kind of database corruption. Depending on
  23     // what is corrupted, some part of the database may be recoverable.
  24     //
  25     // For example, if the on-disk representation of leveldb is corrupted, it's
  26     // likely the whole database will need to be wiped and started again.
  27     //
  28     // If a single key has been committed with an invalid JSON representation,
  29     // just that key can be deleted without affecting the rest of the database.
  30     CORRUPTION,
  31
  32     // The failure was due to the store being read-only (for example, policy).
  33     READ_ONLY,
  34
  35     // The failure was due to the store running out of space.
  36     QUOTA_EXCEEDED,
  37
  38     // Any other error.
  39     OTHER_ERROR,
  40   };
  41
  42   // Bundles an ErrorCode with further metadata.
  43   struct Error {
  44     Error(ErrorCode code,
  45           const std::string& message,
  46           scoped_ptr<std::string> key);
  47     ~Error();
  48
  49     static scoped_ptr<Error> Create(ErrorCode code,
  50                                     const std::string& message,
  51                                     scoped_ptr<std::string> key) {
  52       return make_scoped_ptr(new Error(code, message, key.Pass()));
  53     }
  54
  55     // The error code.
  56     const ErrorCode code;
  57
  58     // Message associated with the error.
  59     const std::string message;
  60
  61     // The key associated with the error, if any. Use a scoped_ptr here
  62     // because empty-string is a valid key.
  63     //
  64     // TODO(kalman): add test(s) for an empty key.
  65     const scoped_ptr<std::string> key;
  66
  67    private:
  68     DISALLOW_COPY_AND_ASSIGN(Error);
  69   };
  70
  71   // The result of a read operation (Get).
  72   class ReadResultType {
  73    public:
  74     explicit ReadResultType(scoped_ptr<base::DictionaryValue> settings);
  75     explicit ReadResultType(scoped_ptr<Error> error);
  76     ~ReadResultType();
  77
  78     bool HasError() const { return error_; }
  79
  80     // Gets the settings read from the storage. Note that this represents
  81     // the root object. If you request the value for key "foo", that value will
  82     // be in |settings|.|foo|.
  83     //
  84     // Must only be called if there is no error.
  85     base::DictionaryValue& settings() { return *settings_; }
  86     scoped_ptr<base::DictionaryValue> PassSettings() {
  87       return settings_.Pass();
  88     }
  89
  90     // Only call if HasError is true.
  91     const Error& error() const { return *error_; }
  92     scoped_ptr<Error> PassError() { return error_.Pass(); }
  93
  94    private:
  95     scoped_ptr<base::DictionaryValue> settings_;
  96     scoped_ptr<Error> error_;
  97
  98     DISALLOW_COPY_AND_ASSIGN(ReadResultType);
  99   };
 100   typedef scoped_ptr<ReadResultType> ReadResult;
 101
 102   // The result of a write operation (Set/Remove/Clear).
 103   class WriteResultType {
 104    public:
 105     explicit WriteResultType(scoped_ptr<ValueStoreChangeList> changes);
 106     explicit WriteResultType(scoped_ptr<Error> error);
 107     ~WriteResultType();
 108
 109     bool HasError() const { return error_; }
 110
 111     // Gets the list of changes to the settings which resulted from the write.
 112     // Won't be present if the NO_GENERATE_CHANGES WriteOptions was given.
 113     // Only call if HasError is false.
 114     ValueStoreChangeList& changes() { return *changes_; }
 115     scoped_ptr<ValueStoreChangeList> PassChanges() { return changes_.Pass(); }
 116
 117     // Only call if HasError is true.
 118     const Error& error() const { return *error_; }
 119     scoped_ptr<Error> PassError() { return error_.Pass(); }
 120
 121    private:
 122     scoped_ptr<ValueStoreChangeList> changes_;
 123     scoped_ptr<Error> error_;
 124
 125     DISALLOW_COPY_AND_ASSIGN(WriteResultType);
 126   };
 127   typedef scoped_ptr<WriteResultType> WriteResult;
 128
 129   // Options for write operations.
 130   enum WriteOptionsValues {
 131     // Callers should usually use this.
 132     DEFAULTS = 0,
 133
 134     // Ignore any quota restrictions.
 135     IGNORE_QUOTA = 1<<1,
 136
 137     // Don't generate the changes for a WriteResult.
 138     NO_GENERATE_CHANGES = 1<<2,
 139   };
 140   typedef int WriteOptions;
 141
 142   virtual ~ValueStore() {}
 143
 144   // Helpers for making a Read/WriteResult.
 145   template<typename T>
 146   static ReadResult MakeReadResult(scoped_ptr<T> arg) {
 147     return ReadResult(new ReadResultType(arg.Pass()));
 148   }
 149
 150   template<typename T>
 151   static WriteResult MakeWriteResult(scoped_ptr<T> arg) {
 152     return WriteResult(new WriteResultType(arg.Pass()));
 153   }
 154
 155   // Gets the amount of space being used by a single value, in bytes.
 156   // Note: The GetBytesInUse methods are only used by extension settings at the
 157   // moment. If these become more generally useful, the
 158   // SettingsStorageQuotaEnforcer and WeakUnlimitedSettingsStorage classes
 159   // should be moved to the value_store directory.
 160   virtual size_t GetBytesInUse(const std::string& key) = 0;
 161
 162   // Gets the total amount of space being used by multiple values, in bytes.
 163   virtual size_t GetBytesInUse(const std::vector<std::string>& keys) = 0;
 164
 165   // Gets the total amount of space being used by this storage area, in bytes.
 166   virtual size_t GetBytesInUse() = 0;
 167
 168   // Gets a single value from storage.
 169   virtual ReadResult Get(const std::string& key) = 0;
 170
 171   // Gets multiple values from storage.
 172   virtual ReadResult Get(const std::vector<std::string>& keys) = 0;
 173
 174   // Gets all values from storage.
 175   virtual ReadResult Get() = 0;
 176
 177   // Sets a single key to a new value.
 178   virtual WriteResult Set(WriteOptions options,
 179                           const std::string& key,
 180                           const base::Value& value) = 0;
 181
 182   // Sets multiple keys to new values.
 183   virtual WriteResult Set(
 184       WriteOptions options, const base::DictionaryValue& values) = 0;
 185
 186   // Removes a key from the storage.
 187   virtual WriteResult Remove(const std::string& key) = 0;
 188
 189   // Removes multiple keys from the storage.
 190   virtual WriteResult Remove(const std::vector<std::string>& keys) = 0;
 191
 192   // Clears the storage.
 193   virtual WriteResult Clear() = 0;
 194 };
 195
 196 #endif  // CHROME_BROWSER_VALUE_STORE_VALUE_STORE_H_