Interface MessageIncoming

    • Method Detail

      • bodyAs

        default <R extends DtoReadableFutureProgress<R> bodyAs​(java.lang.Class<R> class_)
        Requests that the incoming message body be collected and parsed as an instance of the provided class_.

        An attempt will be made to automatically resolve a default DTO encoding. If the attempt fails the method throws.

        Note that only so-called Data Transfer Object (DTO) types may be decoded using this method. More details about such types can be read in the documentation for the se.arkalix.dto package.

        Note also that a body can typically only be requested once via this interface. Any further requests will likely cause exceptions to be thrown.

        Type Parameters:
        R - Type of class_.
        Parameters:
        class_ - Class to decode incoming message body into.
        Returns:
        Future completed when the incoming message body has been fully received and then decoded into an instance of class_.
        Throws:
        MessageException - If no default encoding can be acquired.
        java.lang.IllegalStateException - If the body has already been requested.
      • bodyAs

        <R extends DtoReadableFutureProgress<R> bodyAs​(DtoEncoding encoding,
                                                         java.lang.Class<R> class_)
        Requests that the incoming message body be collected and parsed using encoding as an instance of the provided class_.

        Note that only so-called Data Transfer Object (DTO) types may be decoded using this method. More details about such types can be read in the documentation for the se.arkalix.dto package.

        Note also that a body can typically only be requested once via this interface. Any further requests will likely cause exceptions to be thrown.

        Type Parameters:
        R - Type of class_.
        Parameters:
        encoding - Encoding to use when decoding incoming message body.
        class_ - Class to decode incoming message body into.
        Returns:
        Future completed when the incoming message body has been fully received and then decoded into an instance of class_.
        Throws:
        java.lang.IllegalStateException - If the body has already been requested.
      • bodyAsByteArray

        FutureProgress<byte[]> bodyAsByteArray()
        Requests that the incoming message body be collected into a regular Java byte array (byte[]).

        Note that a body can typically only be requested once via this interface. Any further requests will likely cause exceptions to be thrown.

        Returns:
        Future completed when the incoming message body has been fully collected into a single byte array.
        Throws:
        java.lang.IllegalStateException - If the body has already been requested.
      • bodyAsList

        default <R extends DtoReadableFutureProgress<java.util.List<R>> bodyAsList​(java.lang.Class<R> class_)
        Requests that the incoming message body be collected and parsed as a list of instances of the provided class_.

        An attempt will be made to automatically resolve a default DTO encoding. If the attempt fails the method throws.

        Note that only so-called Data Transfer Object (DTO) types may be decoded using this method. More details about such types can be read in the documentation for the se.arkalix.dto package.

        Note also that a body can typically only be requested once via this interface. Any further requests will likely cause exceptions to be thrown.

        Type Parameters:
        R - Type of class_.
        Parameters:
        class_ - Class to decode incoming message body into.
        Returns:
        Future completed when the incoming message body has been fully received and then decoded into an instance of class_.
        Throws:
        MessageException - If no default encoding can be acquired.
        java.lang.IllegalStateException - If the body has already been requested.
      • bodyAsList

        <R extends DtoReadableFutureProgress<java.util.List<R>> bodyAsList​(DtoEncoding encoding,
                                                                             java.lang.Class<R> class_)
        Requests that the incoming message body be collected and parsed using encoding as a list of instances of the provided class_.

        Note that only so-called Data Transfer Object (DTO) types may be decoded using this method. More details about such types can be read in the documentation for the se.arkalix.dto package.

        Note also that a body can typically only be requested once via this interface. Any further requests will likely cause exceptions to be thrown.

        Type Parameters:
        R - Type of class_.
        Parameters:
        encoding - Encoding to use when decoding incoming message body.
        class_ - Class to decode list elements of incoming message body into.
        Returns:
        Future completed when the incoming message body has been fully received and then decoded into instances of class_.
        Throws:
        java.lang.IllegalStateException - If the body has already been requested.
      • bodyAsStream

        FutureProgress<? extends java.io.InputStream> bodyAsStream()
        Requests that the incoming message body be collected into a regular Java InputStream.

        The returned Future is not completed with the stream until the incoming body has been received in full. However, in comparison to bodyAsByteArray(), this method does not necessitate copying the body into a contiguous byte array, which in some cases can lead to performance gains.

        While it would be technically possible to return an InputStream without waiting for the body to have arrived in full, reading from that stream would require blocking the current thread until more of the body arrives. That behavior does not rhyme well with the concurrency model of the Kalix library, which tries to promote avoiding blocking I/O as far as possible. If expecting to receive a very large incoming message body, consider using the bodyTo(Path, boolean) method, which writes the body directly to a file, as it arrives.

        Note that a body can typically only be requested once via this interface. Any further requests will likely cause exceptions to be thrown.

        Returns:
        Future completed when the incoming message body has been fully collected and can be presented as an input stream.
        Throws:
        java.lang.IllegalStateException - If the body has already been requested.
      • bodyAsString

        default FutureProgress<java.lang.String> bodyAsString()
        Requests that the incoming message body be decoded into a regular Java String.

        If a character encoding supported by Java is Message.encoding() specified in the message, it will be used when decoding the body into a String. In any other case, UTF-8 will be assumed to be adequate.

        Note that a body can typically only be requested once via this interface. Any further requests will likely cause exceptions to be thrown.

        Returns:
        Future completed when the incoming message body becomes has been fully collected into a String.
        Throws:
        java.lang.IllegalStateException - If the body has already been requested.
      • bodyAsString

        FutureProgress<java.lang.String> bodyAsString​(java.nio.charset.Charset charset)
        Requests that the incoming message body be decoded into a regular Java String using the specified character set.

        Note that a body can typically only be requested once via this interface. Any further requests will likely cause exceptions to be thrown.

        Returns:
        Future completed when the incoming message body becomes has been fully collected into a String.
        Throws:
        java.lang.IllegalStateException - If the body has already been requested.
      • bodyTo

        default FutureProgress<java.nio.file.Path> bodyTo​(java.nio.file.Path path)
        Requests that the incoming message body be written to the file at the specified file system path, overwriting it if it already exists.

        Note that a body can typically only be requested once via this interface. Any further requests will likely cause exceptions to be thrown.

        Parameters:
        path - Path to file to contain incoming message body.
        Returns:
        Future completed successfully with given path only if the incoming message body is fully received and written to the file at that path.
        Throws:
        java.lang.IllegalStateException - If the body has already been requested.
        See Also:
        bodyTo(Path, boolean)
      • bodyTo

        FutureProgress<java.nio.file.Path> bodyTo​(java.nio.file.Path path,
                                                  boolean append)
        Requests that the incoming message body be written to the file at the specified file system path.

        The file will be created if it does not exist. If the append parameter is true, the file is appended to rather than being overwritten.

        Using this method, or bodyTo(Path), is the preferred way of receiving data objects that are too large to realistically fit in primary memory. This as received data is written directly to the target file as it is received, rather than being buffered until all of it becomes available.

        Note that a body can typically only be requested once via this interface. Any further requests will likely cause exceptions to be thrown.

        Parameters:
        path - Path to file to contain incoming message body.
        append - If true, any existing file at path will not be overwritten, but have the incoming message body appended to it.
        Returns:
        Future completed successfully with given path only if the incoming message body is fully received and written to the file at that path.
        Throws:
        java.lang.IllegalStateException - If the body has already been requested.