Interface Document

All Superinterfaces:
DocPropertyHolder, Externalizable, Serializable
All Known Subinterfaces:
Document.Mutable
public interface Document extends DocPropertyHolder, Externalizable
The root of a document tree. A document tree consists of key-value pairs, where the keys are string and values are one of the following types:
  1. Objects
  2. Arrays
  3. Primitives
  4. Null

A document can contain multiple sub-documents which are represented as object types. Each of these nesting levels can generically be accessed by reading the document that is associated with the key rather than parsing it to a specific java representation.

Due to the fact that a document is not representing a specific implementation (for example JSON) there is no guarantee that an implementation supports all methods to read elements from the underlying configuration type. In these cases the called methods will throw an UnsupportedOperationException. If a conversion between different document types is required, use the send api as follows: 

 
   Document jsonDocument = Document.newJsonDocument().append("json_key", "Hello World!");
   Document.Mutable tomlDocument = TomlDocumentSource.newDocument().append("toml_key", "CloudNet");

   // Serializes the content of the json document into a format that
   // must be supported by all implementations. This action does not
   // affect the source document at all (all key value pairs of the
   // source document are still available after the method call)
   DocumentSend send = jsonDocument.send();

   // Puts in the serialized content of the source document into the
   // target document. If the target implementation does not support
   // all element types they might get ignored and are not available
   // in the target document. This method call will override all
   // existing value mappings if a duplicate key is encountered.
   tomlDocument.receive(send);
   Assertions.assertEquals("CloudNet", tomlDocument.getString("toml_key")); // old key is present
   Assertions.assertEquals("Hello World!", tomlDocument.getString("json_key")); // key of json document is present

   // This way a new document is created to receive the content of the
   // source document rather than appending to an existing one
   Document newTomlDocument = TomlDocumentFactory.INSTANCE.receive(send);
   Assertions.assertFalse(newTomlDocument.contains("toml_key")); // this key was not send from the json document
   Assertions.assertEquals("Hello World!", newTomlDocument.getString("json_key")); // key of json document is present

There are two versions of document implementation: a mutable (Document.Mutable) and an immutable version. The immutable version has the single constraint that there are no changes made to the document after it became immutable, which guarantees that reading from the same immutable document in multiple places will never result in a different outcome. There is no guarantee for the mutable version of the document to be thread-safe.

Since:
4.0

  • Method Details

    • emptyDocument

      @NonNull static Document.Mutable emptyDocument()
      Get the jvm static implementation of an empty document. The returned document does not take any writes into account and does always return the supplied default value when reading from it. Some methods might throw an exception when used.
      Returns:
      the jvm static empty document instance.

    • newJsonDocument

      @NonNull static Document.Mutable newJsonDocument()
      Constructs a new json document instance. The returned document is mutable.
      Returns:
      a json new document instance.

    • newDocument

      @NonNull static Document.Mutable newDocument(@NonNull @NonNull DocumentFactory factory)
      Constructs a new document instance using the given document factory.
      Parameters:
      factory - the document factory to use for creating the new document.
      Returns:
      a new document instance constructed by the given document factory.
      Throws:
      NullPointerException - if the given document factory is null.

    • factoryName

      @NonNull @NonNull String factoryName()
      Get the name of the factory that is able to construct this document type.
      Returns:
      the factory name of this document type.

    • empty

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

    • elementCount

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

    • contains

      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.
      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.
      Throws:
      NullPointerException - if the given key is null.

    • containsNonNull

      boolean containsNonNull(@NonNull @NonNull String key)
      Get if this document has a non-null value mapping for the given key. Note that the given key is not interpreted as a path.
      Parameters:
      key - the key to check if a value is present.
      Returns:
      true if this document has a non-null value mapping for the given key, false otherwise.
      Throws:
      NullPointerException - if the given key is null.

    • send

      @NonNull @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.
      Returns:
      a serialized version of this document.
      See Also:

    • immutableCopy

      @CheckReturnValue @NonNull @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.
      Returns:
      an immutable copy of this document.

    • mutableCopy

      @CheckReturnValue @NonNull 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.
      Returns:
      a mutable copy of this document.

    • keys

      @NonNull @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.
      Returns:
      a view of the registered keys in this document at the moment the method was called.

    • elements

      @NonNull @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.
      Returns:
      a view of the registered key-value pairs in this document at the moment the method was called.

    • toInstanceOf

      <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).
      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.
      Throws:
      NullPointerException - if the given type is null.

    • toInstanceOf

      <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).
      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.
      Throws:
      NullPointerException - if the given type is null.

    • toInstanceOf

      <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).
      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.
      Throws:
      NullPointerException - if the given type token is null.

    • readObject

      default <T> @UnknownNullability T readObject(@NonNull @NonNull String key, @NonNull @NonNull Type type)
      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.
      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.
      Returns:
      the converted underlying data or null if no value is associated with the given key.
      Throws:
      NullPointerException - if the given key or type is null.

    • readObject

      default <T> @UnknownNullability T readObject(@NonNull @NonNull String key, @NonNull @NonNull Class<T> type)
      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.
      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.
      Returns:
      the converted underlying data or null if no value is associated with the given key.
      Throws:
      NullPointerException - if the given key or type is null.

    • readObject

      default <T> @UnknownNullability T readObject(@NonNull @NonNull String key, @NonNull @NonNull io.leangen.geantyref.TypeToken<T> type)
      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.
      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.
      Returns:
      the converted underlying data or null if no value is associated with the given key.
      Throws:
      NullPointerException - if the given key or type is null.

    • readObject

      <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.
      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.
      Throws:
      NullPointerException - if the given key or type is null.

    • readObject

      <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.
      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.
      Throws:
      NullPointerException - if the given key or type is null.

    • readObject

      <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.
      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.
      Throws:
      NullPointerException - if the given key or type is null.

    • readDocument

      @NonNull default @NonNull Document readDocument(@NonNull @NonNull String key)
      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 never returns null, even if the given key is explicitly associated with null.
      Parameters:
      key - the key of the underlying document to read.
      Returns:
      a deserialized document of the same type as this document, or an empty document if no mapping exists.
      Throws:
      NullPointerException - if the given key is null.

    • readDocument

      @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.
      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.
      Throws:
      NullPointerException - if the given key is null.

    • readMutableDocument

      @NonNull default @NonNull Document.Mutable readMutableDocument(@NonNull @NonNull String key)
      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 never returns null, even if the given key is explicitly associated with null.
      Parameters:
      key - the key of the underlying document to read.
      Returns:
      a deserialized document of the same type as this document, or an empty document if no mapping exists.
      Throws:
      NullPointerException - if the given key is null.

    • readMutableDocument

      @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.
      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.
      Throws:
      NullPointerException - if the given key is null.

    • getByte

      default byte getByte(@NonNull @NonNull String key)
      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 0 is returned.
      Parameters:
      key - the key of the byte to read.
      Returns:
      the byte value associated with the given key or 0 if no mapping exists.
      Throws:
      NullPointerException - if the given key is null.

    • getShort

      default short getShort(@NonNull @NonNull String key)
      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 0 is returned.
      Parameters:
      key - the key of the short to read.
      Returns:
      the short value associated with the given key or 0 if no mapping exists.
      Throws:
      NullPointerException - if the given key is null.

    • getInt

      default int getInt(@NonNull @NonNull String key)
      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 0 is returned.
      Parameters:
      key - the key of the int to read.
      Returns:
      the int value associated with the given key or 0 if no mapping exists.
      Throws:
      NullPointerException - if the given key is null.

    • getLong

      default long getLong(@NonNull @NonNull String key)
      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 0 is returned.
      Parameters:
      key - the key of the long to read.
      Returns:
      the long value associated with the given key or 0 if no mapping exists.
      Throws:
      NullPointerException - if the given key is null.

    • getFloat

      default float getFloat(@NonNull @NonNull String key)
      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 0 is returned.
      Parameters:
      key - the key of the float to read.
      Returns:
      the float value associated with the given key or 0 if no mapping exists.
      Throws:
      NullPointerException - if the given key is null.

    • getDouble

      default double getDouble(@NonNull @NonNull String key)
      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 0 is returned.
      Parameters:
      key - the key of the double to read.
      Returns:
      the double value associated with the given key or 0 if no mapping exists.
      Throws:
      NullPointerException - if the given key is null.

    • getBoolean

      default boolean getBoolean(@NonNull @NonNull String key)
      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 0 is returned.
      Parameters:
      key - the key of the boolean to read.
      Returns:
      the boolean value associated with the given key or 0 if no mapping exists.
      Throws:
      NullPointerException - if the given key is null.

    • getString

      default @UnknownNullability String getString(@NonNull @NonNull String key)
      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 null is returned.
      Parameters:
      key - the key of the string to read.
      Returns:
      the string value associated with the given key or null if no mapping exists.
      Throws:
      NullPointerException - if the given key is null.

    • getByte

      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.
      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.
      Throws:
      NullPointerException - if the given key is null.

    • getShort

      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.
      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.
      Throws:
      NullPointerException - if the given key is null.

    • getInt

      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.
      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.
      Throws:
      NullPointerException - if the given key is null.

    • getLong

      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.
      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.
      Throws:
      NullPointerException - if the given key is null.

    • getFloat

      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.
      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.
      Throws:
      NullPointerException - if the given key is null.

    • getDouble

      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.
      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.
      Throws:
      NullPointerException - if the given key is null.

    • getBoolean

      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.
      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.
      Throws:
      NullPointerException - if the given key is null.

    • getString

      @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.
      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.
      Throws:
      NullPointerException - if the given key is null.

    • writeTo

      default void writeTo(@NonNull @NonNull Path path)
      Writes this document pretty into a file at the given path. If one of the parent directory does not exist it gets created as well.
      Parameters:
      path - the path to write the document to, can be relative or absolute.
      Throws:
      NullPointerException - if the given path is null.
      DocumentSerialisationException - if the document can't be written to the given path.

    • writeTo

      default void writeTo(@NonNull @NonNull OutputStream stream)
      Writes this document pretty to the given output stream.
      Parameters:
      stream - the stream to write the serialized document content to.
      Throws:
      NullPointerException - if the given stream is null.
      DocumentSerialisationException - if the document can't be written to the given stream.

    • writeTo

      default void writeTo(@NonNull @NonNull Appendable appendable)
      Appends this document pretty to the given appendable.
      Parameters:
      appendable - the appendable to append the document content to.
      Throws:
      NullPointerException - if the given appendable is null.
      DocumentSerialisationException - if the document can't be written to the given appendable.

    • writeTo

      default void writeTo(@NonNull DataBuf.Mutable dataBuf)
      Writes this document compact as a string to the given data buffer.
      Parameters:
      dataBuf - the data buffer to write the document content to.
      Throws:
      NullPointerException - if the given data buf is null.
      DocumentSerialisationException - if the document can't be written to the given data buf.

    • serializeToString

      @NonNull default @NonNull String serializeToString()
      Serializes this document to a pretty string.
      Returns:
      a pretty serialized string based on this document.
      Throws:
      DocumentSerialisationException - if the document can't be serialized.

    • writeTo

      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.
      Parameters:
      path - the path to write the document to, can be relative or absolute.
      style - the serialization style to use when writing the document.
      Throws:
      NullPointerException - if the given path or style is null.
      DocumentSerialisationException - if the document can't be written to the given path.
      UnsupportedOperationException - if the given serialisation style is not supported.

    • writeTo

      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.
      Parameters:
      stream - the stream to write the serialized document content to.
      style - the serialization style to use when writing the document.
      Throws:
      NullPointerException - if the given stream or style is null.
      DocumentSerialisationException - if the document can't be written to the given stream.
      UnsupportedOperationException - if the given serialisation style is not supported.

    • writeTo

      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.
      Parameters:
      appendable - the appendable to write the serialized document content to.
      style - the serialization style to use when writing the document.
      Throws:
      NullPointerException - if the given appendable or style is null.
      DocumentSerialisationException - if the document can't be written to the given appendable.
      UnsupportedOperationException - if the given serialisation style is not supported.

    • writeTo

      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.
      Parameters:
      dataBuf - the data buffer to write the document content to.
      style - the serialization style to use when writing the document.
      Throws:
      NullPointerException - if the given data buf or style is null.
      DocumentSerialisationException - if the document can't be written to the given data buf.
      UnsupportedOperationException - if the given serialisation style is not supported.

    • serializeToString

      @NonNull @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.
      Parameters:
      style - the serialization style to use when writing the document.
      Returns:
      a serialized string with the given style based on this document.
      Throws:
      NullPointerException - if the given style is null.
      DocumentSerialisationException - if the document can't be serialized.
      UnsupportedOperationException - if the given serialisation style is not supported.

    • toString

      @NonNull @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 serializeToString(SerialisationStyle) with the COMPACT standard serialisation style instead.
      Overrides:
      toString in class Object
      Returns:
      a compact serialized string based on this document.
      Throws:
      DocumentSerialisationException - if the document can't be serialized.

    • equals

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