Interface Document.Mutable

All Superinterfaces:
DocPropertyHolder, DocPropertyHolder.Mutable<Document.Mutable>, Document, Externalizable, Serializable
Enclosing interface:
Document
public static interface Document.Mutable extends Document, DocPropertyHolder.Mutable<Document.Mutable>
A mutable version of a document. This type allows to set and remove key-value pairs from the underlying implementation but still provides read access to the stored data. Note that this type of document is not required to be thread-safe and users need to be careful to not create data races on accident.

For more information how to use the mutable version, see the root documentation of Document.

Since:
4.0

  • Method Details

    • clear

      @Contract("-> this") @NonNull Document.Mutable clear()
      Removes all key-value pairs from this document. After this method call this document is empty.
      Returns:
      the same document instance as used to call the method, for chaining.

    • remove

      @Contract("_ -> this") @NonNull Document.Mutable remove(@NonNull @NonNull String key)
      Removes the value associated with the given key from this document. If the key is not associated with any value this method call has no effect.
      Parameters:
      key - the key to remove from this document.
      Returns:
      the same document instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given key is null.

    • receive

      @Contract("_ -> this") @NonNull Document.Mutable receive(@NonNull @NonNull DocumentSend send)
      Receives the given document send into this document. All key-value pairs given in the document send will be put into this document, ignoring the fact that a key might already be associated with a value in this document. If the document send contains a data type that is not supported by this document type, the key-value pair gets simply skipped.

      The receiving process of a document send should never throw an exception unless the given document send contains malformed or invalid data making it impossible to get imported.

      Parameters:
      send - the document send to import into this document.
      Returns:
      the same document instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given send is null.

    • appendNull

      @Contract("_ -> this") @NonNull Document.Mutable appendNull(@NonNull @NonNull String key)
      Associates a null value with the given key. If this document type does not support null values, this call has no effect.
      Parameters:
      key - the key to associate with null.
      Returns:
      the same document instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given key is null.

    • appendTree

      @Contract("_ -> this") @NonNull Document.Mutable appendTree(@Nullable @Nullable Object value)
      Appends the key-value pairs based on the given object into this document. Each field of the given object represents a key-value mapping that is directly appended to this document. How the field value is included into this document depends on the type of document. If a field type is not supported by this document type it gets silently ignored. If null or a non-object is passed to this method (for example a primitive) this method call does nothing.

      Note: passing a generic type to this method will lose all the generic type information.

      Parameters:
      value - the value to serialize to a tree and append to this document.
      Returns:
      the same document instance as used to call the method, for chaining.

    • append

      @Contract("_ -> this") @NonNull Document.Mutable append(@NonNull @NonNull Document document)
      Appends all key-value pairs of the given document into this document. If a key-value pair with the same key already exists it gets overridden by this method call. If the given document contains a value type that is not supported by this document, the key-value pair is silently ignored. Changes made to this document after this method call will not reflect into the given document and vice-versa.

      This method should never throw an exception unless the given document contains malformed data.

      Parameters:
      document - the document to import into this document.
      Returns:
      the same document instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given document is null.

    • append

      @Contract("_, _ -> this") @NonNull Document.Mutable append(@NonNull @NonNull String key, @Nullable @Nullable Object value)
      Appends the key-value pairs based on the given object into this document associated with the given key. Each field of the given object represents a key-value mapping. How the field value is included into this document depends on the type of document. If a field type is not supported by this document type it gets silently ignored.

      Note: passing a generic type to this method will lose all the generic type information.

      Parameters:
      key - the key to associate the given value with.
      value - the value to serialize to a tree and append to this document associated with the given key.
      Returns:
      the same document instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given key is null.

    • append

      @Contract("_, _ -> this") @NonNull Document.Mutable append(@NonNull @NonNull String key, @Nullable @Nullable Number value)
      Appends the given number associated with the given key to this document. If the passed number instance is null, then null is appended to this document. If this document does not support numbers (or nulls) then this method call has no effect.
      Parameters:
      key - the key to associate the given number with.
      value - the number value to associate with the given key.
      Returns:
      the same document instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given key is null.

    • append

      @Contract("_, _ -> this") @NonNull Document.Mutable append(@NonNull @NonNull String key, @Nullable @Nullable Boolean value)
      Appends the given boolean associated with the given key to this document. If the passed boolean instance is null, then null is appended to this document. If this document does not support booleans (or nulls) then this method call has no effect.
      Parameters:
      key - the key to associate the given boolean with.
      value - the boolean value to associate with the given key.
      Returns:
      the same document instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given key is null.

    • append

      @Contract("_, _ -> this") @NonNull Document.Mutable append(@NonNull @NonNull String key, @Nullable @Nullable String value)
      Appends the given string associated with the given key to this document. If the passed string instance is null, then null is appended to this document. If this document does not support strings (or nulls) then this method call has no effect.
      Parameters:
      key - the key to associate the given string with.
      value - the string value to associate with the given key.
      Returns:
      the same document instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given key is null.

    • append

      @Contract("_, _ -> this") @NonNull Document.Mutable append(@NonNull @NonNull String key, @Nullable @Nullable Document value)
      Appends the given document associated with the given key to this document. If the passed document instance is null, then null is appended to this document. If the given document contains a value type that is not supported by this document then that key-value pair is ignored.

      This method should never throw an exception unless the given document contains malformed data.

      Parameters:
      key - the key to associate the given document with.
      value - the document value to associate with the given key.
      Returns:
      the same document instance as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given key is null.