Class PosixSysTerminal

  • All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable, Sized, TerminalExt, Terminal

    public class PosixSysTerminal
    extends AbstractPosixTerminal
    Terminal implementation for POSIX systems using system streams.

    The PosixSysTerminal class provides a terminal implementation for POSIX systems (Linux, macOS, etc.) that uses the system standard input and output streams. It extends the AbstractPosixTerminal class and adds functionality specific to system stream-based terminals.

    This implementation is used when connecting to the actual system terminal, such as when running a console application in a terminal window. It provides access to the standard input and output streams, allowing for interaction with the user through the terminal.

    Key features of this implementation include:

    • Direct access to system standard input and output
    • Support for terminal attributes and size changes
    • Support for non-blocking I/O
    • Automatic restoration of terminal state on shutdown
    See Also:
    AbstractPosixTerminal, Pty
    • Constructor Detail

      • PosixSysTerminal

        public PosixSysTerminal​(java.lang.String name,
                                java.lang.String type,
                                Pty pty,
                                java.nio.charset.Charset encoding,
                                boolean nativeSignals,
                                Terminal.SignalHandler signalHandler)
                         throws java.io.IOException
        Creates a POSIX system terminal backed by the provided PTY, using the same charset for input and output, and optionally enabling native signal handling.
        Parameters:
        name - the terminal name
        type - the terminal type (TERM)
        pty - the pseudo-terminal providing slave input/output streams for the terminal
        encoding - the charset used for both input and output encoding
        nativeSignals - if true, native OS signal handlers will be registered
        signalHandler - the initial handler to install for native signals
        Throws:
        java.io.IOException - if an I/O error occurs while initializing the terminal
      • PosixSysTerminal

        public PosixSysTerminal​(java.lang.String name,
                                java.lang.String type,
                                Pty pty,
                                java.nio.charset.Charset encoding,
                                java.nio.charset.Charset inputEncoding,
                                java.nio.charset.Charset outputEncoding,
                                boolean nativeSignals,
                                Terminal.SignalHandler signalHandler)
                         throws java.io.IOException
        Creates a POSIX system terminal backed by the given PTY and character encodings, without a TerminalProvider.
        Parameters:
        name - the terminal name
        type - the terminal type (TERM)
        pty - the pseudoterminal providing slave input/output streams
        encoding - the primary charset for the terminal
        inputEncoding - the charset used for input decoding
        outputEncoding - the charset used for output encoding
        nativeSignals - whether native signal handlers should be registered
        signalHandler - the initial handler to install for native signals
        Throws:
        java.io.IOException - if an I/O error occurs while initializing the terminal
      • PosixSysTerminal

        public PosixSysTerminal​(TerminalProvider provider,
                                java.lang.String name,
                                java.lang.String type,
                                Pty pty,
                                java.nio.charset.Charset encoding,
                                java.nio.charset.Charset inputEncoding,
                                java.nio.charset.Charset outputEncoding,
                                boolean nativeSignals,
                                Terminal.SignalHandler signalHandler)
                         throws java.io.IOException
        Create a POSIX system terminal backed by the provided PTY, initializing non-blocking input/output, reader/writer encodings, and optional native signal handlers.
        Parameters:
        provider - optional TerminalProvider used for native signal registration; may be null
        name - the terminal name
        type - the terminal type (TERM)
        pty - the PTY whose slave streams back this terminal
        encoding - the primary charset for the terminal
        inputEncoding - the charset used for the terminal reader
        outputEncoding - the charset used for the terminal writer
        nativeSignals - if true, register native OS signal handlers for all signals
        signalHandler - the initial handler to install for native signals; if `SignalHandler.SIG_DFL`, default native handlers will be registered
        Throws:
        java.io.IOException - if the PTY streams or terminal I/O cannot be initialized
    • Method Detail

      • getAttributes

        public Attributes getAttributes()
        Description copied from interface: Terminal
        Returns the current terminal attributes.

        Terminal attributes control various aspects of terminal behavior, including:

        • Input processing - How input characters are processed (e.g., character mapping, parity checking)
        • Output processing - How output characters are processed (e.g., newline translation)
        • Control settings - Hardware settings like baud rate and character size
        • Local settings - Terminal behavior settings like echo, canonical mode, and signal generation
        • Control characters - Special characters like EOF, interrupt, and erase

        The returned Attributes object is a copy of the terminal's current attributes and can be safely modified without affecting the terminal until it is applied using Terminal.setAttributes(Attributes). This allows for making multiple changes to the attributes before applying them all at once.

        Example usage:

         Terminal terminal = TerminalBuilder.terminal();
        
         // Get current attributes
         Attributes attrs = terminal.getAttributes();
        
         // Modify attributes
         attrs.setLocalFlag(LocalFlag.ECHO, false);      // Disable echo
         attrs.setInputFlag(InputFlag.ICRNL, false);     // Disable CR to NL mapping
         attrs.setControlChar(ControlChar.VMIN, 1);      // Set minimum input to 1 character
         attrs.setControlChar(ControlChar.VTIME, 0);     // Set timeout to 0 deciseconds
        
         // Apply modified attributes
         terminal.setAttributes(attrs);
         
        Specified by:
        getAttributes in interface Terminal
        Overrides:
        getAttributes in class AbstractPosixTerminal
        Returns:
        a copy of the terminal's current attributes
        See Also:
        Terminal.setAttributes(Attributes), Attributes, Terminal.enterRawMode()
      • setAttributes

        public void setAttributes​(Attributes attr)
        Description copied from interface: Terminal
        Sets the terminal attributes to the specified values.

        This method applies the specified attributes to the terminal, changing its behavior according to the settings in the Attributes object. The terminal makes a copy of the provided attributes, so further modifications to the attr object will not affect the terminal until this method is called again.

        Terminal attributes control various aspects of terminal behavior, including input and output processing, control settings, local settings, and special control characters. Changing these attributes allows for fine-grained control over how the terminal processes input and output.

        Common attribute modifications include:

        • Disabling echo for password input
        • Enabling/disabling canonical mode for line-by-line or character-by-character input
        • Disabling signal generation for custom handling of Ctrl+C and other control sequences
        • Changing control characters like the interrupt character or end-of-file character

        For convenience, the Terminal.enterRawMode() method provides a pre-configured set of attributes suitable for full-screen interactive applications.

        Example usage:

         Terminal terminal = TerminalBuilder.terminal();
        
         // Save original attributes for later restoration
         Attributes originalAttrs = terminal.getAttributes();
        
         try {
             // Create and configure new attributes
             Attributes attrs = new Attributes(originalAttrs);
             attrs.setLocalFlag(LocalFlag.ECHO, false);      // Disable echo for password input
             attrs.setLocalFlag(LocalFlag.ICANON, false);    // Disable canonical mode
        
             // Apply the new attributes
             terminal.setAttributes(attrs);
        
             // Use terminal with modified attributes...
         } finally {
             // Restore original attributes
             terminal.setAttributes(originalAttrs);
         }
         
        Specified by:
        setAttributes in interface Terminal
        Overrides:
        setAttributes in class AbstractPosixTerminal
        Parameters:
        attr - the attributes to apply to the terminal
        See Also:
        Terminal.getAttributes(), Attributes, Terminal.enterRawMode()
      • reader

        public NonBlockingReader reader()
        Description copied from interface: Terminal
        Retrieve the Reader for this terminal. This is the standard way to read input from this terminal. The reader is non blocking.

        The returned reader is owned by this terminal and will be closed when the terminal is closed. Callers should not close it directly.

        Returns:
        The non blocking reader
      • writer

        public java.io.PrintWriter writer()
        Description copied from interface: Terminal
        Retrieve the Writer for this terminal. This is the standard way to write to this terminal.

        The returned writer is owned by this terminal and will be closed when the terminal is closed. Callers should not close it directly.

        Returns:
        The writer
      • input

        public java.io.InputStream input()
        Description copied from interface: Terminal
        Retrieve the input stream for this terminal. In some rare cases, there may be a need to access the terminal input stream directly. In the usual cases, use the Terminal.reader() instead.

        The returned stream is owned by this terminal and will be closed when the terminal is closed. Callers should not close it directly.

        Returns:
        The input stream
        See Also:
        Terminal.reader()
      • output

        public java.io.OutputStream output()
        Description copied from interface: Terminal
        Retrieve the output stream for this terminal. In some rare cases, there may be a need to access the terminal output stream directly. In the usual cases, use the Terminal.writer() instead.

        The returned stream is owned by this terminal and will be closed when the terminal is closed. Callers should not close it directly.

        Returns:
        The output stream
        See Also:
        Terminal.writer()
      • doClose

        protected void doClose()
                        throws java.io.IOException
        Closes the terminal and releases its resources: flushes pending output, removes the shutdown hook, unregisters any native signal handlers, performs superclass shutdown, and closes the reader.
        Overrides:
        doClose in class AbstractPosixTerminal
        Throws:
        java.io.IOException - if an I/O error occurs while flushing or closing the terminal streams