Class 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 Detail

      • 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 Detail

      • 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
      • 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.
      • 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,
                                     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
      • 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