Interface DocumentFactory

public interface DocumentFactory
A factory for documents. Documents can be created from various input sources as well as completely empty. A factory can only produce documents for a single type.
Since:
4.0

  • Method Details

    • json

      @NonNull static @NonNull DocumentFactory json()
      Gets the jvm static document factory for json documents.
      Returns:
      the jvm static document factory for json documents.

    • formatName

      @NonNull @NonNull String formatName()
      Get the name of the format that this factory produces documents for.
      Returns:
      the name of the format this factory produces documents for.

    • parse

      @NonNull Document.Mutable parse(byte[] data)
      Parses a document of the factory supported document type from the given input data. The given data must be the root object of a document in order to work. If possible it should be preferred to read the data from a stream to prevent large heap allocations.
      Parameters:
      data - the data to parse the document from.
      Returns:
      a parsed document from the given input data.
      Throws:
      DocumentParseException - if the document cannot be parsed from the given data.

    • parse

      @NonNull Document.Mutable parse(@NonNull @NonNull Path path)
      Parses a document of the factory supported document type from the file at the given path. The given data must be the root object of a document in order to work. Note: if the file at the given does not exist or the given path is a directory, this method returns a new, empty document from this factory (as specified by newDocument()). However, this method invocation will fail in case the current jvm does not have the appropriate privileges that would allow it open the file for reading.
      Parameters:
      path - the path to the file to parse.
      Returns:
      a parsed document from the file at the given path.
      Throws:
      NullPointerException - if the given path is null.
      DocumentParseException - if the document cannot be parsed from the given path.

    • parse

      @NonNull Document.Mutable parse(@NonNull @NonNull String data)
      Parses a document of the factory supported document type from the given string. The given data must be the root object of a document in order to work. If possible it should be preferred to read the data from a stream to prevent large heap allocations.
      Parameters:
      data - the string data to read the document from.
      Returns:
      a parsed document from the given data.
      Throws:
      NullPointerException - if the given data is null.
      DocumentParseException - if the document cannot be parsed from the given data.

    • parse

      @NonNull Document.Mutable parse(@NonNull @NonNull Reader reader)
      Parses a document of the factory supported document type from the given reader. The given data must be the root object of a document in order to work.
      Parameters:
      reader - a reader of the data to read the document from.
      Returns:
      a parsed document from the given data.
      Throws:
      NullPointerException - if the given reader is null.
      DocumentParseException - if the document cannot be parsed from the given data.

    • parse

      @NonNull Document.Mutable parse(@NonNull @NonNull InputStream stream)
      Parses a document of the factory supported document type from the given input stream. The given data must be the root object of a document in order to work.
      Parameters:
      stream - a stream of the data to read the document from.
      Returns:
      a parsed document from the given data.
      Throws:
      NullPointerException - if the given stream is null.
      DocumentParseException - if the document cannot be parsed from the given data.

    • parse

      @NonNull Document.Mutable parse(@NonNull @NonNull DataBuf dataBuf)
      Parses a document of the factory supported document type from the given data buf. The given data must be the root object of a document in order to work. This method will read one string from the given buffer and parse that.
      Parameters:
      dataBuf - the data buf to read a string to parse from.
      Returns:
      a parsed document from the data in the given buffer.
      Throws:
      NullPointerException - if the given data buf is null.
      DocumentParseException - if the document cannot be parsed from the given data.

    • newDocument

      @NonNull Document.Mutable newDocument()
      Creates a new, completely empty document of the factory supported document type.
      Returns:
      a new, completely empty document.

    • newDocument

      @NonNull Document.Mutable newDocument(@Nullable @Nullable Object wrapped)
      Creates a new, completely empty document and appends the tree of the given object to the document. See Document.Mutable.appendTree(Object) for more information. If the given initial object is null, this method does the same as newDocument().
      Parameters:
      wrapped - the object to initially append the tree of.
      Returns:
      a new document with the tree of the given object appended.

    • newDocument

      @NonNull Document.Mutable newDocument(@NonNull @NonNull String key, @Nullable @Nullable Object value)
      Creates a new, completely empty document and appends the given key-value pair initially to it. If the given initial value is null then null will be associated with the given key unless null values are not supported by this document type.
      Parameters:
      key - the key of the initial mapping.
      value - the value of the initial mapping.
      Returns:
      a new document with the given key-value pair initially appended.
      Throws:
      NullPointerException - if the given key is null.

    • receive

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

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

      Parameters:
      send - the document send to import into this document.
      Returns:
      a new, empty document containing all supported key-value pairs of the given document send.
      Throws:
      NullPointerException - if the given send is null.