base/json/json_file_value_serializer.h

   1 // Copyright 2012 The Chromium Authors
   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 BASE_JSON_JSON_FILE_VALUE_SERIALIZER_H_
   6 #define BASE_JSON_JSON_FILE_VALUE_SERIALIZER_H_
   7
   8 #include <stddef.h>
   9
  10 #include <memory>
  11 #include <string>
  12
  13 #include "base/base_export.h"
  14 #include "base/files/file_path.h"
  15 #include "base/json/json_reader.h"
  16 #include "base/values.h"
  17
  18 class BASE_EXPORT JSONFileValueSerializer : public base::ValueSerializer {
  19  public:
  20   JSONFileValueSerializer() = delete;
  21
  22   // |json_file_path_| is the path of a file that will be destination of the
  23   // serialization. The serializer will attempt to create the file at the
  24   // specified location.
  25   explicit JSONFileValueSerializer(const base::FilePath& json_file_path);
  26
  27   JSONFileValueSerializer(const JSONFileValueSerializer&) = delete;
  28   JSONFileValueSerializer& operator=(const JSONFileValueSerializer&) = delete;
  29
  30   ~JSONFileValueSerializer() override;
  31
  32   // DO NOT USE except in unit tests to verify the file was written properly.
  33   // We should never serialize directly to a file since this will block the
  34   // thread. Instead, serialize to a string and write to the file you want on
  35   // the thread pool.
  36   //
  37   // Attempt to serialize the data structure represented by Value into
  38   // JSON.  If the return value is true, the result will have been written
  39   // into the file whose name was passed into the constructor.
  40   bool Serialize(base::ValueView root) override;
  41
  42   // Equivalent to Serialize(root) except binary values are omitted from the
  43   // output.
  44   bool SerializeAndOmitBinaryValues(base::ValueView root);
  45
  46  private:
  47   bool SerializeInternal(base::ValueView root, bool omit_binary_values);
  48
  49   const base::FilePath json_file_path_;
  50 };
  51
  52 class BASE_EXPORT JSONFileValueDeserializer : public base::ValueDeserializer {
  53  public:
  54   JSONFileValueDeserializer() = delete;
  55
  56   // |json_file_path_| is the path of a file that will be source of the
  57   // deserialization. |options| is a bitmask of JSONParserOptions.
  58   explicit JSONFileValueDeserializer(
  59       const base::FilePath& json_file_path,
  60       int options = base::JSON_PARSE_CHROMIUM_EXTENSIONS);
  61
  62   JSONFileValueDeserializer(const JSONFileValueDeserializer&) = delete;
  63   JSONFileValueDeserializer& operator=(const JSONFileValueDeserializer&) =
  64       delete;
  65
  66   ~JSONFileValueDeserializer() override;
  67
  68   // Attempts to deserialize the data structure encoded in the file passed to
  69   // the constructor into a structure of Value objects. If the return value is
  70   // null, then
  71   // (1) |error_code| will be filled with an integer error code (either a
  72   //     JsonFileError or base::ValueDeserializer::kErrorCodeInvalidFormat) if a
  73   //     non-null |error_code| was given.
  74   // (2) |error_message| will be filled with a formatted error message,
  75   //     including the location of the error (if appropriate), if a non-null
  76   //     |error_message| was given.
  77   // The caller takes ownership of the returned value.
  78   std::unique_ptr<base::Value> Deserialize(int* error_code,
  79                                            std::string* error_message) override;
  80
  81   // This enum is designed to safely overlap with JSONParser::JsonParseError.
  82   //
  83   // These values are persisted to logs. Entries should not be renumbered and
  84   // numeric values should never be reused.
  85   enum JsonFileError {
  86     JSON_NO_ERROR = 0,
  87     JSON_ACCESS_DENIED = kErrorCodeFirstMetadataError,
  88     JSON_CANNOT_READ_FILE,
  89     JSON_FILE_LOCKED,
  90     JSON_NO_SUCH_FILE
  91   };
  92
  93   // File-specific error messages that can be returned.
  94   static const char kAccessDenied[];
  95   static const char kCannotReadFile[];
  96   static const char kFileLocked[];
  97   static const char kNoSuchFile[];
  98
  99   // Convert an error code into an error message.  |error_code| is assumed to
 100   // be a JsonFileError.
 101   static const char* GetErrorMessageForCode(int error_code);
 102
 103   // Returns the size (in bytes) of JSON string read from disk in the last
 104   // successful |Deserialize()| call.
 105   size_t get_last_read_size() const { return last_read_size_; }
 106
 107  private:
 108   // A wrapper for ReadFileToString which returns a non-zero JsonFileError if
 109   // there were file errors.
 110   int ReadFileToString(std::string* json_string);
 111
 112   const base::FilePath json_file_path_;
 113   const int options_;
 114   size_t last_read_size_ = 0u;
 115 };
 116
 117 #endif  // BASE_JSON_JSON_FILE_VALUE_SERIALIZER_H_
 118