/*
 * Copyright (c) 2005, 2018, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package java.io;

import java.util.*;
import java.nio.charset.Charset;
import jdk.internal.access.JavaIOAccess;
import jdk.internal.access.SharedSecrets;
import sun.nio.cs.StreamDecoder;
import sun.nio.cs.StreamEncoder;

Methods to access the character-based console device, if any, associated with the current Java virtual machine.

Whether a virtual machine has a console is dependent upon the underlying platform and also upon the manner in which the virtual machine is invoked. If the virtual machine is started from an interactive command line without redirecting the standard input and output streams then its console will exist and will typically be connected to the keyboard and display from which the virtual machine was launched. If the virtual machine is started automatically, for example by a background job scheduler, then it will typically not have a console.

If this virtual machine has a console then it is represented by a unique instance of this class which can be obtained by invoking the System.console() method. If no console device is available then an invocation of that method will return null.

Read and write operations are synchronized to guarantee the atomic completion of critical operations; therefore invoking methods readLine(), readPassword(), format(), printf() as well as the read, format and write operations on the objects returned by reader() and writer() may block in multithreaded scenarios.

Invoking close() on the objects returned by the reader() and the writer() will not close the underlying stream of those objects.

The console-read methods return null when the end of the console input stream is reached, for example by typing control-D on Unix or control-Z on Windows. Subsequent read operations will succeed if additional characters are later entered on the console's input device.

Unless otherwise specified, passing a null argument to any method in this class will cause a NullPointerException to be thrown.

Security note: If an application needs to read a password or other secure data, it should use readPassword() or readPassword(String, Object...) and manually zero the returned character array after processing to minimize the lifetime of sensitive data in memory.


Console cons;
char[] passwd;
if ((cons = System.console()) != null &&
    (passwd = cons.readPassword("[%s]", "Password:")) != null) {
    ...
    java.util.Arrays.fill(passwd, ' ');
 }
Author: Xueming Shen
Since: 1.6
/** * Methods to access the character-based console device, if any, associated * with the current Java virtual machine. * * <p> Whether a virtual machine has a console is dependent upon the * underlying platform and also upon the manner in which the virtual * machine is invoked. If the virtual machine is started from an * interactive command line without redirecting the standard input and * output streams then its console will exist and will typically be * connected to the keyboard and display from which the virtual machine * was launched. If the virtual machine is started automatically, for * example by a background job scheduler, then it will typically not * have a console. * <p> * If this virtual machine has a console then it is represented by a * unique instance of this class which can be obtained by invoking the * {@link java.lang.System#console()} method. If no console device is * available then an invocation of that method will return {@code null}. * <p> * Read and write operations are synchronized to guarantee the atomic * completion of critical operations; therefore invoking methods * {@link #readLine()}, {@link #readPassword()}, {@link #format format()}, * {@link #printf printf()} as well as the read, format and write operations * on the objects returned by {@link #reader()} and {@link #writer()} may * block in multithreaded scenarios. * <p> * Invoking {@code close()} on the objects returned by the {@link #reader()} * and the {@link #writer()} will not close the underlying stream of those * objects. * <p> * The console-read methods return {@code null} when the end of the * console input stream is reached, for example by typing control-D on * Unix or control-Z on Windows. Subsequent read operations will succeed * if additional characters are later entered on the console's input * device. * <p> * Unless otherwise specified, passing a {@code null} argument to any method * in this class will cause a {@link NullPointerException} to be thrown. * <p> * <b>Security note:</b> * If an application needs to read a password or other secure data, it should * use {@link #readPassword()} or {@link #readPassword(String, Object...)} and * manually zero the returned character array after processing to minimize the * lifetime of sensitive data in memory. * * <blockquote><pre>{@code * Console cons; * char[] passwd; * if ((cons = System.console()) != null && * (passwd = cons.readPassword("[%s]", "Password:")) != null) { * ... * java.util.Arrays.fill(passwd, ' '); * } * }</pre></blockquote> * * @author Xueming Shen * @since 1.6 */
public final class Console implements Flushable {
Retrieves the unique PrintWriter object associated with this console.
Returns: The printwriter associated with this console
/** * Retrieves the unique {@link java.io.PrintWriter PrintWriter} object * associated with this console. * * @return The printwriter associated with this console */
public PrintWriter writer() { return pw; }
Retrieves the unique Reader object associated with this console.

This method is intended to be used by sophisticated applications, for example, a Scanner object which utilizes the rich parsing/scanning functionality provided by the Scanner:

Console con = System.console();
if (con != null) {
    Scanner sc = new Scanner(con.reader());
    ...
}

For simple applications requiring only line-oriented reading, use readLine.

The bulk read operations read(char[]), read(char[], int, int) and read(java.nio.CharBuffer) on the returned object will not read in characters beyond the line bound for each invocation, even if the destination buffer has space for more characters. The Reader's read methods may block if a line bound has not been entered or reached on the console's input device. A line bound is considered to be any one of a line feed ('\n'), a carriage return ('\r'), a carriage return followed immediately by a linefeed, or an end of stream.

Returns: The reader associated with this console
/** * Retrieves the unique {@link java.io.Reader Reader} object associated * with this console. * <p> * This method is intended to be used by sophisticated applications, for * example, a {@link java.util.Scanner} object which utilizes the rich * parsing/scanning functionality provided by the {@code Scanner}: * <blockquote><pre> * Console con = System.console(); * if (con != null) { * Scanner sc = new Scanner(con.reader()); * ... * } * </pre></blockquote> * <p> * For simple applications requiring only line-oriented reading, use * {@link #readLine}. * <p> * The bulk read operations {@link java.io.Reader#read(char[]) read(char[]) }, * {@link java.io.Reader#read(char[], int, int) read(char[], int, int) } and * {@link java.io.Reader#read(java.nio.CharBuffer) read(java.nio.CharBuffer)} * on the returned object will not read in characters beyond the line * bound for each invocation, even if the destination buffer has space for * more characters. The {@code Reader}'s {@code read} methods may block if a * line bound has not been entered or reached on the console's input device. * A line bound is considered to be any one of a line feed ({@code '\n'}), * a carriage return ({@code '\r'}), a carriage return followed immediately * by a linefeed, or an end of stream. * * @return The reader associated with this console */
public Reader reader() { return reader; }
Writes a formatted string to this console's output stream using the specified format string and arguments.
Params:
  • fmt – A format string as described in Format string syntax
  • args – Arguments referenced by the format specifiers in the format string. If there are more arguments than format specifiers, the extra arguments are ignored. The number of arguments is variable and may be zero. The maximum number of arguments is limited by the maximum dimension of a Java array as defined by The Java Virtual Machine Specification. The behaviour on a null argument depends on the conversion.
Throws:
  • IllegalFormatException – If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Details section of the formatter class specification.
Returns: This console
/** * Writes a formatted string to this console's output stream using * the specified format string and arguments. * * @param fmt * A format string as described in <a * href="../util/Formatter.html#syntax">Format string syntax</a> * * @param args * Arguments referenced by the format specifiers in the format * string. If there are more arguments than format specifiers, the * extra arguments are ignored. The number of arguments is * variable and may be zero. The maximum number of arguments is * limited by the maximum dimension of a Java array as defined by * <cite>The Java Virtual Machine Specification</cite>. * The behaviour on a * {@code null} argument depends on the <a * href="../util/Formatter.html#syntax">conversion</a>. * * @throws IllegalFormatException * If a format string contains an illegal syntax, a format * specifier that is incompatible with the given arguments, * insufficient arguments given the format string, or other * illegal conditions. For specification of all possible * formatting errors, see the <a * href="../util/Formatter.html#detail">Details</a> section * of the formatter class specification. * * @return This console */
public Console format(String fmt, Object ...args) { formatter.format(fmt, args).flush(); return this; }
A convenience method to write a formatted string to this console's output stream using the specified format string and arguments.

An invocation of this method of the form con.printf(format, args) behaves in exactly the same way as the invocation of

con.format(format, args)
.
Params:
  • format – A format string as described in Format string syntax.
  • args – Arguments referenced by the format specifiers in the format string. If there are more arguments than format specifiers, the extra arguments are ignored. The number of arguments is variable and may be zero. The maximum number of arguments is limited by the maximum dimension of a Java array as defined by The Java Virtual Machine Specification. The behaviour on a null argument depends on the conversion.
Throws:
  • IllegalFormatException – If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Details section of the formatter class specification.
Returns: This console
/** * A convenience method to write a formatted string to this console's * output stream using the specified format string and arguments. * * <p> An invocation of this method of the form * {@code con.printf(format, args)} behaves in exactly the same way * as the invocation of * <pre>con.format(format, args)</pre>. * * @param format * A format string as described in <a * href="../util/Formatter.html#syntax">Format string syntax</a>. * * @param args * Arguments referenced by the format specifiers in the format * string. If there are more arguments than format specifiers, the * extra arguments are ignored. The number of arguments is * variable and may be zero. The maximum number of arguments is * limited by the maximum dimension of a Java array as defined by * <cite>The Java Virtual Machine Specification</cite>. * The behaviour on a * {@code null} argument depends on the <a * href="../util/Formatter.html#syntax">conversion</a>. * * @throws IllegalFormatException * If a format string contains an illegal syntax, a format * specifier that is incompatible with the given arguments, * insufficient arguments given the format string, or other * illegal conditions. For specification of all possible * formatting errors, see the <a * href="../util/Formatter.html#detail">Details</a> section of the * formatter class specification. * * @return This console */
public Console printf(String format, Object ... args) { return format(format, args); }
Provides a formatted prompt, then reads a single line of text from the console.
Params:
  • fmt – A format string as described in Format string syntax.
  • args – Arguments referenced by the format specifiers in the format string. If there are more arguments than format specifiers, the extra arguments are ignored. The maximum number of arguments is limited by the maximum dimension of a Java array as defined by The Java Virtual Machine Specification.
Throws:
  • IllegalFormatException – If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Details section of the formatter class specification.
  • IOError – If an I/O error occurs.
Returns: A string containing the line read from the console, not including any line-termination characters, or null if an end of stream has been reached.
/** * Provides a formatted prompt, then reads a single line of text from the * console. * * @param fmt * A format string as described in <a * href="../util/Formatter.html#syntax">Format string syntax</a>. * * @param args * Arguments referenced by the format specifiers in the format * string. If there are more arguments than format specifiers, the * extra arguments are ignored. The maximum number of arguments is * limited by the maximum dimension of a Java array as defined by * <cite>The Java Virtual Machine Specification</cite>. * * @throws IllegalFormatException * If a format string contains an illegal syntax, a format * specifier that is incompatible with the given arguments, * insufficient arguments given the format string, or other * illegal conditions. For specification of all possible * formatting errors, see the <a * href="../util/Formatter.html#detail">Details</a> section * of the formatter class specification. * * @throws IOError * If an I/O error occurs. * * @return A string containing the line read from the console, not * including any line-termination characters, or {@code null} * if an end of stream has been reached. */
public String readLine(String fmt, Object ... args) { String line = null; synchronized (writeLock) { synchronized(readLock) { if (!fmt.isEmpty()) pw.format(fmt, args); try { char[] ca = readline(false); if (ca != null) line = new String(ca); } catch (IOException x) { throw new IOError(x); } } } return line; }
Reads a single line of text from the console.
Throws:
  • IOError – If an I/O error occurs.
Returns: A string containing the line read from the console, not including any line-termination characters, or null if an end of stream has been reached.
/** * Reads a single line of text from the console. * * @throws IOError * If an I/O error occurs. * * @return A string containing the line read from the console, not * including any line-termination characters, or {@code null} * if an end of stream has been reached. */
public String readLine() { return readLine(""); }
Provides a formatted prompt, then reads a password or passphrase from the console with echoing disabled.
Params:
  • fmt – A format string as described in Format string syntax for the prompt text.
  • args – Arguments referenced by the format specifiers in the format string. If there are more arguments than format specifiers, the extra arguments are ignored. The maximum number of arguments is limited by the maximum dimension of a Java array as defined by The Java Virtual Machine Specification.
Throws:
  • IllegalFormatException – If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Details section of the formatter class specification.
  • IOError – If an I/O error occurs.
Returns: A character array containing the password or passphrase read from the console, not including any line-termination characters, or null if an end of stream has been reached.
/** * Provides a formatted prompt, then reads a password or passphrase from * the console with echoing disabled. * * @param fmt * A format string as described in <a * href="../util/Formatter.html#syntax">Format string syntax</a> * for the prompt text. * * @param args * Arguments referenced by the format specifiers in the format * string. If there are more arguments than format specifiers, the * extra arguments are ignored. The maximum number of arguments is * limited by the maximum dimension of a Java array as defined by * <cite>The Java Virtual Machine Specification</cite>. * * @throws IllegalFormatException * If a format string contains an illegal syntax, a format * specifier that is incompatible with the given arguments, * insufficient arguments given the format string, or other * illegal conditions. For specification of all possible * formatting errors, see the <a * href="../util/Formatter.html#detail">Details</a> * section of the formatter class specification. * * @throws IOError * If an I/O error occurs. * * @return A character array containing the password or passphrase read * from the console, not including any line-termination characters, * or {@code null} if an end of stream has been reached. */
public char[] readPassword(String fmt, Object ... args) { char[] passwd = null; synchronized (writeLock) { synchronized(readLock) { installShutdownHook(); try { restoreEcho = echo(false); } catch (IOException x) { throw new IOError(x); } IOError ioe = null; try { if (!fmt.isEmpty()) pw.format(fmt, args); passwd = readline(true); } catch (IOException x) { ioe = new IOError(x); } finally { try { if (restoreEcho) restoreEcho = echo(true); } catch (IOException x) { if (ioe == null) ioe = new IOError(x); else ioe.addSuppressed(x); } if (ioe != null) throw ioe; } pw.println(); } } return passwd; } private void installShutdownHook() { if (shutdownHookInstalled) return; try { // Add a shutdown hook to restore console's echo state should // it be necessary. SharedSecrets.getJavaLangAccess() .registerShutdownHook(0 /* shutdown hook invocation order */, false /* only register if shutdown is not in progress */, new Runnable() { public void run() { try { if (restoreEcho) { echo(true); } } catch (IOException x) { } } }); } catch (IllegalStateException e) { // shutdown is already in progress and readPassword is first used // by a shutdown hook } shutdownHookInstalled = true; }
Reads a password or passphrase from the console with echoing disabled
Throws:
  • IOError – If an I/O error occurs.
Returns: A character array containing the password or passphrase read from the console, not including any line-termination characters, or null if an end of stream has been reached.
/** * Reads a password or passphrase from the console with echoing disabled * * @throws IOError * If an I/O error occurs. * * @return A character array containing the password or passphrase read * from the console, not including any line-termination characters, * or {@code null} if an end of stream has been reached. */
public char[] readPassword() { return readPassword(""); }
Flushes the console and forces any buffered output to be written immediately .
/** * Flushes the console and forces any buffered output to be written * immediately . */
public void flush() { pw.flush(); } private Object readLock; private Object writeLock; private Reader reader; private Writer out; private PrintWriter pw; private Formatter formatter; private Charset cs; private char[] rcb; private boolean restoreEcho; private boolean shutdownHookInstalled; private static native String encoding(); /* * Sets the console echo status to {@code on} and returns the previous * console on/off status. * @param on the echo status to set to. {@code true} for echo on and * {@code false} for echo off * @return true if the previous console echo status is on */ private static native boolean echo(boolean on) throws IOException; private char[] readline(boolean zeroOut) throws IOException { int len = reader.read(rcb, 0, rcb.length); if (len < 0) return null; //EOL if (rcb[len-1] == '\r') len--; //remove CR at end; else if (rcb[len-1] == '\n') { len--; //remove LF at end; if (len > 0 && rcb[len-1] == '\r') len--; //remove the CR, if there is one } char[] b = new char[len]; if (len > 0) { System.arraycopy(rcb, 0, b, 0, len); if (zeroOut) { Arrays.fill(rcb, 0, len, ' '); } } return b; } private char[] grow() { assert Thread.holdsLock(readLock); char[] t = new char[rcb.length * 2]; System.arraycopy(rcb, 0, t, 0, rcb.length); rcb = t; return rcb; } class LineReader extends Reader { private Reader in; private char[] cb; private int nChars, nextChar; boolean leftoverLF; LineReader(Reader in) { this.in = in; cb = new char[1024]; nextChar = nChars = 0; leftoverLF = false; } public void close () {} public boolean ready() throws IOException { //in.ready synchronizes on readLock already return in.ready(); } public int read(char cbuf[], int offset, int length) throws IOException { int off = offset; int end = offset + length; if (offset < 0 || offset > cbuf.length || length < 0 || end < 0 || end > cbuf.length) { throw new IndexOutOfBoundsException(); } synchronized(readLock) { boolean eof = false; char c = 0; for (;;) { if (nextChar >= nChars) { //fill int n = 0; do { n = in.read(cb, 0, cb.length); } while (n == 0); if (n > 0) { nChars = n; nextChar = 0; if (n < cb.length && cb[n-1] != '\n' && cb[n-1] != '\r') { /* * we're in canonical mode so each "fill" should * come back with an eol. if there no lf or nl at * the end of returned bytes we reached an eof. */ eof = true; } } else { /*EOF*/ if (off - offset == 0) return -1; return off - offset; } } if (leftoverLF && cbuf == rcb && cb[nextChar] == '\n') { /* * if invoked by our readline, skip the leftover, otherwise * return the LF. */ nextChar++; } leftoverLF = false; while (nextChar < nChars) { c = cbuf[off++] = cb[nextChar]; cb[nextChar++] = 0; if (c == '\n') { return off - offset; } else if (c == '\r') { if (off == end) { /* no space left even the next is LF, so return * whatever we have if the invoker is not our * readLine() */ if (cbuf == rcb) { cbuf = grow(); end = cbuf.length; } else { leftoverLF = true; return off - offset; } } if (nextChar == nChars && in.ready()) { /* * we have a CR and we reached the end of * the read in buffer, fill to make sure we * don't miss a LF, if there is one, it's possible * that it got cut off during last round reading * simply because the read in buffer was full. */ nChars = in.read(cb, 0, cb.length); nextChar = 0; } if (nextChar < nChars && cb[nextChar] == '\n') { cbuf[off++] = '\n'; nextChar++; } return off - offset; } else if (off == end) { if (cbuf == rcb) { cbuf = grow(); end = cbuf.length; } else { return off - offset; } } } if (eof) return off - offset; } } } } // Set up JavaIOAccess in SharedSecrets static { SharedSecrets.setJavaIOAccess(new JavaIOAccess() { public Console console() { if (istty()) { if (cons == null) cons = new Console(); return cons; } return null; } public Charset charset() { // This method is called in sun.security.util.Password, // cons already exists when this method is called return cons.cs; } }); } private static Console cons; private static native boolean istty(); private Console() { readLock = new Object(); writeLock = new Object(); String csname = encoding(); if (csname != null) { try { cs = Charset.forName(csname); } catch (Exception x) {} } if (cs == null) cs = Charset.defaultCharset(); out = StreamEncoder.forOutputStreamWriter( new FileOutputStream(FileDescriptor.out), writeLock, cs); pw = new PrintWriter(out, true) { public void close() {} }; formatter = new Formatter(out); reader = new LineReader(StreamDecoder.forInputStreamReader( new FileInputStream(FileDescriptor.in), readLock, cs)); rcb = new char[1024]; } }