Package io.debezium.document

Interface Document

All Superinterfaces:
Comparable<Document>, Iterable<Document.Field>
All Known Implementing Classes:
BasicDocument
@NotThreadSafe public interface Document extends Iterable<Document.Field>, Comparable<Document>
A document contains multiple Document.Fields, each with a name and possibly-null Value. A single document can only contain a single field with a given name.
Author:
Randall Hauch

  • Method Details

    • field

      static Document.Field field(String name, Value value)

    • field

      static Document.Field field(String name, Object value)

    • create

      static Document create()

    • create

      static Document create(CharSequence fieldName, Object value)

    • create

      static Document create(CharSequence fieldName1, Object value1, CharSequence fieldName2, Object value2)

    • create

      static Document create(CharSequence fieldName1, Object value1, CharSequence fieldName2, Object value2, CharSequence fieldName3, Object value3)

    • create

      static Document create(CharSequence fieldName1, Object value1, CharSequence fieldName2, Object value2, CharSequence fieldName3, Object value3, CharSequence fieldName4, Object value4)

    • create

      static Document create(CharSequence fieldName1, Object value1, CharSequence fieldName2, Object value2, CharSequence fieldName3, Object value3, CharSequence fieldName4, Object value4, CharSequence fieldName5, Object value5)

    • create

      static Document create(CharSequence fieldName1, Object value1, CharSequence fieldName2, Object value2, CharSequence fieldName3, Object value3, CharSequence fieldName4, Object value4, CharSequence fieldName5, Object value5, CharSequence fieldName6, Object value6)

    • size

      int size()
      Return the number of name-value fields in this object.
      Returns:
      the number of name-value fields; never negative

    • isEmpty

      boolean isEmpty()
      Return whether this document contains no fields and is therefore empty.
      Returns:
      true if there are no fields in this document, or false if there is at least one.

    • clear

      void clear()
      Remove all fields from this document.

    • has

      boolean has(CharSequence fieldName)
      Determine if this contains a field with the given name.
      Parameters:
      fieldName - The name of the field
      Returns:
      true if the field exists, or false otherwise

    • hasAll

      boolean hasAll(Document document)
      Checks if this object contains all of the fields in the supplied document.
      Parameters:
      document - The document with the fields that should be in this document
      Returns:
      true if this document contains all of the fields in the supplied document, or false otherwise

    • set

      default Optional<Value> set(Path path, boolean addIntermediaries, Value value, Consumer<Path> invalid)
      Set the value at the given path resolved against this document, optionally adding any missing intermediary documents or arrays based upon the format of the path segments.
      Parameters:
      path - the path at which the value is to be set
      addIntermediaries - true if any missing intermediary fields should be created, or false if any missing intermediary fields should be handled as an error via invalid
      value - the value that should be set at the given path; may be null or a null value
      invalid - the function that should be called if the supplied path cannot be resolved; may not be null
      Returns:
      the value if successful or the empty (not present) optional value if the path was invalid and could not be resolved (and invalid is invoked)

    • find

      default Optional<Value> find(Path path)
      Attempt to find the value at the given path.
      Parameters:
      path - the path to find
      Returns:
      the optional value at this path, which is present if the value was found at that path or is empty (not present) if there is no value at the path or if the path was not valid

    • find

      default Optional<Value> find(Path path, BiFunction<Path,Integer,Optional<Value>> missingSegment, Consumer<Path> invalid)
      Attempt to find the value at the given path, optionally creating missing segments.
      Parameters:
      path - the path to find
      missingSegment - function called when a segment in the path does not exist, and which should return a new value if one should be created or Optional.empty() if nothing should be created and invalid function should be called by this method
      invalid - function called when the supplied path is invalid; in this case, this method also returns Optional.empty()
      Returns:
      the optional value at this path, which is present if the value was found at that path or is empty (not present) if there is no value at the path or if the path was not valid

    • children

      default Stream<Document.Field> children(Path path)
      Find a document at the given path and obtain a stream over its fields. This will return an empty stream when:
      • a value does not exist in this document at the supplied path; or
      • a non-document value does exist in this document at the supplied path; or
      • a document value does exist in this document at the supplied path, but that document is empty
      Parameters:
      path - the path to the contained document
      Returns:
      the stream of fields in the document at the given path; never null

    • children

      default Stream<Document.Field> children(String fieldName)
      Find the document at the given field name and obtain a stream over its fields. This will return an empty stream when:
      • a field with the given name does not exist in this document; or
      • a field with the given name does exist in this document but the value is not a document; or
      • a field with the given name does exist in this document and the value is an empty document
      Parameters:
      fieldName - the path to the contained document
      Returns:
      the stream of fields within the nested document; never null

    • getField

      default Document.Field getField(CharSequence fieldName)
      Gets the field in this document with the given field name.
      Parameters:
      fieldName - The name of the field
      Returns:
      The field, if found, or null otherwise

    • get

      default Value get(CharSequence fieldName)
      Gets the value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      Returns:
      The field value, if found, or null otherwise

    • get

      Value get(CharSequence fieldName, Comparable<?> defaultValue)
      Gets the value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      defaultValue - the default value to return if there is no such field
      Returns:
      The field value, if found, or , or defaultValue if there is no such field

    • getBoolean

      default Boolean getBoolean(CharSequence fieldName)
      Get the boolean value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      Returns:
      The boolean field value, if found, or null if there is no such field or if the value is not a boolean

    • getBoolean

      default boolean getBoolean(CharSequence fieldName, boolean defaultValue)
      Get the boolean value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      defaultValue - the default value to return if there is no such field or if the value is not a boolean
      Returns:
      The boolean field value if found, or defaultValue if there is no such field or if the value is not a boolean

    • getInteger

      default Integer getInteger(CharSequence fieldName)
      Get the integer value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      Returns:
      The integer field value, if found, or null if there is no such field or if the value is not an integer

    • getInteger

      default int getInteger(CharSequence fieldName, int defaultValue)
      Get the integer value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      defaultValue - the default value to return if there is no such field or if the value is not a integer
      Returns:
      The integer field value if found, or defaultValue if there is no such field or if the value is not a integer

    • getLong

      default Long getLong(CharSequence fieldName)
      Get the integer value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      Returns:
      The long field value, if found, or null if there is no such field or if the value is not a long value

    • getLong

      default long getLong(CharSequence fieldName, long defaultValue)
      Get the long value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      defaultValue - the default value to return if there is no such field or if the value is not a long value
      Returns:
      The long field value if found, or defaultValue if there is no such field or if the value is not a long value

    • getDouble

      default Double getDouble(CharSequence fieldName)
      Get the double value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      Returns:
      The double field value, if found, or null if there is no such field or if the value is not a double

    • getDouble

      default double getDouble(CharSequence fieldName, double defaultValue)
      Get the double value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      defaultValue - the default value to return if there is no such field or if the value is not a double
      Returns:
      The double field value if found, or defaultValue if there is no such field or if the value is not a double

    • getFloat

      default Float getFloat(CharSequence fieldName)
      Get the double value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      Returns:
      The double field value, if found, or null if there is no such field or if the value is not a double

    • getFloat

      default float getFloat(CharSequence fieldName, float defaultValue)
      Get the float value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      defaultValue - the default value to return if there is no such field or if the value is not a double
      Returns:
      The double field value if found, or defaultValue if there is no such field or if the value is not a double

    • getNumber

      default Number getNumber(CharSequence fieldName)
      Get the number value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      Returns:
      The number field value, if found, or null if there is no such field or if the value is not a number

    • getNumber

      default Number getNumber(CharSequence fieldName, Number defaultValue)
      Get the number value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      defaultValue - the default value to return if there is no such field or if the value is not a number
      Returns:
      The number field value if found, or defaultValue if there is no such field or if the value is not a number

    • getBigInteger

      default BigInteger getBigInteger(CharSequence fieldName)
      Get the big integer value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      Returns:
      The big integer field value, if found, or null if there is no such field or if the value is not a big integer

    • getBigInteger

      default BigInteger getBigInteger(CharSequence fieldName, BigInteger defaultValue)
      Get the big integer value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      defaultValue - the default value to return if there is no such field or if the value is not a big integer
      Returns:
      The big integer field value, if found, or null if there is no such field or if the value is not a big integer

    • getBigDecimal

      default BigDecimal getBigDecimal(CharSequence fieldName)
      Get the big decimal value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      Returns:
      The big decimal field value, if found, or null if there is no such field or if the value is not a big decimal

    • getBigDecimal

      default BigDecimal getBigDecimal(CharSequence fieldName, BigDecimal defaultValue)
      Get the big decimal value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      defaultValue - the default value to return if there is no such field or if the value is not a big decimal
      Returns:
      The big decimal field value, if found, or null if there is no such field or if the value is not a big decimal

    • getString

      default String getString(CharSequence fieldName)
      Get the string value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      Returns:
      The string field value, if found, or null if there is no such field or if the value is not a string

    • getString

      default String getString(CharSequence fieldName, String defaultValue)
      Get the string value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      defaultValue - the default value to return if there is no such field or if the value is not a string
      Returns:
      The string field value if found, or defaultValue if there is no such field or if the value is not a string

    • getBytes

      default byte[] getBytes(CharSequence fieldName)
      Get the Base64 encoded binary value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      Returns:
      The binary field value, if found, or null if there is no such field or if the value is not a binary value

    • getArray

      default Array getArray(CharSequence fieldName)
      Get the array value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      Returns:
      The array field value (as a list), if found, or null if there is no such field or if the value is not an array

    • getArray

      default Array getArray(CharSequence fieldName, Array defaultValue)
      Get the array value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      defaultValue - the default array that should be returned if there is no such field
      Returns:
      The array field value (as a list), if found, or the default value if there is no such field or if the value is not an array

    • getOrCreateArray

      default Array getOrCreateArray(CharSequence fieldName)
      Get the existing array value in this document for the given field name, or create a new array if there is no existing array at this field.
      Parameters:
      fieldName - The name of the field
      Returns:
      The editable array field value; never null

    • getDocument

      default Document getDocument(CharSequence fieldName)
      Get the document value in this document for the given field name.
      Parameters:
      fieldName - The name of the field
      Returns:
      The document field value, if found, or null if there is no such field or if the value is not a document

    • getOrCreateDocument

      default Document getOrCreateDocument(CharSequence fieldName)
      Get the existing document value in this document for the given field name, or create a new document if there is no existing document at this field.
      Parameters:
      fieldName - The name of the field
      Returns:
      The editable document field value; null if the field exists but is not a document

    • isNull

      default boolean isNull(CharSequence fieldName)
      Determine whether this object has a field with the given the name and the value is null. This is equivalent to calling: 
       this.get(name) instanceof Null;
      Parameters:
      fieldName - The name of the field
      Returns:
      true if the field exists but is null, or false otherwise
      See Also:

    • isNullOrMissing

      default boolean isNullOrMissing(CharSequence fieldName)
      Determine whether this object has a field with the given the name and the value is null, or if this object has no field with the given name. This is equivalent to calling: 
       Null.matches(this.get(name));
      Parameters:
      fieldName - The name of the field
      Returns:
      true if the field value for the name is null or if there is no such field.
      See Also:

    • keySet

      Iterable<CharSequence> keySet()
      Returns this object's fields' names
      Returns:
      The names of the fields in this object

    • clone

      Document clone()
      Obtain a clone of this document.
      Returns:
      the clone of this document; never null

    • remove

      Value remove(CharSequence name)
      Remove the field with the supplied name, and return the value.
      Parameters:
      name - The name of the field
      Returns:
      the value that was removed, or null if there was no such value

    • remove

      default Value remove(Optional<? extends CharSequence> name)
      If the supplied name is provided, then remove the field with the supplied name and return the value.
      Parameters:
      name - The optional name of the field
      Returns:
      the value that was removed, or null if the field was not present or there was no such value

    • removeAll

      Document removeAll()
      Remove all fields from this document.
      Returns:
      This document, to allow for chaining methods

    • putAll

      default Document putAll(Iterator<Document.Field> fields)
      Sets on this object all name/value pairs from the supplied object. If the supplied object is null, this method does nothing.
      Parameters:
      fields - the name/value pairs to be set on this object; may not be null
      Returns:
      This document, to allow for chaining methods

    • putAll

      default Document putAll(Iterable<Document.Field> fields)
      Sets on this object all name/value pairs from the supplied object. If the supplied object is null, this method does nothing.
      Parameters:
      fields - the name/value pairs to be set on this object; may not be null
      Returns:
      This document, to allow for chaining methods

    • putAll

      default Document putAll(Iterable<Document.Field> fields, Predicate<CharSequence> acceptableFieldNames)
      Attempts to copy all of the acceptable fields from the source and set on this document, overwriting any existing values.
      Parameters:
      fields - the name/value pairs to be set on this object; may not be null
      acceptableFieldNames - the predicate to determine which fields from the source should be copied; may not be null
      Returns:
      This document, to allow for chaining methods

    • putAll

      default Document putAll(Map<? extends CharSequence,?> fields)
      Sets on this object all key/value pairs from the supplied map. If the supplied map is null, this method does nothing.
      Parameters:
      fields - the map containing the name/value pairs to be set on this object
      Returns:
      This document, to allow for chaining methods

    • stream

      default Stream<Document.Field> stream()
      Returns a sequential Stream with this array as its source.
      Returns:
      a sequential Stream over the elements in this collection

    • forEach

      default void forEach(BiConsumer<Path,Value> consumer)

    • transform

      default Document transform(BiFunction<CharSequence,Value,Value> transformer)
      Transform all of the field values using the supplied transformer function.
      Parameters:
      transformer - the transformer that should be used to transform each field value; may not be null
      Returns:
      this document with transformed fields, or this document if the transformer changed none of the values

    • set

      default Document set(CharSequence name, Object value)
      Set the value for the field with the given name to be a binary value. The value will be encoded as Base64.
      Parameters:
      name - The name of the field
      value - the new value
      Returns:
      This document, to allow for chaining methods

    • setNull

      default Document setNull(CharSequence name)
      Set the value for the field with the given name to be a null value. The isNull(CharSequence) methods can be used to determine if a field has been set to null, or isNullOrMissing(CharSequence) if the field has not be set or if it has been set to null.
      Parameters:
      name - The name of the field
      Returns:
      This document, to allow for chaining methods
      See Also:

    • setBoolean

      default Document setBoolean(CharSequence name, boolean value)
      Set the value for the field with the given name to the supplied boolean value.
      Parameters:
      name - The name of the field
      value - the new value for the field
      Returns:
      This document, to allow for chaining methods

    • setNumber

      default Document setNumber(CharSequence name, int value)
      Set the value for the field with the given name to the supplied integer value.
      Parameters:
      name - The name of the field
      value - the new value for the field
      Returns:
      This document, to allow for chaining methods

    • setNumber

      default Document setNumber(CharSequence name, long value)
      Set the value for the field with the given name to the supplied long value.
      Parameters:
      name - The name of the field
      value - the new value for the field
      Returns:
      This document, to allow for chaining methods

    • setNumber

      default Document setNumber(CharSequence name, float value)
      Set the value for the field with the given name to the supplied float value.
      Parameters:
      name - The name of the field
      value - the new value for the field
      Returns:
      This document, to allow for chaining methods

    • setNumber

      default Document setNumber(CharSequence name, double value)
      Set the value for the field with the given name to the supplied double value.
      Parameters:
      name - The name of the field
      value - the new value for the field
      Returns:
      This document, to allow for chaining methods

    • setNumber

      default Document setNumber(CharSequence name, BigInteger value)
      Set the value for the field with the given name to the supplied big integer value.
      Parameters:
      name - The name of the field
      value - the new value for the field
      Returns:
      This document, to allow for chaining methods

    • setNumber

      default Document setNumber(CharSequence name, BigDecimal value)
      Set the value for the field with the given name to the supplied big integer value.
      Parameters:
      name - The name of the field
      value - the new value for the field
      Returns:
      This document, to allow for chaining methods

    • setString

      default Document setString(CharSequence name, String value)
      Set the value for the field with the given name to the supplied string value.
      Parameters:
      name - The name of the field
      value - the new value for the field
      Returns:
      This document, to allow for chaining methods

    • increment

      default Document increment(CharSequence name, int increment)
      Increment the numeric value in the given field by the designated amount.
      Parameters:
      name - The name of the field
      increment - the amount to increment the existing value; may be negative to decrement
      Returns:
      this array to allow for chaining methods
      Throws:
      IllegalArgumentException - if the current value is not a number

    • increment

      default Document increment(CharSequence name, long increment)
      Increment the numeric value in the given field by the designated amount.
      Parameters:
      name - The name of the field
      increment - the amount to increment the existing value; may be negative to decrement
      Returns:
      this array to allow for chaining methods
      Throws:
      IllegalArgumentException - if the current value is not a number

    • increment

      default Document increment(CharSequence name, double increment)
      Increment the numeric value in the given field by the designated amount.
      Parameters:
      name - The name of the field
      increment - the amount to increment the existing value; may be negative to decrement
      Returns:
      this array to allow for chaining methods
      Throws:
      IllegalArgumentException - if the current value is not a number

    • increment

      default Document increment(CharSequence name, float increment)
      Increment the numeric value in the given field by the designated amount.
      Parameters:
      name - The name of the field
      increment - the amount to increment the existing value; may be negative to decrement
      Returns:
      this array to allow for chaining methods
      Throws:
      IllegalArgumentException - if the current value is not a number

    • increment

      Document increment(CharSequence name, Value increment)
      Increment the numeric value in the given field by the designated amount.
      Parameters:
      name - The name of the field
      increment - the amount to increment the existing value; may be negative to decrement
      Returns:
      this array to allow for chaining methods
      Throws:
      IllegalArgumentException - if the current value is not a number

    • setBinary

      default Document setBinary(CharSequence name, byte[] data)
      Set the value for the field with the given name to be a binary value. The value will be encoded as Base64.
      Parameters:
      name - The name of the field
      data - the bytes for the binary value
      Returns:
      This document, to allow for chaining methods

    • setValue

      Document setValue(CharSequence name, Value value)
      Set the value for the field with the given name.
      Parameters:
      name - The name of the field
      value - the new value
      Returns:
      This document, to allow for chaining methods

    • setValue

      default Document setValue(Document.Field field)
      Set the field on this document.
      Parameters:
      field - The field
      Returns:
      This document, to allow for chaining methods

    • setDocument

      default Document setDocument(CharSequence name)
      Set the value for the field with the given name to be a new, empty Document.
      Parameters:
      name - The name of the field
      Returns:
      The editable document that was just created; never null

    • setDocument

      default Document setDocument(CharSequence name, Document document)
      Set the value for the field with the given name to be the supplied Document.
      Parameters:
      name - The name of the field
      document - the document; if null, a new document will be created
      Returns:
      The document that was just set as the value for the named field; never null and may or may not be the same instance as the supplied document.

    • setArray

      default Array setArray(CharSequence name)
      Set the value for the field with the given name to be a new, empty array.
      Parameters:
      name - The name of the field
      Returns:
      The array that was just created; never null

    • setArray

      default Array setArray(CharSequence name, Array array)
      Set the value for the field with the given name to be the supplied array.
      Parameters:
      name - The name of the field
      array - the array
      Returns:
      The array that was just set as the value for the named field; never null and may or may not be the same instance as the supplied array.

    • setArray

      default Array setArray(CharSequence name, Object... values)
      Set the value for the field with the given name to be the supplied array.
      Parameters:
      name - The name of the field
      values - the (valid) values for the array
      Returns:
      The array that was just set as the value for the named field; never null and may or may not be the same instance as the supplied array.

    • compareTo

      int compareTo(Document that)
      Compare this Document to the specified Document, taking into account the order of the fields.
      Specified by:
      compareTo in interface Comparable<Document>
      Parameters:
      that - the other Document to be compared to this object
      Returns:
      a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

    • compareToWithoutFieldOrder

      int compareToWithoutFieldOrder(Document that)
      Compare this Document to the specified Document, without regard to the order of the fields.
      Parameters:
      that - the other Document to be compared to this object
      Returns:
      a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

    • compareToUsingSimilarFields

      int compareToUsingSimilarFields(Document that)
      Compare this Document to the specified Document, without regard to the order of the fields and only using the fields that are in both documents.
      Parameters:
      that - the other Document to be compared to this object
      Returns:
      a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

    • compareTo

      int compareTo(Document that, boolean enforceFieldOrder)
      Compare this Document to the specified Document, optionally comparing the fields in the same order.
      Parameters:
      that - the other Document to be compared to this object
      enforceFieldOrder - true if the documents should be compared using their existing field order, or false if the field order should not affect the result.
      Returns:
      a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.