or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcontent-generation.mdcontent-parsing.mdcontent-types.mdindex.mdobject-mapping.md
tile.json

tessl/maven-org-elasticsearch--elasticsearch-x-content

A content processing library for Elasticsearch that provides abstractions for parsing and generating various content formats including JSON, YAML, CBOR, and Smile.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.elasticsearch/elasticsearch-x-content@8.18.x

To install, run

npx @tessl/cli install tessl/maven-org-elasticsearch--elasticsearch-x-content@8.18.0

index.mddocs/

Elasticsearch X-Content

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.

Package Information

  • Package Name: org.elasticsearch:elasticsearch-x-content
  • Package Type: maven
  • Language: Java
  • Installation: Add to your Maven dependencies:
<dependency>
  <groupId>org.elasticsearch</groupId>
  <artifactId>elasticsearch-x-content</artifactId>
  <version>8.18.3</version>
</dependency>

Core Imports

import org.elasticsearch.xcontent.*;
import static org.elasticsearch.xcontent.XContentFactory.*;

Basic Usage

import org.elasticsearch.xcontent.*;
import static org.elasticsearch.xcontent.XContentFactory.*;

// Creating and writing content
XContentBuilder builder = jsonBuilder()
    .startObject()
        .field("name", "John Doe")
        .field("age", 30)
        .startArray("skills")
            .value("Java")
            .value("Elasticsearch")
        .endArray()
    .endObject();

String jsonString = builder.toString();

// Parsing content
XContentParser parser = XContentType.JSON.xContent()
    .createParser(XContentParserConfiguration.EMPTY, jsonString);

// Navigate through the parsed content
while (parser.nextToken() != null) {
    if (parser.currentToken() == XContentParser.Token.FIELD_NAME) {
        String fieldName = parser.currentName();
        parser.nextToken();
        Object value = parser.objectText();
        System.out.println(fieldName + ": " + value);
    }
}
parser.close();

Architecture

The X-Content library is built around several key components:

  • Content Abstraction: XContent interface provides format-agnostic content handling
  • Streaming Parsers: XContentParser offers pull-parsing for efficient, memory-conscious processing
  • Streaming Generators: XContentGenerator and XContentBuilder enable fluent content creation
  • Object Mapping Framework: Declarative parsers (ObjectParser, ConstructingObjectParser) for structured data binding
  • Format Support: Pluggable implementations for JSON, YAML, SMILE, and CBOR
  • Advanced Features: Content filtering, deprecation handling, named object registries

Capabilities

Content Generation

High-level fluent builders and low-level streaming generators for creating structured content in multiple formats.

public static XContentBuilder jsonBuilder() throws IOException;
public static XContentBuilder yamlBuilder() throws IOException;
public static XContentBuilder smileBuilder() throws IOException;
public static XContentBuilder cborBuilder() throws IOException;

public interface XContentGenerator extends Closeable, Flushable {
    void writeStartObject() throws IOException;
    void writeEndObject() throws IOException;
    void writeFieldName(String name) throws IOException;
    void writeString(String value) throws IOException;
    void writeNumber(int value) throws IOException;
}

Content Generation

Content Parsing

Pull-parsing approach for efficiently reading and navigating structured content with support for streaming operations.

public interface XContentParser extends Closeable {
    Token nextToken() throws IOException;
    Token currentToken();
    String currentName() throws IOException;
    String text() throws IOException;
    int intValue() throws IOException;
    Map<String, Object> map() throws IOException;
}

enum Token {
    START_OBJECT, END_OBJECT, START_ARRAY, END_ARRAY,
    FIELD_NAME, VALUE_STRING, VALUE_NUMBER, VALUE_BOOLEAN, VALUE_NULL
}

Content Parsing

Object Mapping Framework

Declarative, type-safe parsers for converting structured content directly into Java objects with support for constructor-based and setter-based object creation.

public final class ObjectParser<Value, Context> {
    public ObjectParser(String name, Supplier<Value> valueSupplier);
    public void declareString(BiConsumer<Value, String> consumer, ParseField field);
    public void declareObject(BiConsumer<Value, T> consumer, 
                             ContextParser<Context, T> parser, ParseField field);
    public Value parse(XContentParser parser, Context context) throws IOException;
}

public final class ConstructingObjectParser<Value, Context> {
    public ConstructingObjectParser(String name, 
                                   BiFunction<Object[], Context, Value> builder);
}

Object Mapping

Content Types and Factory

Central factory and type system for working with different content formats (JSON, YAML, CBOR, SMILE).

public enum XContentType implements MediaType {
    JSON, YAML, CBOR, SMILE;
    
    public XContent xContent();
    public static XContentType fromMediaType(String mediaTypeHeaderValue);
}

public interface XContent {
    XContentType type();
    XContentParser createParser(XContentParserConfiguration config, String content);
    XContentGenerator createGenerator(OutputStream os);
}

Content Types

Configuration and Registry

Configuration system for parsers including named object registries, deprecation handling, and API versioning support.

public interface XContentParserConfiguration {
    XContentParserConfiguration withRegistry(NamedXContentRegistry registry);
    XContentParserConfiguration withDeprecationHandler(DeprecationHandler handler);
    
    static final XContentParserConfiguration EMPTY = ...;
}

public class NamedXContentRegistry {
    public <T, C> T parseNamedObject(Class<T> categoryClass, String name, 
                                    XContentParser parser, C context);
    
    static final NamedXContentRegistry EMPTY = ...;
}

Configuration and Registry

Types

Core Interfaces

public interface ToXContent {
    XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException;
    
    interface Params {
        String param(String key);
    }
}

public interface ToXContentObject extends ToXContent {
    default boolean isFragment() { return false; }
}

public interface ToXContentFragment extends ToXContent {
    default boolean isFragment() { return true; }
}

Field Handling

public class ParseField {
    public ParseField(String name, String... deprecatedNames);
    public String getPreferredName();
    public boolean match(String fieldName, DeprecationHandler handler);
}

@FunctionalInterface
public interface ContextParser<Context, T> {
    T parse(XContentParser parser, Context context) throws IOException;
}

Exception Types

public class XContentParseException extends RuntimeException {
    public XContentParseException(String message);
    public XContentParseException(XContentLocation location, String message);
}

public class NamedObjectNotFoundException extends RuntimeException {
    public NamedObjectNotFoundException(String message);
}

public class XContentGenerationException extends RuntimeException {
    public XContentGenerationException(String message);
}