Package eu.cloudnetservice.driver.document.empty

Class EmptyDocument

java.lang.Object
eu.cloudnetservice.driver.document.empty.EmptyDocument
All Implemented Interfaces:
Document, Document.Mutable, DefaultedDocPropertyHolder, DefaultedDocPropertyHolder.Mutable<Document.Mutable>, DocPropertyHolder, DocPropertyHolder.Mutable<Document.Mutable>, Serializable
public final class EmptyDocument extends Object implements Document.Mutable, DefaultedDocPropertyHolder.Mutable<Document.Mutable>
A document implementation that just ignores all calls made to it.
Since:
4.0
See Also:

  • Field Details

    • INSTANCE

      public static final Document.Mutable INSTANCE
      The jvm static instance of the empty document. There should never be a different instance of this class during the jvm lifetime.

      Note: do not use this field directly, prefer Document.emptyDocument() instead.

  • Constructor Details

    • EmptyDocument

      private EmptyDocument()
      Constructs an empty document instance. This constructor is sealed to prevent accidental instantiations. Obtain the singleton instance of this implementation via Document.emptyDocument().

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

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

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

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