Package eu.cloudnetservice.driver.document.gson

Class ImmutableGsonDocument

java.lang.Object
eu.cloudnetservice.driver.document.gson.ImmutableGsonDocument
All Implemented Interfaces:
Document, DefaultedDocPropertyHolder, DocPropertyHolder, Serializable
Direct Known Subclasses:
MutableGsonDocument
class ImmutableGsonDocument extends Object implements Document, DefaultedDocPropertyHolder
Immutable version of a gson document implementing the full document functionality.
Since:
4.0

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      See Also:

    • internalObject

      protected final com.google.gson.JsonObject internalObject

  • Constructor Details

    • ImmutableGsonDocument

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

    • ImmutableGsonDocument

      ImmutableGsonDocument(@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

    • factoryName

      @NonNull public @NonNull String factoryName()
      Get the name of the factory that is able to construct this document type.
      Specified by:
      factoryName in interface Document
      Returns:
      the factory name of this document type.

    • empty

      public boolean empty()
      Get if the document is empty (therefore has no key-value mappings present).
      Specified by:
      empty in interface Document
      Returns:
      true if the document is empty, false otherwise.

    • elementCount

      public int elementCount()
      Get the amount of key-value mappings that are present in the document. Zero indicates that the document is empty.
      Specified by:
      elementCount in interface Document
      Returns:
      the amount of key-value mappings in this document.

    • contains

      public boolean contains(@NonNull @NonNull String key)
      Get if this document has a value mapping for the given key. Note that the given key is not interpreted as a path.
      Specified by:
      contains in interface Document
      Parameters:
      key - the key to check if a value is present.
      Returns:
      true if this document has a value mapping for the given key, false otherwise.

    • send

      @NonNull public @NonNull DocumentSend send()
      Converts this document into a version that can be cross-handled by other document implementations. The serialized form of this document can be used to convert it to a different type of document. Note that the returned form is a snapshot of the document at the time the method was called. Any changes made to this document after the method call are not reflected into the document send.
      Specified by:
      send in interface Document
      Returns:
      a serialized version of this document.
      See Also:

    • immutableCopy

      @NonNull public @NonNull Document immutableCopy()
      Makes an immutable copy of this document. Changes to this document (in case it is mutable) are not reflected into the returned document and vice-versa.
      Specified by:
      immutableCopy in interface Document
      Returns:
      an immutable copy of this document.

    • mutableCopy

      @NonNull public Document.Mutable mutableCopy()
      Makes a mutable copy of this document. Changes to this document (in case it is mutable) are not reflected into the returned document and vice-versa.
      Specified by:
      mutableCopy in interface Document
      Returns:
      a mutable copy of this document.

    • keys

      @NonNull public @Unmodifiable @NonNull Set<String> keys()
      Get a snapshot view of the keys that are registered in this document at the moment this method was called. New keys that are registered after the method call are not reflecting into the returned collection and vice-versa.
      Specified by:
      keys in interface Document
      Returns:
      a view of the registered keys in this document at the moment the method was called.

    • elements

      @NonNull public @Unmodifiable @NonNull Collection<? extends Element> elements()
      Get a snapshot of all serialized key-value pairs registered in this document at the moment this method was called. New pairs that are registered after the method call are not reflecting into the returned collection and vice-versa.
      Specified by:
      elements in interface Document
      Returns:
      a view of the registered key-value pairs in this document at the moment the method was called.

    • toInstanceOf

      public <T> @UnknownNullability T toInstanceOf(@NonNull @NonNull Type type)
      Converts the underlying key-value mappings to an instance of the given type. Note that the type must represent an object and cannot be of any other type (like an array or primitive type).
      Specified by:
      toInstanceOf in interface Document
      Type Parameters:
      T - the type to model from the underlying data.
      Parameters:
      type - the type to construct from the underlying key-value data.
      Returns:
      the constructed instance of the given type.

    • toInstanceOf

      public <T> @UnknownNullability T toInstanceOf(@NonNull @NonNull Class<T> type)
      Converts the underlying key-value mappings to an instance of the given type. Note that the type must represent an object and cannot be of any other type (like an array or primitive type).
      Specified by:
      toInstanceOf in interface Document
      Type Parameters:
      T - the type to model from the underlying data.
      Parameters:
      type - the type to construct from the underlying key-value data.
      Returns:
      the constructed instance of the given type.

    • toInstanceOf

      public <T> @UnknownNullability T toInstanceOf(@NonNull @NonNull io.leangen.geantyref.TypeToken<T> type)
      Converts the underlying key-value mappings to an instance of the given type. Note that the type must represent an object and cannot be of any other type (like an array or primitive type).
      Specified by:
      toInstanceOf in interface Document
      Type Parameters:
      T - the type to model from the underlying data.
      Parameters:
      type - the type to construct from the underlying key-value data.
      Returns:
      the constructed instance of the given type.

    • readObject

      public <T> @UnknownNullability T readObject(@NonNull @NonNull String key, @NonNull @NonNull Type type, @Nullable T def)
      Reads the associated value of the given key and converts it to the given type model. Note that this method is able to read all kinds of types, including arrays, primitives i.a. If an object is requested and a key is missing from the underlying mapping, it is up to the implementation to handle the case. In normal cases a default (fallback) value should get used instead.
      Specified by:
      readObject in interface Document
      Type Parameters:
      T - the type to model from the underlying data.
      Parameters:
      key - the key of the underlying object to convert.
      type - the type to convert the underlying data mapping to.
      def - the default value to return if no mapping exists for the given key.
      Returns:
      the converted underlying data or the given default value if no value is associated with the given key.

    • readObject

      public <T> @UnknownNullability T readObject(@NonNull @NonNull String key, @NonNull @NonNull Class<T> type, @Nullable T def)
      Reads the associated value of the given key and converts it to the given type model. Note that this method is able to read all kinds of types, including arrays, primitives i.a. If an object is requested and a key is missing from the underlying mapping, it is up to the implementation to handle the case. In normal cases a default (fallback) value should get used instead.
      Specified by:
      readObject in interface Document
      Type Parameters:
      T - the type to model from the underlying data.
      Parameters:
      key - the key of the underlying object to convert.
      type - the type to convert the underlying data mapping to.
      def - the default value to return if no mapping exists for the given key.
      Returns:
      the converted underlying data or the given default value if no value is associated with the given key.

    • readObject

      public <T> @UnknownNullability T readObject(@NonNull @NonNull String key, @NonNull @NonNull io.leangen.geantyref.TypeToken<T> type, @Nullable T def)
      Reads the associated value of the given key and converts it to the given type model. Note that this method is able to read all kinds of types, including arrays, primitives i.a. If an object is requested and a key is missing from the underlying mapping, it is up to the implementation to handle the case. In normal cases a default (fallback) value should get used instead.
      Specified by:
      readObject in interface Document
      Type Parameters:
      T - the type to model from the underlying data.
      Parameters:
      key - the key of the underlying object to convert.
      type - the type to convert the underlying data mapping to.
      def - the default value to return if no mapping exists for the given key.
      Returns:
      the converted underlying data or the given default value if no value is associated with the given key.

    • readDocument

      public @UnknownNullability Document readDocument(@NonNull @NonNull String key, @Nullable @Nullable Document def)
      Reads a document of the same type from this document or returns an empty document if no value is associated with the given key. This method returns the given default value, even if the given key is explicitly associated with null.
      Specified by:
      readDocument in interface Document
      Parameters:
      key - the key of the underlying document to read.
      def - the default value to return if the no mapping for the given key exists.
      Returns:
      a deserialized document of the same type as this document, or the given default value if no mapping exists.

    • readMutableDocument

      public @UnknownNullability Document.Mutable readMutableDocument(@NonNull @NonNull String key, @Nullable Document.Mutable def)
      Reads a mutable document of the same type from this document or returns an empty document if no value is associated with the given key. This method returns the given default value, even if the given key is explicitly associated with null.
      Specified by:
      readMutableDocument in interface Document
      Parameters:
      key - the key of the underlying document to read.
      def - the default value to return if the no mapping for the given key exists.
      Returns:
      a deserialized document of the same type as this document, or the given default value if no mapping exists.

    • getByte

      public byte getByte(@NonNull @NonNull String key, byte def)
      Reads a byte that is associated with the given key from this document. If no value is associated with the given key or the associated value is not a number then the given default value is returned.
      Specified by:
      getByte in interface Document
      Parameters:
      key - the key of the byte to read.
      def - the default value to return if no mapping exists.
      Returns:
      the byte value associated with the given key or the given default value if no mapping exists.

    • getShort

      public short getShort(@NonNull @NonNull String key, short def)
      Reads a short that is associated with the given key from this document. If no value is associated with the given key or the associated value is not a number then the given default value is returned.
      Specified by:
      getShort in interface Document
      Parameters:
      key - the key of the short to read.
      def - the default value to return if no mapping exists.
      Returns:
      the short value associated with the given key or the given default value if no mapping exists.

    • getInt

      public int getInt(@NonNull @NonNull String key, int def)
      Reads an int that is associated with the given key from this document. If no value is associated with the given key or the associated value is not a number then the given default value is returned.
      Specified by:
      getInt in interface Document
      Parameters:
      key - the key of the int to read.
      def - the default value to return if no mapping exists.
      Returns:
      the int value associated with the given key or the given default value if no mapping exists.

    • getLong

      public long getLong(@NonNull @NonNull String key, long def)
      Reads a long that is associated with the given key from this document. If no value is associated with the given key or the associated value is not a number then the given default value is returned.
      Specified by:
      getLong in interface Document
      Parameters:
      key - the key of the long to read.
      def - the default value to return if no mapping exists.
      Returns:
      the long value associated with the given key or the given default value if no mapping exists.

    • getFloat

      public float getFloat(@NonNull @NonNull String key, float def)
      Reads a float that is associated with the given key from this document. If no value is associated with the given key or the associated value is not a number then the given default value is returned.
      Specified by:
      getFloat in interface Document
      Parameters:
      key - the key of the float to read.
      def - the default value to return if no mapping exists.
      Returns:
      the float value associated with the given key or the given default value if no mapping exists.

    • getDouble

      public double getDouble(@NonNull @NonNull String key, double def)
      Reads a double that is associated with the given key from this document. If no value is associated with the given key or the associated value is not a number then the given default value is returned.
      Specified by:
      getDouble in interface Document
      Parameters:
      key - the key of the double to read.
      def - the default value to return if no mapping exists.
      Returns:
      the double value associated with the given key or the given default value if no mapping exists.

    • getBoolean

      public boolean getBoolean(@NonNull @NonNull String key, boolean def)
      Reads a boolean that is associated with the given key from this document. If no value is associated with the given key or the associated value is not a number then the given default value is returned.
      Specified by:
      getBoolean in interface Document
      Parameters:
      key - the key of the boolean to read.
      def - the default value to return if no mapping exists.
      Returns:
      the boolean value associated with the given key or the given default value if no mapping exists.

    • getString

      public @UnknownNullability String getString(@NonNull @NonNull String key, @Nullable @Nullable String def)
      Reads a string that is associated with the given key from this document. If no value is associated with the given key or the associated value is not a string then the given default value is returned.
      Specified by:
      getString in interface Document
      Parameters:
      key - the key of the string to read.
      def - the default value to return if no mapping exists.
      Returns:
      the string value associated with the given key or the given default value if no mapping exists.

    • getPrimitiveElement

      @Nullable private @Nullable com.google.gson.JsonPrimitive getPrimitiveElement(@NonNull @NonNull String key)
      Internal helper method to get a json element as JsonPrimitive if it is one, else returns null. This method is purely to make the code in the methods that return primitive values more readable and should not be used externally.
      Parameters:
      key - the key of the json primitive to get.
      Returns:
      the json primitive instance of the json element associated with the key, null if not a primitive entry.
      Throws:
      NullPointerException - if the given key is null.

    • getElementSafe

      @NonNull private @NonNull com.google.gson.JsonElement getElementSafe(@NonNull @NonNull String key)
      Internal helper method to safely read a json element from the underlying json object. In comparison to the JsonObject.get(String) method, this method returns the jvm-static JsonNull instance if no element with the given key exists.
      Parameters:
      key - the key to get the json element of.
      Returns:
      the json element associated with the key, or the jvm-static JsonNull instance if no mapping exists.
      Throws:
      NullPointerException - if the given key is null.

    • writeTo

      public void writeTo(@NonNull @NonNull Path path, @NonNull @NonNull SerialisationStyle style)
      Writes this document with the given style into a file at the given path. If one of the parent directory does not exist it gets created as well. Not every custom serialisation style is supported, but at least the standard styles must be supported.
      Specified by:
      writeTo in interface Document
      Parameters:
      path - the path to write the document to, can be relative or absolute.
      style - the serialization style to use when writing the document.

    • writeTo

      public void writeTo(@NonNull @NonNull OutputStream stream, @NonNull @NonNull SerialisationStyle style)
      Writes this document with the given style to the given output stream. Not every custom serialisation style is supported, but at least the standard styles must be supported.
      Specified by:
      writeTo in interface Document
      Parameters:
      stream - the stream to write the serialized document content to.
      style - the serialization style to use when writing the document.

    • writeTo

      public void writeTo(@NonNull @NonNull Appendable appendable, @NonNull @NonNull SerialisationStyle style)
      Appends this document with the given style to the given appendable. Not every custom serialisation style is supported, but at least the standard styles must be supported.
      Specified by:
      writeTo in interface Document
      Parameters:
      appendable - the appendable to write the serialized document content to.
      style - the serialization style to use when writing the document.

    • writeTo

      public void writeTo(@NonNull DataBuf.Mutable dataBuf, @NonNull @NonNull SerialisationStyle style)
      Writes this document with the given style as a string to the given data buffer. Not every custom serialisation style is supported, but at least the standard styles must be supported.
      Specified by:
      writeTo in interface Document
      Parameters:
      dataBuf - the data buffer to write the document content to.
      style - the serialization style to use when writing the document.

    • serializeToString

      @NonNull public @NonNull String serializeToString(@NonNull @NonNull SerialisationStyle style)
      Serializes this document to a string with the given style. Not every custom serialisation style is supported, but at least the standard styles must be supported.
      Specified by:
      serializeToString in interface Document
      Parameters:
      style - the serialization style to use when writing the document.
      Returns:
      a serialized string with the given style based on this document.

    • resolveSerialisationGsonInstance

      @NonNull private @NonNull com.google.gson.Gson resolveSerialisationGsonInstance(@NonNull @NonNull SerialisationStyle style)
      Resolves the gson instance to use to serialize this document, throwing an exception if the given serialisation style is not supported.
      Parameters:
      style - the requested serialisation style.
      Returns:
      the gson instance to use to serialize this document with the given style.
      Throws:
      NullPointerException - if the given style is null.
      UnsupportedOperationException - if the given style is not supported.

    • propertyHolder

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

    • equals

      public boolean equals(@Nullable @Nullable Object other)
      Ensures that the given object is a document of the same type and that all members of this document are present in the given other document. This method will not take entry order into account.
      Specified by:
      equals in interface Document
      Overrides:
      equals in class Object
      Parameters:
      other - the possible other document to check against.
      Returns:
      true if all members of the other document are equal to the members in this document, false otherwise.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      @NonNull public @NonNull String toString()
      Returns this document compact serialised. This method should only be used for debug reasons, as an api user you should prefer using Document.serializeToString(SerialisationStyle) with the COMPACT standard serialisation style instead.
      Specified by:
      toString in interface Document
      Overrides:
      toString in class Object
      Returns:
      a compact serialized string based on this 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.