Class TemporaryBuffer

    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) java.util.ArrayList<TemporaryBuffer.Block> blocks
      Chain of data, if we are still completely in-core; otherwise null.
      protected static int DEFAULT_IN_CORE_LIMIT
      Default limit for in-core storage.
      private int inCoreLimit
      Maximum number of bytes we will permit storing in memory.
      private int initialBlocks
      Initial size of block list.
      private java.io.OutputStream overflow
      If inCoreLimit has been reached, remainder goes here.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected TemporaryBuffer​(int limit)
      Create a new empty temporary buffer.
      protected TemporaryBuffer​(int estimatedSize, int limit)
      Create a new empty temporary buffer.
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      void copy​(java.io.InputStream in)
      Copy all bytes remaining on the input stream into this buffer.
      void destroy()
      Clear this buffer so it has no data, and cannot be used again.
      protected void doFlush()
      Dumps the entire buffer into the overflow stream, and flushes it.
      private long inCoreLength()  
      private TemporaryBuffer.Block last()  
      long length()
      Obtain the length (in bytes) of the buffer.
      java.io.InputStream openInputStream()
      Open an input stream to read from the buffered data.
      java.io.InputStream openInputStreamWithAutoDestroy()
      Same as openInputStream() but handling destruction of any associated resources automatically when closing the returned stream.
      protected abstract java.io.OutputStream overflow()
      Open the overflow output stream, so the remaining output can be stored.
      private boolean reachedInCoreLimit()  
      void reset()
      Reset this buffer for reuse, purging all buffered content.
      private void switchToOverflow()  
      byte[] toByteArray()
      Convert this buffer's contents into a contiguous byte array.
      byte[] toByteArray​(int limit)
      Convert this buffer's contents into a contiguous byte array.
      java.lang.String toString​(int limit)
      Convert first limit number of bytes of the buffer content to String.
      void write​(byte[] b, int off, int len)
      void write​(int b)
      void writeTo​(java.io.OutputStream os, ProgressMonitor pm)
      Send this buffer to an output stream.
      • Methods inherited from class java.io.OutputStream

        flush, nullOutputStream, write
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • DEFAULT_IN_CORE_LIMIT

        protected static final int DEFAULT_IN_CORE_LIMIT
        Default limit for in-core storage.
        See Also:
        Constant Field Values
      • blocks

        java.util.ArrayList<TemporaryBuffer.Block> blocks
        Chain of data, if we are still completely in-core; otherwise null.
      • inCoreLimit

        private int inCoreLimit
        Maximum number of bytes we will permit storing in memory.

        When this limit is reached the data will be shifted to a file on disk, preventing the JVM heap from growing out of control.

      • initialBlocks

        private int initialBlocks
        Initial size of block list.
      • overflow

        private java.io.OutputStream overflow
        If inCoreLimit has been reached, remainder goes here.
    • Constructor Detail

      • TemporaryBuffer

        protected TemporaryBuffer​(int limit)
        Create a new empty temporary buffer.
        Parameters:
        limit - maximum number of bytes to store in memory before entering the overflow output path; also used as the estimated size.
      • TemporaryBuffer

        protected TemporaryBuffer​(int estimatedSize,
                                  int limit)
        Create a new empty temporary buffer.
        Parameters:
        estimatedSize - estimated size of storage used, to size the initial list of block pointers.
        limit - maximum number of bytes to store in memory before entering the overflow output path.
        Since:
        4.0
    • Method Detail

      • write

        public void write​(int b)
                   throws java.io.IOException
        Specified by:
        write in class java.io.OutputStream
        Throws:
        java.io.IOException
      • write

        public void write​(byte[] b,
                          int off,
                          int len)
                   throws java.io.IOException
        Overrides:
        write in class java.io.OutputStream
        Throws:
        java.io.IOException
      • doFlush

        protected void doFlush()
                        throws java.io.IOException
        Dumps the entire buffer into the overflow stream, and flushes it.
        Throws:
        java.io.IOException - the overflow stream cannot be started, or the buffer contents cannot be written to it, or it failed to flush.
      • copy

        public void copy​(java.io.InputStream in)
                  throws java.io.IOException
        Copy all bytes remaining on the input stream into this buffer.
        Parameters:
        in - the stream to read from, until EOF is reached.
        Throws:
        java.io.IOException - an error occurred reading from the input stream, or while writing to a local temporary file.
      • length

        public long length()
        Obtain the length (in bytes) of the buffer.

        The length is only accurate after close() has been invoked.

        Returns:
        total length of the buffer, in bytes.
      • inCoreLength

        private long inCoreLength()
      • toByteArray

        public byte[] toByteArray()
                           throws java.io.IOException
        Convert this buffer's contents into a contiguous byte array.

        The buffer is only complete after close() has been invoked.

        Returns:
        the complete byte array; length matches length().
        Throws:
        java.io.IOException - an error occurred reading from a local temporary file
      • toString

        public java.lang.String toString​(int limit)
        Convert first limit number of bytes of the buffer content to String.
        Parameters:
        limit - the maximum number of bytes to be converted to String
        Returns:
        first limit number of bytes of the buffer content converted to String.
        Since:
        5.12
      • toByteArray

        public byte[] toByteArray​(int limit)
                           throws java.io.IOException
        Convert this buffer's contents into a contiguous byte array. If this size of the buffer exceeds the limit only return the first limit bytes

        The buffer is only complete after close() has been invoked.

        Parameters:
        limit - the maximum number of bytes to be returned
        Returns:
        the byte array limited to limit bytes.
        Throws:
        java.io.IOException - an error occurred reading from a local temporary file
        Since:
        4.2
      • writeTo

        public void writeTo​(java.io.OutputStream os,
                            ProgressMonitor pm)
                     throws java.io.IOException
        Send this buffer to an output stream.

        This method may only be invoked after close() has completed normally, to ensure all data is completely transferred.

        Parameters:
        os - stream to send this buffer's complete content to.
        pm - if not null progress updates are sent here. Caller should initialize the task and the number of work units to length()/1024.
        Throws:
        java.io.IOException - an error occurred reading from a temporary file on the local system, or writing to the output stream.
      • openInputStream

        public java.io.InputStream openInputStream()
                                            throws java.io.IOException
        Open an input stream to read from the buffered data.

        This method may only be invoked after close() has completed normally, to ensure all data is completely transferred.

        Returns:
        a stream to read from the buffer. The caller must close the stream when it is no longer useful.
        Throws:
        java.io.IOException - an error occurred opening the temporary file.
      • openInputStreamWithAutoDestroy

        public java.io.InputStream openInputStreamWithAutoDestroy()
                                                           throws java.io.IOException
        Same as openInputStream() but handling destruction of any associated resources automatically when closing the returned stream.
        Returns:
        an InputStream which will automatically destroy any associated temporary file on close()
        Throws:
        java.io.IOException - in case of an error.
        Since:
        4.11
      • reset

        public void reset()
        Reset this buffer for reuse, purging all buffered content.
      • overflow

        protected abstract java.io.OutputStream overflow()
                                                  throws java.io.IOException
        Open the overflow output stream, so the remaining output can be stored.
        Returns:
        the output stream to receive the buffered content, followed by the remaining output.
        Throws:
        java.io.IOException - the buffer cannot create the overflow stream.
      • reachedInCoreLimit

        private boolean reachedInCoreLimit()
                                    throws java.io.IOException
        Throws:
        java.io.IOException
      • switchToOverflow

        private void switchToOverflow()
                               throws java.io.IOException
        Throws:
        java.io.IOException
      • close

        public void close()
                   throws java.io.IOException
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Overrides:
        close in class java.io.OutputStream
        Throws:
        java.io.IOException
      • destroy

        public void destroy()
        Clear this buffer so it has no data, and cannot be used again.