Package de.aristaflow.adept2.util.io

Class RereadableContentBuilder

  • All Implemented Interfaces:
    Closeable, AutoCloseable
    public class RereadableContentBuilder
extends Object
implements Closeable
    A RereadableContentBuilder provides the means for creating RereadableContent. It accepts data via an OutputStream or an InputStream (or both) and provides a RereadableContent for this. The data is either stored in memory or in a temporary file depending on the size. So the configuration of a RereadableContentBuilder consists of the (expected) size of the data, directory and hints for the name for creating the temporary file.
    When using an output stream, the file configuration cannot be changed after creating the output stream. An input stream can be provided (or changed) until building. If there is data provided via output and input stream, the input stream data will be appended to the output stream. This requires to output stream to be unclosed.

    A RereadableContentBuilder provides wrapping of RereadableContent. For this provide an input stream from an existing RereadableContent without any additional data. This will ignore the file configuration of the RereadableContentBuilde and return a lightweight RereadableContent that will use the wrapped one for content handling. When providing additional data via output stream, the input stream will be handled like a normal input stream, that is, its data will be appended and the file configuration will apply.

    This class is not thread-safe, so build only from the very same thread.

    This class is inspired by DeferredFileOutputStream.

    See Also:
    StreamTools.getMemStreamThreshold()

    • Field Detail

      • TIMESTAMP_FORMATTER

        protected static final DateTimeFormatter TIMESTAMP_FORMATTER
        The format for the date/time used for the names of temporary files for RereadableContent. This helps to identify the files.

      • TEMP_DIR

        protected static final File TEMP_DIR
        The JVM-wide directory for temporary files.

      • size

        protected final long size
        The estimated size of (the contents of) the created stream, a negative value if the size is unknown.

      • cleanup

        protected final Cleanup<IOException> cleanup
        The clean-up called as post-mortem action of this RereadableContentBuilder closing the streams (if not used) and deleting the temporary file if appropriate.

    • Constructor Detail

      • RereadableContentBuilder

        public RereadableContentBuilder()
        Creates a new RereadableContentBuilder with the file having a (unique) standard name containing creation date/time and being stored in the system default directory for temporary files unless reconfigured. It will switch from memory data to file storing as soon as its size reaches the StreamTools.getMemStreamThreshold().

      • RereadableContentBuilder

        public RereadableContentBuilder​(long size)
        Creates a new RereadableContentBuilder with the file having a (unique) standard name containing creation date/time and being stored in the system default directory for temporary files unless reconfigured. It is either stored in memory or in file storage depending on the designated size and the StreamTools.getMemStreamThreshold(). If a valid size (>= 0) is provided the storage will be used right from the beginning and the threshold will be set to either -1 or 0. Otherwise storage may change when writing the data.
        Parameters:
        size - The estimated size of (the contents of) the created stream. Use a negative value if the size is unknown.

    • Method Detail

      • tempDir

        public RereadableContentBuilder tempDir​(File tempDir)
        Sets the directory to store the temporary file. null resets the previously set directory and uses the standard temp directory.
        Parameters:
        tempDir - The directory to store the temporary file. If this is null, the default directory for temporary files of the system will be used.
        Returns:
        This RereadableContentBuilder.
        Throws:
        IllegalArgumentException - If this RereadableContenBuilder has already been closed or an output stream has already been created or this has been already closed or the designated directory refers to an existing file, an IllegalArgumentException will be thrown.

      • tempFileTag

        public RereadableContentBuilder tempFileTag​(String tempFileTag)
        Sets a part of the file name of the created temporary file to identify it. null removes the previously set part of the file name. Obviously, the files cannot be distinguished based on their usage then.
        Parameters:
        tempFileTag - Part of the file name of the created temporary file. If this is null, no special tag will be used.
        Returns:
        This RereadableContentBuilder.
        Throws:
        IllegalArgumentException - If this RereadableContenBuilder has already been closed or an output stream has already been created or this has been already closed or the designated directory refers to an existing file, an IllegalArgumentException will be thrown.

      • data

        public RereadableContentBuilder data​(InputStream data)
        Sets the data to the designated one or appends this data to the output stream when building the RereadableContent. null will remove this (additional) data.
        Parameters:
        data - The data for the RereadableContent to be appended to the output stream or null to remove any previously set data. The stream will be closed after building (or when closing this builder).
        Returns:
        This RereadableContentBuilder.
        Throws:
        IllegalArgumentException - If this RereadableContenBuilder has already been closed or an output stream exists and it has been already closed, an IllegalArgumentException will be thrown.

      • build

        public RereadableContent build()
                        throws IOException
        Builds a RereadableContent from the current configuration and provided data. If a RereadableContent has already been built, this instance will be returned.
        Note that after the RereadableContent has been closed, the returned one here will also be closed.

        Building will write provided data to a new or an existing output stream. If such an output stream exists, it must not be closed. It may contain data, to which the input stream data will be appended. When building the output stream will be closed and its content (usually byte[] or Path) will be used to create a new RereadableContent.
        A special case is the provision of a RereadableContent.RrcInputStream which wraps an existing RereadableContent. In this case the file configuration will be ignored and the created RereadableContent will simply wrap the provided one and delegate input stream retrieval. This avoids duplicating the content while correctly tracking input stream creation Obviously, with existing content in the output stream, the content of a RrcInputStream will be appended and its wrapped RereadableContent will be ignored.

        Returns:
        A new (or previously built) RereadableContent containing the content provided to this RereadableContentBuilder.
        Throws:
        IOException - If the builder is in a state that does not allow for building, creating the file for storing or one of its directories or transferring the data(java.io.InputStream) fails or there are problems creating the RereadableContent, an IOException will be thrown.

      • getOutputStream

        public OutputStream getOutputStream()
                             throws IOException
        Gets a new existing output stream for writing via OutputStream instead or additionally to providing an input stream. This method can only be called once to prevent concurrent writing of the output stream.
        Returns:
        The output stream accepting the content of the RereadableContent.
        Throws:
        IOException - If the RereadableContentBuilder has already been closed, there are problems creating the output stream or an output stream already exists, an IOException will be thrown.