0
# Content Generation
1

2
The X-Content library provides both high-level fluent builders and low-level streaming generators for creating structured content in multiple formats (JSON, YAML, CBOR, SMILE).
3

4
## Capabilities
5

6
### XContentFactory Methods
7

8
Central factory methods for creating content builders for different formats.
9

10
```java { .api }
11
/**
12
 * Creates a JSON content builder
13
 * @return XContentBuilder configured for JSON output
14
 */
15
public static XContentBuilder jsonBuilder() throws IOException;
16

17
/**
18
 * Creates a JSON content builder with specific output stream
19
 * @param os the output stream to write to
20
 * @return XContentBuilder configured for JSON output
21
 */
22
public static XContentBuilder jsonBuilder(OutputStream os) throws IOException;
23

24
/**
25
 * Creates a SMILE content builder (binary JSON format)
26
 * @return XContentBuilder configured for SMILE output
27
 */
28
public static XContentBuilder smileBuilder() throws IOException;
29

30
/**
31
 * Creates a YAML content builder
32
 * @return XContentBuilder configured for YAML output
33
 */
34
public static XContentBuilder yamlBuilder() throws IOException;
35

36
/**
37
 * Creates a CBOR content builder
38
 * @return XContentBuilder configured for CBOR output
39
 */
40
public static XContentBuilder cborBuilder() throws IOException;
41

42
/**
43
 * Creates a content builder for the specified type
44
 * @param type the content type to create builder for
45
 * @return XContentBuilder configured for the specified type
46
 */
47
public static XContentBuilder contentBuilder(XContentType type) throws IOException;
48

49
/**
50
 * Gets the XContent instance for the specified type
51
 * @param type the content type
52
 * @return XContent instance for the type
53
 */
54
public static XContent xContent(XContentType type);
55
```
56

57
### XContentBuilder
58

59
High-level fluent builder for creating structured content with method chaining.
60

61
```java { .api }
62
public final class XContentBuilder implements Closeable, Flushable {
63
    
64
    /**
65
     * Start a new object in the content
66
     * @return this builder for chaining
67
     */
68
    public XContentBuilder startObject() throws IOException;
69
    
70
    /**
71
     * Start a new object with a field name
72
     * @param name the field name for the object
73
     * @return this builder for chaining
74
     */
75
    public XContentBuilder startObject(String name) throws IOException;
76
    
77
    /**
78
     * End the current object
79
     * @return this builder for chaining
80
     */
81
    public XContentBuilder endObject() throws IOException;
82
    
83
    /**
84
     * Start a new array in the content
85
     * @return this builder for chaining
86
     */
87
    public XContentBuilder startArray() throws IOException;
88
    
89
    /**
90
     * Start a new array with a field name
91
     * @param name the field name for the array
92
     * @return this builder for chaining
93
     */
94
    public XContentBuilder startArray(String name) throws IOException;
95
    
96
    /**
97
     * End the current array
98
     * @return this builder for chaining
99
     */
100
    public XContentBuilder endArray() throws IOException;
101
    
102
    /**
103
     * Write a field name
104
     * @param name the field name
105
     * @return this builder for chaining
106
     */
107
    public XContentBuilder field(String name) throws IOException;
108
    
109
    /**
110
     * Write a string value
111
     * @param value the string value
112
     * @return this builder for chaining
113
     */
114
    public XContentBuilder value(String value) throws IOException;
115
    
116
    /**
117
     * Write an integer value
118
     * @param value the integer value
119
     * @return this builder for chaining
120
     */
121
    public XContentBuilder value(int value) throws IOException;
122
    
123
    /**
124
     * Write a long value
125
     * @param value the long value
126
     * @return this builder for chaining
127
     */
128
    public XContentBuilder value(long value) throws IOException;
129
    
130
    /**
131
     * Write a double value
132
     * @param value the double value
133
     * @return this builder for chaining
134
     */
135
    public XContentBuilder value(double value) throws IOException;
136
    
137
    /**
138
     * Write a boolean value
139
     * @param value the boolean value
140
     * @return this builder for chaining
141
     */
142
    public XContentBuilder value(boolean value) throws IOException;
143
    
144
    /**
145
     * Write a binary value (byte array)
146
     * @param value the byte array
147
     * @return this builder for chaining
148
     */
149
    public XContentBuilder value(byte[] value) throws IOException;
150
    
151
    /**
152
     * Write a null value
153
     * @return this builder for chaining
154
     */
155
    public XContentBuilder nullValue() throws IOException;
156
    
157
    /**
158
     * Write a field with a string value
159
     * @param name the field name
160
     * @param value the string value
161
     * @return this builder for chaining
162
     */
163
    public XContentBuilder field(String name, String value) throws IOException;
164
    
165
    /**
166
     * Write a field with an integer value
167
     * @param name the field name
168
     * @param value the integer value
169
     * @return this builder for chaining
170
     */
171
    public XContentBuilder field(String name, int value) throws IOException;
172
    
173
    /**
174
     * Write a field with a long value
175
     * @param name the field name
176
     * @param value the long value
177
     * @return this builder for chaining
178
     */
179
    public XContentBuilder field(String name, long value) throws IOException;
180
    
181
    /**
182
     * Write a field with a double value
183
     * @param name the field name
184
     * @param value the double value
185
     * @return this builder for chaining
186
     */
187
    public XContentBuilder field(String name, double value) throws IOException;
188
    
189
    /**
190
     * Write a field with a boolean value
191
     * @param name the field name
192
     * @param value the boolean value
193
     * @return this builder for chaining
194
     */
195
    public XContentBuilder field(String name, boolean value) throws IOException;
196
    
197
    /**
198
     * Write a field with a binary value
199
     * @param name the field name
200
     * @param value the byte array
201
     * @return this builder for chaining
202
     */
203
    public XContentBuilder field(String name, byte[] value) throws IOException;
204
    
205
    /**
206
     * Write a null field
207
     * @param name the field name
208
     * @return this builder for chaining
209
     */
210
    public XContentBuilder nullField(String name) throws IOException;
211
    
212
    /**
213
     * Write a field with any object value (uses ToXContent if available)
214
     * @param name the field name
215
     * @param value the object value
216
     * @return this builder for chaining
217
     */
218
    public XContentBuilder field(String name, Object value) throws IOException;
219
    
220
    /**
221
     * Write raw content from an input stream
222
     * @param name the field name
223
     * @param value the input stream containing raw content
224
     * @param contentType the type of the raw content
225
     * @return this builder for chaining
226
     */
227
    public XContentBuilder rawField(String name, InputStream value, XContentType contentType) throws IOException;
228
    
229
    /**
230
     * Get the string representation of the built content
231
     * @return string representation of the content
232
     */
233
    public String toString();
234
    
235
    /**
236
     * Get the content as a byte array
237
     * @return byte array representation of the content
238
     */
239
    public byte[] bytes();
240
}
241
```
242

243
### XContentGenerator
244

245
Low-level streaming interface for generating content with fine-grained control.
246

247
```java { .api }
248
public interface XContentGenerator extends Closeable, Flushable {
249
    
250
    /**
251
     * Get the content type this generator produces
252
     * @return the content type
253
     */
254
    XContentType contentType();
255
    
256
    /**
257
     * Enable pretty printing for human-readable output
258
     */
259
    void usePrettyPrint();
260
    
261
    /**
262
     * Check if pretty printing is enabled
263
     * @return true if pretty printing is enabled
264
     */
265
    boolean isPrettyPrint();
266
    
267
    /**
268
     * Enable line feed at the end of output
269
     */
270
    void usePrintLineFeedAtEnd();
271
    
272
    /**
273
     * Write the start of an object
274
     */
275
    void writeStartObject() throws IOException;
276
    
277
    /**
278
     * Write the end of an object
279
     */
280
    void writeEndObject() throws IOException;
281
    
282
    /**
283
     * Write the start of an array
284
     */
285
    void writeStartArray() throws IOException;
286
    
287
    /**
288
     * Write the end of an array
289
     */
290
    void writeEndArray() throws IOException;
291
    
292
    /**
293
     * Write a field name
294
     * @param name the field name
295
     */
296
    void writeFieldName(String name) throws IOException;
297
    
298
    /**
299
     * Write a null value
300
     */
301
    void writeNull() throws IOException;
302
    
303
    /**
304
     * Write a null field
305
     * @param name the field name
306
     */
307
    void writeNullField(String name) throws IOException;
308
    
309
    /**
310
     * Write a boolean field
311
     * @param name the field name
312
     * @param value the boolean value
313
     */
314
    void writeBooleanField(String name, boolean value) throws IOException;
315
    
316
    /**
317
     * Write a boolean value
318
     * @param value the boolean value
319
     */
320
    void writeBoolean(boolean value) throws IOException;
321
    
322
    /**
323
     * Write a number field (double)
324
     * @param name the field name
325
     * @param value the double value
326
     */
327
    void writeNumberField(String name, double value) throws IOException;
328
    
329
    /**
330
     * Write a number field (int)
331
     * @param name the field name
332
     * @param value the integer value
333
     */
334
    void writeNumberField(String name, int value) throws IOException;
335
    
336
    /**
337
     * Write a number field (long)
338
     * @param name the field name
339
     * @param value the long value
340
     */
341
    void writeNumberField(String name, long value) throws IOException;
342
    
343
    /**
344
     * Write a string field
345
     * @param name the field name
346
     * @param value the string value
347
     */
348
    void writeStringField(String name, String value) throws IOException;
349
    
350
    /**
351
     * Write a string value
352
     * @param value the string value
353
     */
354
    void writeString(String value) throws IOException;
355
    
356
    /**
357
     * Write a binary field
358
     * @param name the field name
359
     * @param value the byte array
360
     */
361
    void writeBinaryField(String name, byte[] value) throws IOException;
362
    
363
    /**
364
     * Write a binary value
365
     * @param value the byte array
366
     */
367
    void writeBinary(byte[] value) throws IOException;
368
    
369
    /**
370
     * Write raw content from an input stream
371
     * @param name the field name
372
     * @param value the input stream
373
     * @param contentType the content type
374
     */
375
    void writeRawField(String name, InputStream value, XContentType contentType) throws IOException;
376
    
377
    /**
378
     * Copy the current structure from a parser
379
     * @param parser the parser to copy from
380
     */
381
    void copyCurrentStructure(XContentParser parser) throws IOException;
382
}
383
```
384

385
**Usage Examples:**
386

387
```java
388
import org.elasticsearch.xcontent.*;
389
import static org.elasticsearch.xcontent.XContentFactory.*;
390

391
// Basic object creation
392
XContentBuilder builder = jsonBuilder()
393
    .startObject()
394
        .field("name", "John Doe")
395
        .field("age", 30)
396
        .field("active", true)
397
        .nullField("nickname")
398
    .endObject();
399

400
// Array creation
401
XContentBuilder arrayBuilder = jsonBuilder()
402
    .startObject()
403
        .field("user", "john")
404
        .startArray("roles")
405
            .value("admin")
406
            .value("editor")
407
        .endArray()
408
    .endObject();
409

410
// Nested objects
411
XContentBuilder nestedBuilder = jsonBuilder()
412
    .startObject()
413
        .field("name", "John")
414
        .startObject("address")
415
            .field("street", "123 Main St")
416
            .field("city", "New York")
417
        .endObject()
418
    .endObject();
419

420
// Complex data structure
421
XContentBuilder complexBuilder = jsonBuilder()
422
    .startObject()
423
        .field("timestamp", System.currentTimeMillis())
424
        .startObject("user")
425
            .field("id", 123)
426
            .field("email", "john@example.com")
427
            .startArray("preferences")
428
                .startObject()
429
                    .field("key", "theme")
430
                    .field("value", "dark")
431
                .endObject()
432
            .endArray()
433
        .endObject()
434
    .endObject();
435

436
// Different formats
437
XContentBuilder yamlBuilder = yamlBuilder()
438
    .startObject()
439
        .field("message", "Hello World")
440
    .endObject();
441

442
XContentBuilder smileBuilder = smileBuilder()  // Binary format
443
    .startObject()
444
        .field("data", "compressed")
445
    .endObject();
446
```
447

448
### Builder Extensions
449

450
```java { .api }
451
public interface XContentBuilderExtension {
452
    /**
453
     * Write custom content to the builder
454
     * @param builder the builder to write to
455
     * @param params parameters for the operation
456
     */
457
    void writeTo(XContentBuilder builder, ToXContent.Params params) throws IOException;
458
}
459

460
public interface Writer {
461
    /**
462
     * Write a value to the generator
463
     * @param generator the generator to write to
464
     * @param value the value to write
465
     */
466
    void write(XContentGenerator generator, Object value) throws IOException;
467
}
468
```