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.
16class 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_
197