extensions/browser/value_store/value_store.h

// Copyright 2014 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef EXTENSIONS_BROWSER_VALUE_STORE_VALUE_STORE_H_
#define EXTENSIONS_BROWSER_VALUE_STORE_VALUE_STORE_H_

#include <string>
#include <vector>

#include "base/memory/scoped_ptr.h"
#include "base/values.h"
#include "extensions/browser/value_store/value_store_change.h"

// Interface for a storage area for Value objects.
class ValueStore {
 public:
  // Error codes returned from storage methods.
  enum ErrorCode {
    OK,

    // The failure was due to some kind of database corruption. Depending on
    // what is corrupted, some part of the database may be recoverable.
    //
    // For example, if the on-disk representation of leveldb is corrupted, it's
    // likely the whole database will need to be wiped and started again.
    //
    // If a single key has been committed with an invalid JSON representation,
    // just that key can be deleted without affecting the rest of the database.
    CORRUPTION,

    // The failure was due to the store being read-only (for example, policy).
    READ_ONLY,

    // The failure was due to the store running out of space.
    QUOTA_EXCEEDED,

    // Any other error.
    OTHER_ERROR,
  };

  // Bundles an ErrorCode with further metadata.
  struct Error {
    Error(ErrorCode code,
          const std::string& message,
          scoped_ptr<std::string> key);
    ~Error();

    static scoped_ptr<Error> Create(ErrorCode code,
                                    const std::string& message,
                                    scoped_ptr<std::string> key) {
      return make_scoped_ptr(new Error(code, message, key.Pass()));
    }

    // The error code.
    const ErrorCode code;

    // Message associated with the error.
    const std::string message;

    // The key associated with the error, if any. Use a scoped_ptr here
    // because empty-string is a valid key.
    //
    // TODO(kalman): add test(s) for an empty key.
    const scoped_ptr<std::string> key;

   private:
    DISALLOW_COPY_AND_ASSIGN(Error);
  };

  // The result of a read operation (Get).
  class ReadResultType {
   public:
    explicit ReadResultType(scoped_ptr<base::DictionaryValue> settings);
    explicit ReadResultType(scoped_ptr<Error> error);
    ~ReadResultType();

    bool HasError() const { return error_; }

    bool IsCorrupted() const {
      return error_.get() && error_->code == CORRUPTION;
    }

    // Gets the settings read from the storage. Note that this represents
    // the root object. If you request the value for key "foo", that value will
    // be in |settings|.|foo|.
    //
    // Must only be called if there is no error.
    base::DictionaryValue& settings() { return *settings_; }
    scoped_ptr<base::DictionaryValue> PassSettings() {
      return settings_.Pass();
    }

    // Only call if HasError is true.
    const Error& error() const { return *error_; }
    scoped_ptr<Error> PassError() { return error_.Pass(); }

   private:
    scoped_ptr<base::DictionaryValue> settings_;
    scoped_ptr<Error> error_;

    DISALLOW_COPY_AND_ASSIGN(ReadResultType);
  };
  typedef scoped_ptr<ReadResultType> ReadResult;

  // The result of a write operation (Set/Remove/Clear).
  class WriteResultType {
   public:
    explicit WriteResultType(scoped_ptr<ValueStoreChangeList> changes);
    explicit WriteResultType(scoped_ptr<Error> error);
    ~WriteResultType();

    bool HasError() const { return error_; }

    // Gets the list of changes to the settings which resulted from the write.
    // Won't be present if the NO_GENERATE_CHANGES WriteOptions was given.
    // Only call if HasError is false.
    ValueStoreChangeList& changes() { return *changes_; }
    scoped_ptr<ValueStoreChangeList> PassChanges() { return changes_.Pass(); }

    // Only call if HasError is true.
    const Error& error() const { return *error_; }
    scoped_ptr<Error> PassError() { return error_.Pass(); }

   private:
    scoped_ptr<ValueStoreChangeList> changes_;
    scoped_ptr<Error> error_;

    DISALLOW_COPY_AND_ASSIGN(WriteResultType);
  };
  typedef scoped_ptr<WriteResultType> WriteResult;

  // Options for write operations.
  enum WriteOptionsValues {
    // Callers should usually use this.
    DEFAULTS = 0,

    // Ignore any quota restrictions.
    IGNORE_QUOTA = 1<<1,

    // Don't generate the changes for a WriteResult.
    NO_GENERATE_CHANGES = 1<<2,
  };
  typedef int WriteOptions;

  virtual ~ValueStore() {}

  // Helpers for making a Read/WriteResult.
  template<typename T>
  static ReadResult MakeReadResult(scoped_ptr<T> arg) {
    return ReadResult(new ReadResultType(arg.Pass()));
  }

  template<typename T>
  static WriteResult MakeWriteResult(scoped_ptr<T> arg) {
    return WriteResult(new WriteResultType(arg.Pass()));
  }

  // Gets the amount of space being used by a single value, in bytes.
  // Note: The GetBytesInUse methods are only used by extension settings at the
  // moment. If these become more generally useful, the
  // SettingsStorageQuotaEnforcer and WeakUnlimitedSettingsStorage classes
  // should be moved to the value_store directory.
  virtual size_t GetBytesInUse(const std::string& key) = 0;

  // Gets the total amount of space being used by multiple values, in bytes.
  virtual size_t GetBytesInUse(const std::vector<std::string>& keys) = 0;

  // Gets the total amount of space being used by this storage area, in bytes.
  virtual size_t GetBytesInUse() = 0;

  // Gets a single value from storage.
  virtual ReadResult Get(const std::string& key) = 0;

  // Gets multiple values from storage.
  virtual ReadResult Get(const std::vector<std::string>& keys) = 0;

  // Gets all values from storage.
  virtual ReadResult Get() = 0;

  // Sets a single key to a new value.
  virtual WriteResult Set(WriteOptions options,
                          const std::string& key,
                          const base::Value& value) = 0;

  // Sets multiple keys to new values.
  virtual WriteResult Set(
      WriteOptions options, const base::DictionaryValue& values) = 0;

  // Removes a key from the storage.
  virtual WriteResult Remove(const std::string& key) = 0;

  // Removes multiple keys from the storage.
  virtual WriteResult Remove(const std::vector<std::string>& keys) = 0;

  // Clears the storage.
  virtual WriteResult Clear() = 0;

  // In the event of corruption, the ValueStore should be able to restore
  // itself. This means deleting local corrupted files. If only a few keys are
  // corrupted, then some of the database may be saved. If the full database is
  // corrupted, this will erase it in its entirety.
  // Returns true on success, false on failure. The only way this will fail is
  // if we also cannot delete the database file.
  // Note: This method may be expensive; some implementations may need to read
  // the entire database to restore. Use sparingly.
  // Note: This method (and the following RestoreKey()) are rude, and do not
  // make any logs, track changes, or other generally polite things. Please do
  // not use these as substitutes for Clear() and Remove().
  virtual bool Restore() = 0;

  // Similar to Restore(), but for only a particular key. If the key is corrupt,
  // this will forcefully remove the key. It does not look at the database on
  // the whole, which makes it faster, but does not guarantee there is no
  // additional corruption.
  // Returns true on success, and false on failure. If false, the next step is
  // probably to Restore() the whole database.
  virtual bool RestoreKey(const std::string& key) = 0;
};

#endif  // EXTENSIONS_BROWSER_VALUE_STORE_VALUE_STORE_H_