0
# Structured Data Utilities
1

2
Factory methods for creating google.protobuf.Struct and google.protobuf.Value messages with type-safe builders for various data types. These utilities simplify the creation of structured data that can represent JSON-like objects and values in protobuf messages.
3

4
## Capabilities
5

6
### Struct Creation
7

8
Factory methods for creating Struct messages with key-value pairs.
9

10
```java { .api }
11
/**
12
 * Returns a Struct containing the single key-value pair.
13
 * 
14
 * @param k1 Key for the first field
15
 * @param v1 Value for the first field
16
 * @return Struct containing the specified key-value pair
17
 */
18
public static Struct of(String k1, Value v1);
19

20
/**
21
 * Returns a Struct containing the two key-value pairs.
22
 * Providing duplicate keys results in undefined behavior.
23
 * 
24
 * @param k1 Key for the first field
25
 * @param v1 Value for the first field
26
 * @param k2 Key for the second field
27
 * @param v2 Value for the second field
28
 * @return Struct containing the specified key-value pairs
29
 */
30
public static Struct of(String k1, Value v1, String k2, Value v2);
31

32
/**
33
 * Returns a Struct containing the three key-value pairs.
34
 * Providing duplicate keys results in undefined behavior.
35
 * 
36
 * @param k1 Key for the first field
37
 * @param v1 Value for the first field
38
 * @param k2 Key for the second field
39
 * @param v2 Value for the second field
40
 * @param k3 Key for the third field
41
 * @param v3 Value for the third field
42
 * @return Struct containing the specified key-value pairs
43
 */
44
public static Struct of(String k1, Value v1, String k2, Value v2, String k3, Value v3);
45
```
46

47
### Value Creation - Null and Primitives
48

49
Factory methods for creating Value messages from primitive types and null.
50

51
```java { .api }
52
/**
53
 * Returns a Value representing null.
54
 * 
55
 * @return Value with null_value set
56
 */
57
public static Value ofNull();
58

59
/**
60
 * Returns a Value with boolean value.
61
 * 
62
 * @param value Boolean value to wrap
63
 * @return Value with bool_value set to the specified boolean
64
 */
65
public static Value of(boolean value);
66

67
/**
68
 * Returns a Value with number value.
69
 * 
70
 * @param value Double value to wrap
71
 * @return Value with number_value set to the specified double
72
 */
73
public static Value of(double value);
74

75
/**
76
 * Returns a Value with string value.
77
 * 
78
 * @param value String value to wrap
79
 * @return Value with string_value set to the specified string
80
 */
81
public static Value of(String value);
82
```
83

84
### Value Creation - Complex Types
85

86
Factory methods for creating Value messages from complex protobuf types.
87

88
```java { .api }
89
/**
90
 * Returns a Value with struct value.
91
 * 
92
 * @param value Struct to wrap
93
 * @return Value with struct_value set to the specified Struct
94
 */
95
public static Value of(Struct value);
96

97
/**
98
 * Returns a Value with list value.
99
 * 
100
 * @param value ListValue to wrap
101
 * @return Value with list_value set to the specified ListValue
102
 */
103
public static Value of(ListValue value);
104

105
/**
106
 * Returns a Value with ListValue created from the iterable.
107
 * Creates a ListValue by appending all elements from the iterable.
108
 * 
109
 * @param values Iterable of Value objects to include in the list
110
 * @return Value with list_value containing all specified values
111
 */
112
public static Value of(Iterable<Value> values);
113
```
114

115

116
**Usage Examples:**
117

118
```java
119
import com.google.protobuf.util.Structs;
120
import com.google.protobuf.util.Values;
121
import com.google.protobuf.Struct;
122
import com.google.protobuf.Value;
123
import com.google.protobuf.ListValue;
124
import java.util.Arrays;
125

126
// Create simple Value objects
127
Value nullValue = Values.ofNull();
128
Value boolValue = Values.of(true);
129
Value numberValue = Values.of(42.5);
130
Value stringValue = Values.of("hello world");
131

132
// Create a simple Struct with one field
133
Struct simpleStruct = Structs.of("name", Values.of("Alice"));
134

135
// Create Struct with multiple fields
136
Struct userStruct = Structs.of(
137
    "name", Values.of("Bob"),
138
    "age", Values.of(30),
139
    "active", Values.of(true)
140
);
141

142
// Create more complex nested structures
143
Value addressValue = Values.of(Structs.of(
144
    "street", Values.of("123 Main St"),
145
    "city", Values.of("Anytown"),
146
    "zipcode", Values.of("12345")
147
));
148

149
Struct complexStruct = Structs.of(
150
    "user", Values.of(userStruct),
151
    "address", addressValue,
152
    "tags", Values.of(Arrays.asList(
153
        Values.of("premium"),
154
        Values.of("verified"),
155
        Values.of("new")
156
    ))
157
);
158

159
// Create ListValue and wrap in Value
160
ListValue numberList = ListValue.newBuilder()
161
    .addValues(Values.of(1))
162
    .addValues(Values.of(2))
163
    .addValues(Values.of(3))
164
    .build();
165
Value listValue = Values.of(numberList);
166

167
// Create Value from iterable
168
Value iterableValue = Values.of(Arrays.asList(
169
    Values.of("first"),
170
    Values.of("second"),
171
    Values.of("third")
172
));
173

174

175
// Building complex JSON-like structures
176
Struct apiResponse = Structs.of(
177
    "success", Values.of(true),
178
    "data", Values.of(Structs.of(
179
        "users", Values.of(Arrays.asList(
180
            Values.of(Structs.of("id", Values.of(1), "name", Values.of("Alice"))),
181
            Values.of(Structs.of("id", Values.of(2), "name", Values.of("Bob")))
182
        )),
183
        "total", Values.of(2)
184
    )),
185
    "metadata", Values.of(Structs.of(
186
        "timestamp", Values.of("2024-01-15T10:30:00Z"),
187
        "version", Values.of("1.0.0")
188
    ))
189
);
190

191
// Convert to JSON using JsonFormat for verification
192
// This demonstrates interoperability with JSON utilities
193
import com.google.protobuf.util.JsonFormat;
194

195
try {
196
    String jsonString = JsonFormat.printer().print(complexStruct);
197
    System.out.println("Struct as JSON: " + jsonString);
198
} catch (Exception e) {
199
    System.err.println("JSON conversion error: " + e.getMessage());
200
}
201
```
202

203
## Integration with JSON Format
204

205
These structured data utilities work seamlessly with the JsonFormat utilities to create protobuf messages that can be easily converted to and from JSON:
206

207
```java
208
import com.google.protobuf.util.JsonFormat;
209
import com.google.protobuf.util.Structs;
210
import com.google.protobuf.util.Values;
211

212
// Create structured data
213
Struct data = Structs.of(
214
    "message", Values.of("Hello, world!"),
215
    "priority", Values.of(1),
216
    "enabled", Values.of(true),
217
    "metadata", Values.of(Structs.of(
218
        "source", Values.of("api"),
219
        "timestamp", Values.of("2024-01-15T10:30:00Z")
220
    ))
221
);
222

223
// Convert to JSON
224
JsonFormat.Printer printer = JsonFormat.printer();
225
String json = printer.print(data);
226

227
// Parse back from JSON
228
JsonFormat.Parser parser = JsonFormat.parser();
229
Struct.Builder builder = Struct.newBuilder();
230
parser.merge(json, builder);
231
Struct parsed = builder.build();
232
```