Package eu.cloudnetservice.driver.document.gson

Class MutableGsonDocument

java.lang.Object
eu.cloudnetservice.driver.document.gson.ImmutableGsonDocument
eu.cloudnetservice.driver.document.gson.MutableGsonDocument
All Implemented Interfaces:
Document, Document.Mutable, DefaultedDocPropertyHolder, DefaultedDocPropertyHolder.Mutable<Document.Mutable>, DocPropertyHolder, DocPropertyHolder.Mutable<Document.Mutable>, Serializable
final class MutableGsonDocument extends ImmutableGsonDocument implements Document.Mutable, DefaultedDocPropertyHolder.Mutable<Document.Mutable>
Mutable version of a gson document implementing the full mutable document functionality.
Since:
4.0

  • Field Details

  • Constructor Details

    • MutableGsonDocument

      public MutableGsonDocument()
      Constructs a new, empty gson document instance.

    • MutableGsonDocument

      MutableGsonDocument(@NonNull @NonNull com.google.gson.JsonObject internalObject)
      Constructs a new gson document instance using the given initial internal object. Note that the given object is not copied, it is up to the caller to ensure no races or data leaks are created when using this constructor.
      Parameters:
      internalObject - the initial internal json object to use.
      Throws:
      NullPointerException - if the given internal object is null.

  • Method Details

    • clear

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

    • remove

      @NonNull public 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.
      Specified by:
      remove in interface Document.Mutable
      Parameters:
      key - the key to remove from this document.
      Returns:
      the same document instance as used to call the method, for chaining.

    • receive

      @NonNull public 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.

      Specified by:
      receive in interface Document.Mutable
      Parameters:
      send - the document send to import into this document.
      Returns:
      the same document instance as used to call the method, for chaining.

    • appendNull

      @NonNull public 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.
      Specified by:
      appendNull in interface Document.Mutable
      Parameters:
      key - the key to associate with null.
      Returns:
      the same document instance as used to call the method, for chaining.

    • appendTree

      @NonNull public 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.

      Specified by:
      appendTree in interface Document.Mutable
      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

      @NonNull public 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.

      Specified by:
      append in interface Document.Mutable
      Parameters:
      document - the document to import into this document.
      Returns:
      the same document instance as used to call the method, for chaining.

    • append

      @NonNull public 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.

      Specified by:
      append in interface Document.Mutable
      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.

    • append

      @NonNull public 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.
      Specified by:
      append in interface Document.Mutable
      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.

    • append

      @NonNull public 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.
      Specified by:
      append in interface Document.Mutable
      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.

    • append

      @NonNull public 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.
      Specified by:
      append in interface Document.Mutable
      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.

    • append

      @NonNull public 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.

      Specified by:
      append in interface Document.Mutable
      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.

    • propertyHolder

      @NonNull public Document.Mutable propertyHolder()
      Get the underlying document that all read and write operations are delegated to.
      Specified by:
      propertyHolder in interface DocPropertyHolder
      Specified by:
      propertyHolder in interface DocPropertyHolder.Mutable<Document.Mutable>
      Overrides:
      propertyHolder in class ImmutableGsonDocument
      Returns:
      the underlying document.

    • writeObject

      private void writeObject(@NonNull @NonNull ObjectOutputStream out) throws IOException
      Writes this document in a compact way to the given output stream. This method is part of the java serialisation api.
      Parameters:
      out - the target stream to write the content of this document to.
      Throws:
      IOException - if an i/o error occurs while writing the content.
      DocumentSerialisationException - if an exception occurs serialising the document.

    • readObject

      private void readObject(@NonNull @NonNull ObjectInputStream in) throws IOException
      Reads a json object from the given stream and copies all it's members into this document. This method does not take into account whether a key of the deserialized object is already present in this document. This method is part of the java serialisation api.
      Parameters:
      in - the stream to read the json content from.
      Throws:
      IOException - if an i/o error occurs while reading the document content.
      IllegalArgumentException - if the decoded json element from the stream is not a json object.