Package org.opensearch.core.xcontent

Class XContentBuilder

java.lang.Object

org.opensearch.core.xcontent.XContentBuilder

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

@PublicApi(since="1.0.0")
public final class XContentBuilder
extends Object
implements Closeable, Flushable

A utility to build XContent (ie json).

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	XContentBuilder.HumanReadableTransformer	Interface for transforming complex objects into their "raw" equivalents for human-readable fields
static interface	XContentBuilder.Writer	The writer interface for the serializable content builder

Constructor Summary

Constructors

Constructor	Description
XContentBuilder(XContent xContent, OutputStream bos)	Constructs a new builder using the provided XContent and an OutputStream.
XContentBuilder(XContent xContent, OutputStream bos, Set<String> includes)	Constructs a new builder using the provided XContent, an OutputStream and some filters.
XContentBuilder(XContent xContent, OutputStream os, Set<String> includes, Set<String> excludes)	Creates a new builder using the provided XContent, output stream and some inclusive and/or exclusive filters.

Method Summary

Modifier and Type	Method	Description
XContentBuilder	array(String name, boolean[] values)
XContentBuilder	array(String name, double[] values)
XContentBuilder	array(String name, float[] values)
XContentBuilder	array(String name, int[] values)
XContentBuilder	array(String name, long[] values)
XContentBuilder	array(String name, short[] values)
XContentBuilder	array(String name, Object... values)
XContentBuilder	array(String name, String... values)
XContentBuilder	array(String name, BigDecimal[] values)
XContentBuilder	array(String name, BigInteger[] values)
static XContentBuilder	builder(XContent xContent)	Create a new XContentBuilder using the given XContent content.
static XContentBuilder	builder(XContent xContent, Set<String> includes, Set<String> excludes)	Create a new XContentBuilder using the given XContent content and some inclusive and/or exclusive filters.
void	close()
MediaType	contentType()
XContentBuilder	copyCurrentStructure(XContentParser parser)
XContentBuilder	endArray()
XContentBuilder	endObject()
static void	ensureNameNotNull(String name)
static void	ensureNotNull(Object value, String message)
XContentBuilder	field(String name)
XContentBuilder	field(String name, boolean value)
XContentBuilder	field(String name, byte value)
XContentBuilder	field(String name, byte[] value)
XContentBuilder	field(String name, byte[] value, int offset, int length)
XContentBuilder	field(String name, double value)
XContentBuilder	field(String name, float value)
XContentBuilder	field(String name, int value)
XContentBuilder	field(String name, long value)
XContentBuilder	field(String name, short value)
XContentBuilder	field(String name, Boolean value)
XContentBuilder	field(String name, Byte value)
XContentBuilder	field(String name, Double value)
XContentBuilder	field(String name, Float value)
XContentBuilder	field(String name, Integer value)
XContentBuilder	field(String name, Iterable<?> values)
XContentBuilder	field(String name, Long value)
XContentBuilder	field(String name, Object value)
XContentBuilder	field(String name, Short value)
XContentBuilder	field(String name, String value)
XContentBuilder	field(String name, BigDecimal value)
XContentBuilder	field(String name, BigInteger value)
XContentBuilder	field(String name, Map<String,Object> values)
XContentBuilder	field(String name, ToXContent value)
XContentBuilder	field(String name, ToXContent value, ToXContent.Params params)
void	flush()
XContentGenerator	generator()
OutputStream	getOutputStream()
boolean	humanReadable()
XContentBuilder	humanReadable(boolean humanReadable)	Set the "human readable" flag.
XContentBuilder	humanReadableField(String rawFieldName, String readableFieldName, Object value)
boolean	isPrettyPrint()
XContentBuilder	latlon(double lat, double lon)
XContentBuilder	latlon(String name, double lat, double lon)
XContentBuilder	lfAtEnd()	Indicate that the current XContentBuilder must write a line feed ("\n") at the end of the built object.
XContentBuilder	map(Map<String,?> values)
XContentBuilder	mapContents(Map<String,?> values)	writes a map without the start object and end object headers
XContentBuilder	nullField(String name)
XContentBuilder	nullValue()
XContentBuilder	percentageField(String rawFieldName, String readableFieldName, double percentage)
XContentBuilder	prettyPrint()
XContentBuilder	rawField(String name, InputStream value)	Deprecated. use rawField(String, InputStream, MediaType) to avoid content type auto-detection
XContentBuilder	rawField(String name, InputStream value, MediaType mediaType)	Writes a raw field with the value taken from the bytes in the stream
XContentBuilder	rawValue(InputStream stream, MediaType contentType)	Writes a value with the source coming directly from the bytes in the stream
XContentBuilder	startArray()
XContentBuilder	startArray(String name)
XContentBuilder	startObject()
XContentBuilder	startObject(String name)
XContentBuilder	timeField(String name, Object timeValue)	Write a time-based field and value, if the passed timeValue is null a null value is written, otherwise a date transformers lookup is performed.
XContentBuilder	timeField(String name, String readableName, long value)	If the humanReadable flag is set, writes both a formatted and unformatted version of the time value using the date transformer for the Long class.
XContentBuilder	timeValue(Object timeValue)	Write a time-based value, if the value is null a null value is written, otherwise a date transformers lookup is performed.
String	toString()	Returns a string representation of the builder (only applicable for text based xcontent).
XContentBuilder	utf8Value(byte[] bytes, int offset, int length)	Writes the binary content of the given byte array as UTF-8 bytes.
XContentBuilder	value(boolean value)
XContentBuilder	value(byte value)
XContentBuilder	value(byte[] value)
XContentBuilder	value(byte[] value, int offset, int length)
XContentBuilder	value(double value)
XContentBuilder	value(float value)
XContentBuilder	value(int value)
XContentBuilder	value(long value)
XContentBuilder	value(short value)
XContentBuilder	value(Boolean value)
XContentBuilder	value(Byte value)
XContentBuilder	value(Double value)
XContentBuilder	value(Float value)
XContentBuilder	value(Integer value)
XContentBuilder	value(Long value)
XContentBuilder	value(Object value)
XContentBuilder	value(Short value)
XContentBuilder	value(String value)
XContentBuilder	value(BigDecimal value)
XContentBuilder	value(BigInteger value)
XContentBuilder	value(Path value)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

XContentBuilder

public XContentBuilder(XContent xContent,
 OutputStream bos)
                throws IOException

Constructs a new builder using the provided XContent and an OutputStream. Make sure to call close() when the builder is done with.

Throws:

IOException

XContentBuilder

public XContentBuilder(XContent xContent,
 OutputStream bos,
 Set<String> includes)
                throws IOException

Constructs a new builder using the provided XContent, an OutputStream and some filters. If filters are specified, only those values matching a filter will be written to the output stream. Make sure to call close() when the builder is done with.

Throws:

IOException

XContentBuilder

public XContentBuilder(XContent xContent,
 OutputStream os,
 Set<String> includes,
 Set<String> excludes)
                throws IOException

Creates a new builder using the provided XContent, output stream and some inclusive and/or exclusive filters. When both exclusive and inclusive filters are provided, the underlying builder will first use exclusion filters to remove fields and then will check the remaining fields against the inclusive filters.

Make sure to call close() when the builder is done with.

Parameters:

os - the output stream

includes - the inclusive filters: only fields and objects that match the inclusive filters will be written to the output.

excludes - the exclusive filters: only fields and objects that don't match the exclusive filters will be written to the output.

Throws:

IOException

Method Details

builder

public static XContentBuilder builder(XContent xContent)
                               throws IOException

Create a new XContentBuilder using the given XContent content.

The builder uses an internal ByteArrayOutputStream output stream to build the content.

Parameters:

xContent - the XContent

Returns:

a new XContentBuilder

Throws:

IOException - if an IOException occurs while building the content

builder

public static XContentBuilder builder(XContent xContent,
 Set<String> includes,
 Set<String> excludes)
                               throws IOException

Create a new XContentBuilder using the given XContent content and some inclusive and/or exclusive filters.

The builder uses an internal ByteArrayOutputStream output stream to build the content. When both exclusive and inclusive filters are provided, the underlying builder will first use exclusion filters to remove fields and then will check the remaining fields against the inclusive filters.

Parameters:

xContent - the XContent

includes - the inclusive filters: only fields and objects that match the inclusive filters will be written to the output.

excludes - the exclusive filters: only fields and objects that don't match the exclusive filters will be written to the output.

Throws:

IOException - if an IOException occurs while building the content

toString

public String toString()

Returns a string representation of the builder (only applicable for text based xcontent). Note: explicitly or implicitly (from debugger) calling toString() could cause XContentBuilder to close which is a side effect done by @see BytesReference#bytes(). Trying to write more contents after toString() will cause NPE. Use it with caution.

Overrides:

toString in class Object

contentType

public MediaType contentType()

getOutputStream

public OutputStream getOutputStream()

Returns:

the output stream to which the built object is being written. Note that is dangerous to modify the stream.

prettyPrint

public XContentBuilder prettyPrint()

isPrettyPrint

public boolean isPrettyPrint()

lfAtEnd

public XContentBuilder lfAtEnd()

Indicate that the current XContentBuilder must write a line feed ("\n") at the end of the built object.

This only applies for JSON XContent type. It has no effect for other types.

humanReadable

public XContentBuilder humanReadable(boolean humanReadable)

Set the "human readable" flag. Once set, some types of values are written in a format easier to read for a human.

humanReadable

public boolean humanReadable()

Returns:

the value of the "human readable" flag. When the value is equal to true, some types of values are written in a format easier to read for a human.

startObject

public XContentBuilder startObject()
                            throws IOException

Throws:

IOException

startObject

public XContentBuilder startObject(String name)
                            throws IOException

Throws:

IOException

endObject

public XContentBuilder endObject()
                          throws IOException

Throws:

IOException

startArray

public XContentBuilder startArray()
                           throws IOException

Throws:

IOException

startArray

public XContentBuilder startArray(String name)
                           throws IOException

Throws:

IOException

endArray

public XContentBuilder endArray()
                         throws IOException

Throws:

IOException

field

public XContentBuilder field(String name)
                      throws IOException

Throws:

IOException

nullField

public XContentBuilder nullField(String name)
                          throws IOException

Throws:

IOException

nullValue

public XContentBuilder nullValue()
                          throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 Boolean value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 boolean value)
                      throws IOException

Throws:

IOException

array

public XContentBuilder array(String name,
 boolean[] values)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(Boolean value)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(boolean value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 Byte value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 byte value)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(Byte value)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(byte value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 Double value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 double value)
                      throws IOException

Throws:

IOException

array

public XContentBuilder array(String name,
 double[] values)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(Double value)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(double value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 Float value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 float value)
                      throws IOException

Throws:

IOException

array

public XContentBuilder array(String name,
 float[] values)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(Float value)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(float value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 Integer value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 int value)
                      throws IOException

Throws:

IOException

array

public XContentBuilder array(String name,
 int[] values)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(Integer value)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(int value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 Long value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 long value)
                      throws IOException

Throws:

IOException

array

public XContentBuilder array(String name,
 long[] values)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(Long value)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(long value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 Short value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 short value)
                      throws IOException

Throws:

IOException

array

public XContentBuilder array(String name,
 short[] values)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(Short value)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(short value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 BigInteger value)
                      throws IOException

Throws:

IOException

array

public XContentBuilder array(String name,
 BigInteger[] values)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(BigInteger value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 BigDecimal value)
                      throws IOException

Throws:

IOException

array

public XContentBuilder array(String name,
 BigDecimal[] values)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(BigDecimal value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 String value)
                      throws IOException

Throws:

IOException

array

public XContentBuilder array(String name,
 String... values)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(String value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 byte[] value)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(byte[] value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 byte[] value,
 int offset,
 int length)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(byte[] value,
 int offset,
 int length)
                      throws IOException

Throws:

IOException

utf8Value

public XContentBuilder utf8Value(byte[] bytes,
 int offset,
 int length)
                          throws IOException

Writes the binary content of the given byte array as UTF-8 bytes.

Use XContentParser.charBuffer() to read the value back

Throws:

IOException

timeField

public XContentBuilder timeField(String name,
 Object timeValue)
                          throws IOException

Write a time-based field and value, if the passed timeValue is null a null value is written, otherwise a date transformers lookup is performed.

Throws:

IllegalArgumentException - if there is no transformers for the type of object

IOException

timeField

public XContentBuilder timeField(String name,
 String readableName,
 long value)
                          throws IOException

If the humanReadable flag is set, writes both a formatted and unformatted version of the time value using the date transformer for the Long class.

Throws:

IOException

timeValue

public XContentBuilder timeValue(Object timeValue)
                          throws IOException

Write a time-based value, if the value is null a null value is written, otherwise a date transformers lookup is performed.

Throws:

IllegalArgumentException - if there is no transformers for the type of object

IOException

latlon

public XContentBuilder latlon(String name,
 double lat,
 double lon)
                       throws IOException

Throws:

IOException

latlon

public XContentBuilder latlon(double lat,
 double lon)
                       throws IOException

Throws:

IOException

value

public XContentBuilder value(Path value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 Object value)
                      throws IOException

Throws:

IOException

array

public XContentBuilder array(String name,
 Object... values)
                      throws IOException

Throws:

IOException

value

public XContentBuilder value(Object value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 ToXContent value)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 ToXContent value,
 ToXContent.Params params)
                      throws IOException

Throws:

IOException

field

public XContentBuilder field(String name,
 Map<String,Object> values)
                      throws IOException

Throws:

IOException

map

public XContentBuilder map(Map<String,?> values)
                    throws IOException

Throws:

IOException

mapContents

public XContentBuilder mapContents(Map<String,?> values)
                            throws IOException

writes a map without the start object and end object headers

Throws:

IOException

field

public XContentBuilder field(String name,
 Iterable<?> values)
                      throws IOException

Throws:

IOException

humanReadableField

public XContentBuilder humanReadableField(String rawFieldName,
 String readableFieldName,
 Object value)
                                   throws IOException

Throws:

IOException

percentageField

public XContentBuilder percentageField(String rawFieldName,
 String readableFieldName,
 double percentage)
                                throws IOException

Throws:

IOException

rawField

@Deprecated
public XContentBuilder rawField(String name,
 InputStream value)
                         throws IOException

Deprecated.

use rawField(String, InputStream, MediaType) to avoid content type auto-detection

Writes a raw field with the value taken from the bytes in the stream

Throws:

IOException

rawField

public XContentBuilder rawField(String name,
 InputStream value,
 MediaType mediaType)
                         throws IOException

Writes a raw field with the value taken from the bytes in the stream

Throws:

IOException

rawValue

public XContentBuilder rawValue(InputStream stream,
 MediaType contentType)
                         throws IOException

Writes a value with the source coming directly from the bytes in the stream

Throws:

IOException

copyCurrentStructure

public XContentBuilder copyCurrentStructure(XContentParser parser)
                                     throws IOException

Throws:

IOException

flush

public void flush()
           throws IOException

Specified by:

flush in interface Flushable

Throws:

IOException

close

public void close()

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

generator

public XContentGenerator generator()

ensureNameNotNull

public static void ensureNameNotNull(String name)

ensureNotNull

public static void ensureNotNull(Object value,
 String message)