0
# Elasticsearch X-Content
1
2
Elasticsearch X-Content is a comprehensive content processing library that provides abstractions for parsing and generating various content formats including JSON, YAML, CBOR, and Smile. It offers a generic abstraction layer for content handling with support for pull parsing, filtering, and streaming operations across different serialization formats.
3
4
## Package Information
5
6
- **Package Name**: org.elasticsearch:elasticsearch-x-content
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven dependencies:
10
11
```xml
12
<dependency>
13
<groupId>org.elasticsearch</groupId>
14
<artifactId>elasticsearch-x-content</artifactId>
15
<version>8.18.3</version>
16
</dependency>
17
```
18
19
## Core Imports
20
21
```java
22
import org.elasticsearch.xcontent.*;
23
import static org.elasticsearch.xcontent.XContentFactory.*;
24
```
25
26
## Basic Usage
27
28
```java
29
import org.elasticsearch.xcontent.*;
30
import static org.elasticsearch.xcontent.XContentFactory.*;
31
32
// Creating and writing content
33
XContentBuilder builder = jsonBuilder()
34
.startObject()
35
.field("name", "John Doe")
36
.field("age", 30)
37
.startArray("skills")
38
.value("Java")
39
.value("Elasticsearch")
40
.endArray()
41
.endObject();
42
43
String jsonString = builder.toString();
44
45
// Parsing content
46
XContentParser parser = XContentType.JSON.xContent()
47
.createParser(XContentParserConfiguration.EMPTY, jsonString);
48
49
// Navigate through the parsed content
50
while (parser.nextToken() != null) {
51
if (parser.currentToken() == XContentParser.Token.FIELD_NAME) {
52
String fieldName = parser.currentName();
53
parser.nextToken();
54
Object value = parser.objectText();
55
System.out.println(fieldName + ": " + value);
56
}
57
}
58
parser.close();
59
```
60
61
## Architecture
62
63
The X-Content library is built around several key components:
64
65
- **Content Abstraction**: `XContent` interface provides format-agnostic content handling
66
- **Streaming Parsers**: `XContentParser` offers pull-parsing for efficient, memory-conscious processing
67
- **Streaming Generators**: `XContentGenerator` and `XContentBuilder` enable fluent content creation
68
- **Object Mapping Framework**: Declarative parsers (`ObjectParser`, `ConstructingObjectParser`) for structured data binding
69
- **Format Support**: Pluggable implementations for JSON, YAML, SMILE, and CBOR
70
- **Advanced Features**: Content filtering, deprecation handling, named object registries
71
72
## Capabilities
73
74
### Content Generation
75
76
High-level fluent builders and low-level streaming generators for creating structured content in multiple formats.
77
78
```java { .api }
79
public static XContentBuilder jsonBuilder() throws IOException;
80
public static XContentBuilder yamlBuilder() throws IOException;
81
public static XContentBuilder smileBuilder() throws IOException;
82
public static XContentBuilder cborBuilder() throws IOException;
83
84
public interface XContentGenerator extends Closeable, Flushable {
85
void writeStartObject() throws IOException;
86
void writeEndObject() throws IOException;
87
void writeFieldName(String name) throws IOException;
88
void writeString(String value) throws IOException;
89
void writeNumber(int value) throws IOException;
90
}
91
```
92
93
[Content Generation](./content-generation.md)
94
95
### Content Parsing
96
97
Pull-parsing approach for efficiently reading and navigating structured content with support for streaming operations.
98
99
```java { .api }
100
public interface XContentParser extends Closeable {
101
Token nextToken() throws IOException;
102
Token currentToken();
103
String currentName() throws IOException;
104
String text() throws IOException;
105
int intValue() throws IOException;
106
Map<String, Object> map() throws IOException;
107
}
108
109
enum Token {
110
START_OBJECT, END_OBJECT, START_ARRAY, END_ARRAY,
111
FIELD_NAME, VALUE_STRING, VALUE_NUMBER, VALUE_BOOLEAN, VALUE_NULL
112
}
113
```
114
115
[Content Parsing](./content-parsing.md)
116
117
### Object Mapping Framework
118
119
Declarative, type-safe parsers for converting structured content directly into Java objects with support for constructor-based and setter-based object creation.
120
121
```java { .api }
122
public final class ObjectParser<Value, Context> {
123
public ObjectParser(String name, Supplier<Value> valueSupplier);
124
public void declareString(BiConsumer<Value, String> consumer, ParseField field);
125
public void declareObject(BiConsumer<Value, T> consumer,
126
ContextParser<Context, T> parser, ParseField field);
127
public Value parse(XContentParser parser, Context context) throws IOException;
128
}
129
130
public final class ConstructingObjectParser<Value, Context> {
131
public ConstructingObjectParser(String name,
132
BiFunction<Object[], Context, Value> builder);
133
}
134
```
135
136
[Object Mapping](./object-mapping.md)
137
138
### Content Types and Factory
139
140
Central factory and type system for working with different content formats (JSON, YAML, CBOR, SMILE).
141
142
```java { .api }
143
public enum XContentType implements MediaType {
144
JSON, YAML, CBOR, SMILE;
145
146
public XContent xContent();
147
public static XContentType fromMediaType(String mediaTypeHeaderValue);
148
}
149
150
public interface XContent {
151
XContentType type();
152
XContentParser createParser(XContentParserConfiguration config, String content);
153
XContentGenerator createGenerator(OutputStream os);
154
}
155
```
156
157
[Content Types](./content-types.md)
158
159
### Configuration and Registry
160
161
Configuration system for parsers including named object registries, deprecation handling, and API versioning support.
162
163
```java { .api }
164
public interface XContentParserConfiguration {
165
XContentParserConfiguration withRegistry(NamedXContentRegistry registry);
166
XContentParserConfiguration withDeprecationHandler(DeprecationHandler handler);
167
168
static final XContentParserConfiguration EMPTY = ...;
169
}
170
171
public class NamedXContentRegistry {
172
public <T, C> T parseNamedObject(Class<T> categoryClass, String name,
173
XContentParser parser, C context);
174
175
static final NamedXContentRegistry EMPTY = ...;
176
}
177
```
178
179
[Configuration and Registry](./configuration.md)
180
181
## Types
182
183
### Core Interfaces
184
185
```java { .api }
186
public interface ToXContent {
187
XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException;
188
189
interface Params {
190
String param(String key);
191
}
192
}
193
194
public interface ToXContentObject extends ToXContent {
195
default boolean isFragment() { return false; }
196
}
197
198
public interface ToXContentFragment extends ToXContent {
199
default boolean isFragment() { return true; }
200
}
201
```
202
203
### Field Handling
204
205
```java { .api }
206
public class ParseField {
207
public ParseField(String name, String... deprecatedNames);
208
public String getPreferredName();
209
public boolean match(String fieldName, DeprecationHandler handler);
210
}
211
212
@FunctionalInterface
213
public interface ContextParser<Context, T> {
214
T parse(XContentParser parser, Context context) throws IOException;
215
}
216
```
217
218
### Exception Types
219
220
```java { .api }
221
public class XContentParseException extends RuntimeException {
222
public XContentParseException(String message);
223
public XContentParseException(XContentLocation location, String message);
224
}
225
226
public class NamedObjectNotFoundException extends RuntimeException {
227
public NamedObjectNotFoundException(String message);
228
}
229
230
public class XContentGenerationException extends RuntimeException {
231
public XContentGenerationException(String message);
232
}
233
```