Class XContentBuilder

java.lang.Object
org.elasticsearch.common.xcontent.XContentBuilder
All Implemented Interfaces:
java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

public final class XContentBuilder
extends java.lang.Object
implements java.io.Closeable, java.io.Flushable
A utility to build XContent (ie json).
  • Constructor Details

    • XContentBuilder

      public XContentBuilder​(XContent xContent, java.io.OutputStream bos) throws java.io.IOException
      Constructs a new builder using the provided XContent and an OutputStream. Make sure to call close() when the builder is done with.
      Throws:
      java.io.IOException
    • XContentBuilder

      public XContentBuilder​(XContent xContent, java.io.OutputStream bos, java.util.Set<java.lang.String> includes) throws java.io.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:
      java.io.IOException
    • XContentBuilder

      public XContentBuilder​(XContent xContent, java.io.OutputStream os, java.util.Set<java.lang.String> includes, java.util.Set<java.lang.String> excludes) throws java.io.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:
      java.io.IOException
  • Method Details

    • builder

      public static XContentBuilder builder​(XContent xContent) throws java.io.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:
      java.io.IOException - if an IOException occurs while building the content
    • builder

      public static XContentBuilder builder​(XContent xContent, java.util.Set<java.lang.String> includes, java.util.Set<java.lang.String> excludes) throws java.io.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:
      java.io.IOException - if an IOException occurs while building the content
    • contentType

      public XContentType contentType()
    • getOutputStream

      public java.io.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 java.io.IOException
      Throws:
      java.io.IOException
    • startObject

      public XContentBuilder startObject​(java.lang.String name) throws java.io.IOException
      Throws:
      java.io.IOException
    • endObject

      public XContentBuilder endObject() throws java.io.IOException
      Throws:
      java.io.IOException
    • startArray

      public XContentBuilder startArray() throws java.io.IOException
      Throws:
      java.io.IOException
    • startArray

      public XContentBuilder startArray​(java.lang.String name) throws java.io.IOException
      Throws:
      java.io.IOException
    • endArray

      public XContentBuilder endArray() throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name) throws java.io.IOException
      Throws:
      java.io.IOException
    • nullField

      public XContentBuilder nullField​(java.lang.String name) throws java.io.IOException
      Throws:
      java.io.IOException
    • nullValue

      public XContentBuilder nullValue() throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, java.lang.Boolean value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, boolean value) throws java.io.IOException
      Throws:
      java.io.IOException
    • array

      public XContentBuilder array​(java.lang.String name, boolean[] values) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(java.lang.Boolean value) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(boolean value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, java.lang.Byte value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, byte value) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(java.lang.Byte value) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(byte value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, java.lang.Double value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, double value) throws java.io.IOException
      Throws:
      java.io.IOException
    • array

      public XContentBuilder array​(java.lang.String name, double[] values) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(java.lang.Double value) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(double value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, java.lang.Float value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, float value) throws java.io.IOException
      Throws:
      java.io.IOException
    • array

      public XContentBuilder array​(java.lang.String name, float[] values) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(java.lang.Float value) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(float value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, java.lang.Integer value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, int value) throws java.io.IOException
      Throws:
      java.io.IOException
    • array

      public XContentBuilder array​(java.lang.String name, int[] values) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(java.lang.Integer value) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(int value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, java.lang.Long value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, long value) throws java.io.IOException
      Throws:
      java.io.IOException
    • array

      public XContentBuilder array​(java.lang.String name, long[] values) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(java.lang.Long value) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(long value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, java.lang.Short value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, short value) throws java.io.IOException
      Throws:
      java.io.IOException
    • array

      public XContentBuilder array​(java.lang.String name, short[] values) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(java.lang.Short value) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(short value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, java.math.BigInteger value) throws java.io.IOException
      Throws:
      java.io.IOException
    • array

      public XContentBuilder array​(java.lang.String name, java.math.BigInteger[] values) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(java.math.BigInteger value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, java.math.BigDecimal value) throws java.io.IOException
      Throws:
      java.io.IOException
    • array

      public XContentBuilder array​(java.lang.String name, java.math.BigDecimal[] values) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(java.math.BigDecimal value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, java.lang.String value) throws java.io.IOException
      Throws:
      java.io.IOException
    • array

      public XContentBuilder array​(java.lang.String name, java.lang.String... values) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(java.lang.String value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, byte[] value) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(byte[] value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, byte[] value, int offset, int length) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(byte[] value, int offset, int length) throws java.io.IOException
      Throws:
      java.io.IOException
    • utf8Value

      public XContentBuilder utf8Value​(byte[] bytes, int offset, int length) throws java.io.IOException
      Writes the binary content of the given byte array as UTF-8 bytes. Use XContentParser.charBuffer() to read the value back
      Throws:
      java.io.IOException
    • timeField

      public XContentBuilder timeField​(java.lang.String name, java.lang.Object timeValue) throws java.io.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:
      java.lang.IllegalArgumentException - if there is no transformers for the type of object
      java.io.IOException
    • timeField

      public XContentBuilder timeField​(java.lang.String name, java.lang.String readableName, long value) throws java.io.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:
      java.io.IOException
    • timeValue

      public XContentBuilder timeValue​(java.lang.Object timeValue) throws java.io.IOException
      Write a time-based value, if the value is null a null value is written, otherwise a date transformers lookup is performed.
      Throws:
      java.lang.IllegalArgumentException - if there is no transformers for the type of object
      java.io.IOException
    • latlon

      public XContentBuilder latlon​(java.lang.String name, double lat, double lon) throws java.io.IOException
      Throws:
      java.io.IOException
    • latlon

      public XContentBuilder latlon​(double lat, double lon) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(java.nio.file.Path value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, java.lang.Object value) throws java.io.IOException
      Throws:
      java.io.IOException
    • array

      public XContentBuilder array​(java.lang.String name, java.lang.Object... values) throws java.io.IOException
      Throws:
      java.io.IOException
    • value

      public XContentBuilder value​(java.lang.Object value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, ToXContent value) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, ToXContent value, ToXContent.Params params) throws java.io.IOException
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, java.util.Map<java.lang.String,​java.lang.Object> values) throws java.io.IOException
      Throws:
      java.io.IOException
    • map

      public XContentBuilder map​(java.util.Map<java.lang.String,​?> values) throws java.io.IOException
      Throws:
      java.io.IOException
    • mapContents

      public XContentBuilder mapContents​(java.util.Map<java.lang.String,​?> values) throws java.io.IOException
      writes a map without the start object and end object headers
      Throws:
      java.io.IOException
    • field

      public XContentBuilder field​(java.lang.String name, java.lang.Iterable<?> values) throws java.io.IOException
      Throws:
      java.io.IOException
    • humanReadableField

      public XContentBuilder humanReadableField​(java.lang.String rawFieldName, java.lang.String readableFieldName, java.lang.Object value) throws java.io.IOException
      Throws:
      java.io.IOException
    • percentageField

      public XContentBuilder percentageField​(java.lang.String rawFieldName, java.lang.String readableFieldName, double percentage) throws java.io.IOException
      Throws:
      java.io.IOException
    • rawField

      @Deprecated public XContentBuilder rawField​(java.lang.String name, java.io.InputStream value) throws java.io.IOException
      Deprecated.
      use rawField(String, InputStream, XContentType) to avoid content type auto-detection
      Writes a raw field with the value taken from the bytes in the stream
      Throws:
      java.io.IOException
    • rawField

      public XContentBuilder rawField​(java.lang.String name, java.io.InputStream value, XContentType contentType) throws java.io.IOException
      Writes a raw field with the value taken from the bytes in the stream
      Throws:
      java.io.IOException
    • rawValue

      public XContentBuilder rawValue​(java.io.InputStream stream, XContentType contentType) throws java.io.IOException
      Writes a value with the source coming directly from the bytes in the stream
      Throws:
      java.io.IOException
    • copyCurrentStructure

      public XContentBuilder copyCurrentStructure​(XContentParser parser) throws java.io.IOException
      Throws:
      java.io.IOException
    • flush

      public void flush() throws java.io.IOException
      Specified by:
      flush in interface java.io.Flushable
      Throws:
      java.io.IOException
    • close

      public void close()
      Specified by:
      close in interface java.lang.AutoCloseable
      Specified by:
      close in interface java.io.Closeable
    • generator

      public XContentGenerator generator()