0
# Content Types and Factory
1

2
The X-Content library provides a unified type system and factory for working with different content formats including JSON, YAML, CBOR, and SMILE with consistent APIs across all formats.
3

4
## Capabilities
5

6
### XContentType Enumeration
7

8
Central enumeration defining all supported content types and their properties.
9

10
```java { .api }
11
/**
12
 * Enumeration of supported content types
13
 */
14
public enum XContentType implements MediaType {
15
    
16
    /**
17
     * Standard JSON format
18
     */
19
    JSON {
20
        @Override
21
        public String mediaTypeWithoutParameters() { return "application/json"; }
22
        
23
        @Override
24
        public String mediaType() { return "application/json;charset=utf-8"; }
25
        
26
        @Override
27
        public String queryParameter() { return "json"; }
28
        
29
        @Override
30
        public Set<HeaderValue> headerValues() {
31
            return Set.of(new HeaderValue("application/json"), 
32
                         new HeaderValue("application/x-ndjson"), 
33
                         new HeaderValue("application/*"));
34
        }
35
    },
36
    
37
    /**
38
     * SMILE binary JSON format (fast and compact)
39
     */
40
    SMILE {
41
        @Override
42
        public String mediaTypeWithoutParameters() { return "application/smile"; }
43
        
44
        @Override
45
        public String mediaType() { return "application/smile"; }
46
        
47
        @Override
48
        public String queryParameter() { return "smile"; }
49
        
50
        @Override
51
        public Set<HeaderValue> headerValues() {
52
            return Set.of(new HeaderValue("application/smile"));
53
        }
54
    },
55
    
56
    /**
57
     * YAML format
58
     */
59
    YAML {
60
        @Override
61
        public String mediaTypeWithoutParameters() { return "application/yaml"; }
62
        
63
        @Override
64
        public String mediaType() { return "application/yaml"; }
65
        
66
        @Override
67
        public String queryParameter() { return "yaml"; }
68
        
69
        @Override
70
        public Set<HeaderValue> headerValues() {
71
            return Set.of(new HeaderValue("application/yaml"), 
72
                         new HeaderValue("text/yaml"));
73
        }
74
    },
75
    
76
    /**
77
     * CBOR (Concise Binary Object Representation) format
78
     */
79
    CBOR {
80
        @Override
81
        public String mediaTypeWithoutParameters() { return "application/cbor"; }
82
        
83
        @Override
84
        public String mediaType() { return "application/cbor"; }
85
        
86
        @Override
87
        public String queryParameter() { return "cbor"; }
88
        
89
        @Override
90
        public Set<HeaderValue> headerValues() {
91
            return Set.of(new HeaderValue("application/cbor"));
92
        }
93
    },
94
    
95
    /**
96
     * Versioned JSON format
97
     */
98
    VND_JSON,
99
    
100
    /**
101
     * Versioned SMILE format
102
     */
103
    VND_SMILE,
104
    
105
    /**
106
     * Versioned YAML format
107
     */
108
    VND_YAML,
109
    
110
    /**
111
     * Versioned CBOR format
112
     */
113
    VND_CBOR;
114
    
115
    /**
116
     * Parse content type from format string
117
     * @param format format string (e.g., "json", "yaml")
118
     * @return corresponding XContentType
119
     */
120
    public static XContentType fromFormat(String format);
121
    
122
    /**
123
     * Parse content type from HTTP media type header
124
     * @param mediaTypeHeaderValue media type header value
125
     * @return corresponding XContentType, or null if not recognized
126
     */
127
    public static XContentType fromMediaType(String mediaTypeHeaderValue);
128
    
129
    /**
130
     * Get the XContent instance for this type
131
     * @return XContent implementation for this type
132
     */
133
    public XContent xContent();
134
    
135
    /**
136
     * Get the canonical (non-versioned) type
137
     * @return canonical XContentType
138
     */
139
    public XContentType canonical();
140
    
141
    /**
142
     * Get media type without parameters
143
     * @return media type string
144
     */
145
    public abstract String mediaTypeWithoutParameters();
146
    
147
    /**
148
     * Get full media type with parameters
149
     * @return full media type string
150
     */
151
    public abstract String mediaType();
152
    
153
    /**
154
     * Get query parameter name for this type
155
     * @return query parameter string
156
     */
157
    public abstract String queryParameter();
158
    
159
    /**
160
     * Get acceptable header values for this type
161
     * @return set of acceptable header values
162
     */
163
    public abstract Set<HeaderValue> headerValues();
164
}
165
```
166

167
### XContent Interface
168

169
Abstract interface for content format implementations.
170

171
```java { .api }
172
/**
173
 * Generic abstraction for content handling inspired by JSON and pull parsing
174
 */
175
public interface XContent {
176
    
177
    /**
178
     * Get the type this content handles and produces
179
     * @return XContentType for this implementation
180
     */
181
    XContentType type();
182
    
183
    /**
184
     * Get the bulk separator byte for this format
185
     * @return bulk separator byte
186
     */
187
    byte bulkSeparator();
188
    
189
    /**
190
     * Detect if the given bytes represent this content type
191
     * @param bytes byte array to check
192
     * @param offset starting offset
193
     * @param length number of bytes to check  
194
     * @return true if bytes match this content type
195
     * @deprecated Use MediaTypeRegistry for content detection
196
     */
197
    @Deprecated
198
    boolean detectContent(byte[] bytes, int offset, int length);
199
    
200
    /**
201
     * Detect if the given character sequence represents this content type
202
     * @param chars character sequence to check
203
     * @return true if chars match this content type
204
     * @deprecated Use MediaTypeRegistry for content detection
205
     */
206
    @Deprecated  
207
    boolean detectContent(CharSequence chars);
208
    
209
    /**
210
     * Create a generator using the provided output stream
211
     * @param os output stream to write to
212
     * @return XContentGenerator for this format
213
     */
214
    default XContentGenerator createGenerator(OutputStream os) throws IOException {
215
        return createGenerator(os, Collections.emptySet(), Collections.emptySet());
216
    }
217
    
218
    /**
219
     * Create a generator with include/exclude filtering
220
     * @param os output stream to write to
221
     * @param includes field patterns to include (empty means include all)
222
     * @param excludes field patterns to exclude
223
     * @return XContentGenerator with filtering
224
     */
225
    XContentGenerator createGenerator(OutputStream os, Set<String> includes, Set<String> excludes) throws IOException;
226
    
227
    /**
228
     * Create parser from string content
229
     * @param config parser configuration
230
     * @param content string content to parse
231
     * @return XContentParser for this format
232
     */
233
    XContentParser createParser(XContentParserConfiguration config, String content) throws IOException;
234
    
235
    /**
236
     * Create parser from input stream
237
     * @param config parser configuration
238
     * @param is input stream to parse
239
     * @return XContentParser for this format
240
     */
241
    XContentParser createParser(XContentParserConfiguration config, InputStream is) throws IOException;
242
    
243
    /**
244
     * Create parser from byte array
245
     * @param config parser configuration
246
     * @param data byte array to parse
247
     * @return XContentParser for this format
248
     */
249
    default XContentParser createParser(XContentParserConfiguration config, byte[] data) throws IOException {
250
        return createParser(config, data, 0, data.length);
251
    }
252
    
253
    /**
254
     * Create parser from byte array with offset and length
255
     * @param config parser configuration
256
     * @param data byte array to parse
257
     * @param offset starting offset
258
     * @param length number of bytes to parse
259
     * @return XContentParser for this format
260
     */
261
    XContentParser createParser(XContentParserConfiguration config, byte[] data, int offset, int length) 
262
        throws IOException;
263
    
264
    /**
265
     * Create parser from Reader
266
     * @param config parser configuration
267
     * @param reader Reader to parse from
268
     * @return XContentParser for this format
269
     */
270
    XContentParser createParser(XContentParserConfiguration config, Reader reader) throws IOException;
271
}
272
```
273

274
### Format-Specific Implementations
275

276
Individual format implementations with their specific characteristics.
277

278
```java { .api }
279
/**
280
 * JSON format implementation
281
 */
282
public final class JsonXContent implements XContent {
283
    /**
284
     * Singleton JSON XContent instance
285
     */
286
    public static final XContent jsonXContent = new JsonXContent();
287
    
288
    /**
289
     * Create a JSON content builder
290
     * @return XContentBuilder for JSON
291
     */
292
    public static XContentBuilder contentBuilder() throws IOException;
293
}
294

295
/**
296
 * YAML format implementation  
297
 */
298
public final class YamlXContent implements XContent {
299
    /**
300
     * Singleton YAML XContent instance
301
     */
302
    public static final XContent yamlXContent = new YamlXContent();
303
    
304
    /**
305
     * Create a YAML content builder
306
     * @return XContentBuilder for YAML
307
     */
308
    public static XContentBuilder contentBuilder() throws IOException;
309
}
310

311
/**
312
 * SMILE binary format implementation
313
 */
314
public final class SmileXContent implements XContent {
315
    /**
316
     * Singleton SMILE XContent instance
317
     */
318
    public static final XContent smileXContent = new SmileXContent();
319
    
320
    /**
321
     * Create a SMILE content builder
322
     * @return XContentBuilder for SMILE
323
     */
324
    public static XContentBuilder contentBuilder() throws IOException;
325
}
326

327
/**
328
 * CBOR format implementation
329
 */
330
public final class CborXContent implements XContent {
331
    /**
332
     * Singleton CBOR XContent instance
333
     */
334
    public static final XContent cborXContent = new CborXContent();
335
    
336
    /**
337
     * Create a CBOR content builder
338
     * @return XContentBuilder for CBOR
339
     */
340
    public static XContentBuilder contentBuilder() throws IOException;
341
}
342
```
343

344
**Usage Examples:**
345

346
```java
347
import org.elasticsearch.xcontent.*;
348
import static org.elasticsearch.xcontent.XContentFactory.*;
349

350
// Working with different content types
351
XContentType jsonType = XContentType.JSON;
352
XContentType yamlType = XContentType.YAML;
353
XContentType smileType = XContentType.SMILE;
354
XContentType cborType = XContentType.CBOR;
355

356
// Get XContent instances
357
XContent jsonContent = jsonType.xContent();
358
XContent yamlContent = yamlType.xContent();
359

360
// Create builders for different formats
361
XContentBuilder jsonBuilder = jsonBuilder()
362
    .startObject()
363
        .field("message", "Hello JSON")
364
    .endObject();
365

366
XContentBuilder yamlBuilder = yamlBuilder()
367
    .startObject()
368
        .field("message", "Hello YAML")
369
    .endObject();
370

371
XContentBuilder smileBuilder = smileBuilder()  // Binary format
372
    .startObject()
373
        .field("message", "Hello SMILE")
374
    .endObject();
375

376
// Parse content in different formats
377
String jsonString = """{"name": "John", "age": 30}""";
378
XContentParser jsonParser = XContentType.JSON.xContent()
379
    .createParser(XContentParserConfiguration.EMPTY, jsonString);
380

381
String yamlString = """
382
name: John
383
age: 30
384
""";
385
XContentParser yamlParser = XContentType.YAML.xContent()
386
    .createParser(XContentParserConfiguration.EMPTY, yamlString);
387

388
// Content type detection from media type
389
XContentType detectedType = XContentType.fromMediaType("application/json");
390
assert detectedType == XContentType.JSON;
391

392
XContentType yamlDetected = XContentType.fromMediaType("application/yaml");
393
assert yamlDetected == XContentType.YAML;
394

395
// Content type from format string
396
XContentType fromFormat = XContentType.fromFormat("json");
397
assert fromFormat == XContentType.JSON;
398

399
// Get media type properties
400
String mediaType = XContentType.JSON.mediaType();  // "application/json;charset=utf-8"
401
String queryParam = XContentType.JSON.queryParameter();  // "json"
402
Set<MediaType.HeaderValue> headers = XContentType.JSON.headerValues();
403

404
// Working with canonical types
405
XContentType canonical = XContentType.VND_JSON.canonical();  // Returns JSON
406
```
407

408
### MediaType Interface
409

410
Base interface for media type handling.
411

412
```java { .api }
413
/**
414
 * Interface for HTTP media type support
415
 */
416
public interface MediaType {
417
    
418
    /**
419
     * Header value record for media type headers
420
     */
421
    public record HeaderValue(String value, Map<String, String> parameters) {
422
        /**
423
         * Simple header value without parameters
424
         * @param value the header value
425
         */
426
        public HeaderValue(String value) {
427
            this(value, Collections.emptyMap());
428
        }
429
    }
430
    
431
    /**
432
     * Get the query parameter name for this media type
433
     * @return query parameter string
434
     */
435
    String queryParameter();
436
    
437
    /**
438
     * Get acceptable header values for this media type
439
     * @return set of header values
440
     */
441
    Set<HeaderValue> headerValues();
442
}
443
```
444

445
### Content Detection and Registry
446

447
Media type detection and registry functionality.
448

449
```java { .api }
450
/**
451
 * Registry for media type detection and handling
452
 */
453
public class MediaTypeRegistry {
454
    
455
    /**
456
     * Parse media type from string
457
     * @param mediaType media type string
458
     * @return ParsedMediaType instance
459
     */
460
    public static ParsedMediaType parseMediaType(String mediaType);
461
    
462
    /**
463
     * Get content type from parsed media type
464
     * @param parsedMediaType parsed media type
465
     * @return corresponding XContentType, or null if not supported
466
     */
467
    public static XContentType fromParsedMediaType(ParsedMediaType parsedMediaType);
468
}
469

470
/**
471
 * Parsed representation of a media type
472
 */
473
public class ParsedMediaType {
474
    
475
    /**
476
     * Get the media type
477
     * @return media type string
478
     */
479
    public String mediaType();
480
    
481
    /**
482
     * Get media type parameters
483
     * @return map of parameters
484
     */
485
    public Map<String, String> parameters();
486
    
487
    /**
488
     * Get a specific parameter value
489
     * @param parameter parameter name
490
     * @return parameter value, or null if not present
491
     */
492
    public String parameter(String parameter);
493
}
494
```