Class NonBlockingInputStream

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, java.lang.Runnable

    public class NonBlockingInputStream
    extends java.io.InputStream
    implements java.lang.Runnable
    This class wraps a regular input stream and allows it to appear as if it is non-blocking; that is, reads can be performed against it that timeout if no data is seen for a period of time. This effect is achieved by having a separate thread perform all non-blocking read requests and then waiting on the thread to complete.

    VERY IMPORTANT NOTES

    • This class is not thread safe. It expects at most one reader.
    • The shutdown() method must be called in order to shut down the thread that handles blocking I/O.
    Since:
    2.7
    Author:
    Scott C. Gray
    • Constructor Summary

      Constructors 
      Constructor Description
      NonBlockingInputStream​(java.io.InputStream in, boolean isNonBlockingEnabled)
      Creates a NonBlockingInputStream out of a normal blocking stream.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()  
      boolean isNonBlockingEnabled()
      Non-blocking is considered enabled if the feature is enabled and the I/O thread has not been shut down.
      int peek​(long timeout)
      Peeks to see if there is a byte waiting in the input stream without actually consuming the byte.
      int read()  
      int read​(byte[] b, int off, int len)
      This version of read() is very specific to jline's purposes, it will always always return a single byte at a time, rather than filling the entire buffer.
      int read​(long timeout)
      Attempts to read a character from the input stream for a specific period of time.
      void run()  
      void shutdown()
      Shuts down the thread that is handling blocking I/O.
      • Methods inherited from class java.io.InputStream

        available, mark, markSupported, nullInputStream, read, readAllBytes, readNBytes, readNBytes, reset, skip, transferTo
      • Methods inherited from class java.lang.Object

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

      • NonBlockingInputStream

        public NonBlockingInputStream​(java.io.InputStream in,
                                      boolean isNonBlockingEnabled)
        Creates a NonBlockingInputStream out of a normal blocking stream. Note that this call also spawn a separate thread to perform the blocking I/O on behalf of the thread that is using this class. The shutdown() method must be called in order to shut this thread down.
        Parameters:
        in - The input stream to wrap
        isNonBlockingEnabled - If true, then the non-blocking methods read(long) and peek(long) will be available and, more importantly, the thread will be started to provide support for the feature. If false, then this class acts as a clean-passthru for the underlying I/O stream and provides very little overhead.
    • Method Detail

      • shutdown

        public void shutdown()
        Shuts down the thread that is handling blocking I/O. Note that if the thread is currently blocked waiting for I/O it will not actually shut down until the I/O is received. Shutting down the I/O thread does not prevent this class from being used, but causes the non-blocking methods to fail if called and causes isNonBlockingEnabled() to return false.
      • isNonBlockingEnabled

        public boolean isNonBlockingEnabled()
        Non-blocking is considered enabled if the feature is enabled and the I/O thread has not been shut down.
        Returns:
        true if non-blocking mode is enabled.
      • 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.InputStream
        Throws:
        java.io.IOException
      • read

        public int read()
                 throws java.io.IOException
        Specified by:
        read in class java.io.InputStream
        Throws:
        java.io.IOException
      • peek

        public int peek​(long timeout)
                 throws java.io.IOException
        Peeks to see if there is a byte waiting in the input stream without actually consuming the byte.
        Parameters:
        timeout - The amount of time to wait, 0 == forever
        Returns:
        -1 on eof, -2 if the timeout expired with no available input or the character that was read (without consuming it).
        Throws:
        java.io.IOException
      • read

        public int read​(long timeout)
                 throws java.io.IOException
        Attempts to read a character from the input stream for a specific period of time.
        Parameters:
        timeout - The amount of time to wait for the character
        Returns:
        The character read, -1 if EOF is reached, or -2 if the read timed out.
        Throws:
        java.io.IOException
      • read

        public int read​(byte[] b,
                        int off,
                        int len)
                 throws java.io.IOException
        This version of read() is very specific to jline's purposes, it will always always return a single byte at a time, rather than filling the entire buffer.
        Overrides:
        read in class java.io.InputStream
        Throws:
        java.io.IOException
      • run

        public void run()
        Specified by:
        run in interface java.lang.Runnable