1// Protocol Buffers - Google's data interchange format
2// Copyright 2008 Google Inc. All rights reserved.
3// https://developers.google.com/protocol-buffers/
4//
5// Redistribution and use in source and binary forms, with or without
6// modification, are permitted provided that the following conditions are
7// met:
8//
9// * Redistributions of source code must retain the above copyright
10// notice, this list of conditions and the following disclaimer.
11// * Redistributions in binary form must reproduce the above
12// copyright notice, this list of conditions and the following disclaimer
13// in the documentation and/or other materials provided with the
14// distribution.
15// * Neither the name of Google Inc. nor the names of its
16// contributors may be used to endorse or promote products derived from
17// this software without specific prior written permission.
18//
19// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
31#ifndef GOOGLE_PROTOBUF_UTIL_INTERNAL_DEFAULT_VALUE_OBJECTWRITER_H__
32#define GOOGLE_PROTOBUF_UTIL_INTERNAL_DEFAULT_VALUE_OBJECTWRITER_H__
33
34#include <cstdint>
35#include <functional>
36#include <memory>
37#include <stack>
38#include <vector>
39
40#include <google/protobuf/stubs/common.h>
41#include <google/protobuf/stubs/strutil.h>
42#include <google/protobuf/util/internal/datapiece.h>
43#include <google/protobuf/util/internal/object_writer.h>
44#include <google/protobuf/util/internal/type_info.h>
45#include <google/protobuf/util/internal/utility.h>
46#include <google/protobuf/util/type_resolver.h>
47
48// Must be included last.
49#include <google/protobuf/port_def.inc>
50
51namespace google {
52namespace protobuf {
53namespace util {
54namespace converter {
55
56// An ObjectWriter that renders non-repeated primitive fields of proto messages
57// with their default values. DefaultValueObjectWriter holds objects, lists and
58// fields it receives in a tree structure and writes them out to another
59// ObjectWriter when EndObject() is called on the root object. It also writes
60// out all non-repeated primitive fields that haven't been explicitly rendered
61// with their default values (0 for numbers, "" for strings, etc).
62class PROTOBUF_EXPORT DefaultValueObjectWriter : public ObjectWriter {
63 public:
64 // A Callback function to check whether a field needs to be scrubbed.
65 //
66 // Returns true if the field should not be present in the output. Returns
67 // false otherwise.
68 //
69 // The 'path' parameter is a vector of path to the field from root. For
70 // example: if a nested field "a.b.c" (b is the parent message field of c and
71 // a is the parent message field of b), then the vector should contain { "a",
72 // "b", "c" }.
73 //
74 // The Field* should point to the google::protobuf::Field of "c".
75 typedef std::function<bool(
76 const std::vector<std::string>& /*path of the field*/,
77 const google::protobuf::Field* /*field*/)>
78 FieldScrubCallBack;
79
80 DefaultValueObjectWriter(TypeResolver* type_resolver,
81 const google::protobuf::Type& type,
82 ObjectWriter* ow);
83
84 ~DefaultValueObjectWriter() override;
85
86 // ObjectWriter methods.
87 DefaultValueObjectWriter* StartObject(StringPiece name) override;
88
89 DefaultValueObjectWriter* EndObject() override;
90
91 DefaultValueObjectWriter* StartList(StringPiece name) override;
92
93 DefaultValueObjectWriter* EndList() override;
94
95 DefaultValueObjectWriter* RenderBool(StringPiece name,
96 bool value) override;
97
98 DefaultValueObjectWriter* RenderInt32(StringPiece name,
99 int32_t value) override;
100
101 DefaultValueObjectWriter* RenderUint32(StringPiece name,
102 uint32_t value) override;
103
104 DefaultValueObjectWriter* RenderInt64(StringPiece name,
105 int64_t value) override;
106
107 DefaultValueObjectWriter* RenderUint64(StringPiece name,
108 uint64_t value) override;
109
110 DefaultValueObjectWriter* RenderDouble(StringPiece name,
111 double value) override;
112
113 DefaultValueObjectWriter* RenderFloat(StringPiece name,
114 float value) override;
115
116 DefaultValueObjectWriter* RenderString(StringPiece name,
117 StringPiece value) override;
118 DefaultValueObjectWriter* RenderBytes(StringPiece name,
119 StringPiece value) override;
120
121 DefaultValueObjectWriter* RenderNull(StringPiece name) override;
122
123 // Register the callback for scrubbing of fields.
124 void RegisterFieldScrubCallBack(FieldScrubCallBack field_scrub_callback);
125
126 // If set to true, empty lists are suppressed from output when default values
127 // are written.
128 void set_suppress_empty_list(bool value) { suppress_empty_list_ = value; }
129
130 // If set to true, original proto field names are used
131 void set_preserve_proto_field_names(bool value) {
132 preserve_proto_field_names_ = value;
133 }
134
135 // If set to true, enums are rendered as ints from output when default values
136 // are written.
137 void set_print_enums_as_ints(bool value) { use_ints_for_enums_ = value; }
138
139 protected:
140 enum NodeKind {
141 PRIMITIVE = 0,
142 OBJECT = 1,
143 LIST = 2,
144 MAP = 3,
145 };
146
147 // "Node" represents a node in the tree that holds the input of
148 // DefaultValueObjectWriter.
149 class PROTOBUF_EXPORT Node {
150 public:
151 Node(const std::string& name, const google::protobuf::Type* type,
152 NodeKind kind, const DataPiece& data, bool is_placeholder,
153 const std::vector<std::string>& path, bool suppress_empty_list,
154 bool preserve_proto_field_names, bool use_ints_for_enums,
155 FieldScrubCallBack field_scrub_callback);
156 virtual ~Node() {
157 for (int i = 0; i < children_.size(); ++i) {
158 delete children_[i];
159 }
160 }
161
162 // Adds a child to this node. Takes ownership of this child.
163 void AddChild(Node* child) { children_.push_back(x: child); }
164
165 // Finds the child given its name.
166 Node* FindChild(StringPiece name);
167
168 // Populates children of this Node based on its type. If there are already
169 // children created, they will be merged to the result. Caller should pass
170 // in TypeInfo for looking up types of the children.
171 virtual void PopulateChildren(const TypeInfo* typeinfo);
172
173 // If this node is a leaf (has data), writes the current node to the
174 // ObjectWriter; if not, then recursively writes the children to the
175 // ObjectWriter.
176 virtual void WriteTo(ObjectWriter* ow);
177
178 // Accessors
179 const std::string& name() const { return name_; }
180
181 const std::vector<std::string>& path() const { return path_; }
182
183 const google::protobuf::Type* type() const { return type_; }
184
185 void set_type(const google::protobuf::Type* type) { type_ = type; }
186
187 NodeKind kind() const { return kind_; }
188
189 int number_of_children() const { return children_.size(); }
190
191 void set_data(const DataPiece& data) { data_ = data; }
192
193 bool is_any() const { return is_any_; }
194
195 void set_is_any(bool is_any) { is_any_ = is_any; }
196
197 void set_is_placeholder(bool is_placeholder) {
198 is_placeholder_ = is_placeholder;
199 }
200
201 protected:
202 // Returns the Value Type of a map given the Type of the map entry and a
203 // TypeInfo instance.
204 const google::protobuf::Type* GetMapValueType(
205 const google::protobuf::Type& found_type, const TypeInfo* typeinfo);
206
207 // Calls WriteTo() on every child in children_.
208 void WriteChildren(ObjectWriter* ow);
209
210 // The name of this node.
211 std::string name_;
212 // google::protobuf::Type of this node. Owned by TypeInfo.
213 const google::protobuf::Type* type_;
214 // The kind of this node.
215 NodeKind kind_;
216 // Whether this is a node for "Any".
217 bool is_any_;
218 // The data of this node when it is a leaf node.
219 DataPiece data_;
220 // Children of this node.
221 std::vector<Node*> children_;
222 // Whether this node is a placeholder for an object or list automatically
223 // generated when creating the parent node. Should be set to false after
224 // the parent node's StartObject()/StartList() method is called with this
225 // node's name.
226 bool is_placeholder_;
227
228 // Path of the field of this node
229 std::vector<std::string> path_;
230
231 // Whether to suppress empty list output.
232 bool suppress_empty_list_;
233
234 // Whether to preserve original proto field names
235 bool preserve_proto_field_names_;
236
237 // Whether to always print enums as ints
238 bool use_ints_for_enums_;
239
240 // Function for determining whether a field needs to be scrubbed or not.
241 FieldScrubCallBack field_scrub_callback_;
242
243 private:
244 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(Node);
245 };
246
247 // Creates a new Node and returns it. Caller owns memory of returned object.
248 virtual Node* CreateNewNode(const std::string& name,
249 const google::protobuf::Type* type, NodeKind kind,
250 const DataPiece& data, bool is_placeholder,
251 const std::vector<std::string>& path,
252 bool suppress_empty_list,
253 bool preserve_proto_field_names,
254 bool use_ints_for_enums,
255 FieldScrubCallBack field_scrub_callback);
256
257 // Creates a DataPiece containing the default value of the type of the field.
258 static DataPiece CreateDefaultDataPieceForField(
259 const google::protobuf::Field& field, const TypeInfo* typeinfo) {
260 return CreateDefaultDataPieceForField(field, typeinfo, use_ints_for_enums: false);
261 }
262
263 // Same as the above but with a flag to use ints instead of enum names.
264 static DataPiece CreateDefaultDataPieceForField(
265 const google::protobuf::Field& field, const TypeInfo* typeinfo,
266 bool use_ints_for_enums);
267
268 protected:
269 // Returns a pointer to current Node in tree.
270 Node* current() { return current_; }
271
272 private:
273 // Populates children of "node" if it is an "any" Node and its real type has
274 // been given.
275 void MaybePopulateChildrenOfAny(Node* node);
276
277 // Writes the root_ node to ow_ and resets the root_ and current_ pointer to
278 // nullptr.
279 void WriteRoot();
280
281 // Adds or replaces the data_ of a primitive child node.
282 void RenderDataPiece(StringPiece name, const DataPiece& data);
283
284 // Returns the default enum value as a DataPiece, or the first enum value if
285 // there is no default. For proto3, where we cannot specify an explicit
286 // default, a zero value will always be returned.
287 static DataPiece FindEnumDefault(const google::protobuf::Field& field,
288 const TypeInfo* typeinfo,
289 bool use_ints_for_enums);
290
291 // Type information for all the types used in the descriptor. Used to find
292 // google::protobuf::Type of nested messages/enums.
293 const TypeInfo* typeinfo_;
294 // Whether the TypeInfo object is owned by this class.
295 bool own_typeinfo_;
296 // google::protobuf::Type of the root message type.
297 const google::protobuf::Type& type_;
298 // Holds copies of strings passed to RenderString.
299 std::vector<std::unique_ptr<std::string>> string_values_;
300
301 // The current Node. Owned by its parents.
302 Node* current_;
303 // The root Node.
304 std::unique_ptr<Node> root_;
305 // The stack to hold the path of Nodes from current_ to root_;
306 std::stack<Node*> stack_;
307
308 // Whether to suppress output of empty lists.
309 bool suppress_empty_list_;
310
311 // Whether to preserve original proto field names
312 bool preserve_proto_field_names_;
313
314 // Whether to always print enums as ints
315 bool use_ints_for_enums_;
316
317 // Function for determining whether a field needs to be scrubbed or not.
318 FieldScrubCallBack field_scrub_callback_;
319
320 ObjectWriter* ow_;
321
322 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(DefaultValueObjectWriter);
323};
324
325} // namespace converter
326} // namespace util
327} // namespace protobuf
328} // namespace google
329
330#include <google/protobuf/port_undef.inc>
331
332#endif // GOOGLE_PROTOBUF_UTIL_INTERNAL_DEFAULT_VALUE_OBJECTWRITER_H__
333