Flushable
, ConfigurableSensibleUi
, SensibleUi
public final class DefaultConfigurableSensibleUi extends Object implements ConfigurableSensibleUi
This is the default implementation of the ConfigurableSensibleUi
interface (and the SensibleUi
interface).
Use a Builder
to construct an instance of this class, or use
the create()
static factory method to
construct a default instance.
Writing to the standard output stream and standard error stream
Appendable
instances may throw an exception due to an I/O error. If
this is not the desired behavior, a different Appendable
can be
supplied to the builder that prevents such exceptions from being thrown
(e.g., a PrintWriter
).
If an exception stack trace is printed, the stream on which it is printed will be flushed after printing it. Also, the system locale will be used when printing the stack trace, not the locale of this UI.
This class is conditionally thread-safe. All methods may be called
concurrently. Output to the standard output stream and standard error stream
is guarded by a lock to ensure output on a terminal is not corrupted (e.g.,
two messages character-interleaved on the same line). The
prompt(String, String)
and
promptChoice(String, int, String)
methods may block waiting for
user input if this UI has been created with a ProgramConsole
. The
methods may also block if a client calls one of these methods and blocks,
and then a second client calls one of these methods from another thread; the
second client may block waiting for access to the lock. The standard output
stream and standard error stream are not guarded by the same lock as the
ProgramConsole
used by the prompt(String, String)
and
promptChoice(String, int, String)
methods.
Modifier and Type | Class | Description |
---|---|---|
static class |
DefaultConfigurableSensibleUi.Builder |
A builder for creating
DefaultConfigurableSensibleUi
instances. |
Modifier and Type | Method | Description |
---|---|---|
static DefaultConfigurableSensibleUi |
create() |
Creates a new instance with
Builder defaults. |
void |
debug(String format,
Object... args) |
Writes the message, prefixed with the debug prefix, to the underlying
stream if the
debug level flag is set. |
void |
error(String format,
Object... args) |
Writes the message, prefixed with the error prefix, to the standard error
stream.
|
void |
flush() |
Causes any buffered output on the standard output stream, standard error
stream, and console to be written out.
|
void |
note(String format,
Object... args) |
Writes the message, prefixed with the note prefix, to the underlying
stream if the
verbose level flag is set. |
String |
prompt(String message,
String defaultResponse) |
Prompts the user with the specified prompt message and default response.
|
int |
promptChoice(String message,
int defaultResponse,
String choices) |
Prompts the user with the specified prompt message, default response, and
choices.
|
char[] |
promptPassword(String message,
char[] defaultPassword) |
Prompts the user for a password with echoing turned off and with the
specified prompt message and default password.
|
void |
status(String format,
Object... args) |
Writes the message, prefixed with the status prefix, to the underlying
stream if the
quiet level flag is not set. |
DefaultConfigurableSensibleUi.Builder |
toBuilder() |
Converts this UI into a builder.
|
void |
warn(String format,
Object... args) |
Writes the message, prefixed with the warn prefix, to the standard error
stream.
|
void |
write(String format,
Object... args) |
Writes the message to the standard output stream.
|
void |
writeStderr(String format,
Object... args) |
Writes the message to the standard error stream.
|
public void write(String format, Object... args)
This method may be used for output that should always be written to the standard output stream regardless of the level flags and without a level prefix.
write
in interface SensibleUi
format
- the format string as defined by Formatter
args
- the format string argumentsIllegalFormatException
- if format
or args
is illegal according to the rules of Formatter
NullPointerException
- if format
is null
StandardIoException
- if an error occurs while writing to the
standard output streampublic void writeStderr(String format, Object... args)
This method may be used for output that should always be written to the standard error stream regardless of the level flags and without a level prefix.
writeStderr
in interface SensibleUi
format
- the format string as defined by Formatter
args
- the format string argumentsIllegalFormatException
- if format
or args
is illegal according to the rules of Formatter
NullPointerException
- if format
is null
StandardIoException
- if an error occurs while writing to the
standard error streampublic void status(String format, Object... args)
quiet
level flag is not set.status
in interface SensibleUi
format
- the format string as defined by Formatter
args
- the format string argumentsIllegalFormatException
- if format
or args
is illegal according to the rules of Formatter
NullPointerException
- if format
is null
StandardIoException
- if an error occurs while writing to the
underlying streampublic void note(String format, Object... args)
verbose
level flag is set.note
in interface SensibleUi
format
- the format string as defined by Formatter
args
- the format string argumentsIllegalFormatException
- if format
or args
is illegal according to the rules of Formatter
NullPointerException
- if format
is null
StandardIoException
- if an error occurs while writing to the
underlying streampublic void debug(String format, Object... args)
debug
level flag is set.debug
in interface SensibleUi
format
- the format string as defined by Formatter
args
- the format string argumentsIllegalFormatException
- if format
or args
is illegal according to the rules of Formatter
NullPointerException
- if format
is null
StandardIoException
- if an error occurs while writing to the
underlying streampublic void warn(String format, Object... args)
A causing/associated exception my be supplied in addition to the message
format and arguments by including it as the last argument in this method's
varargs argument. This behavior is specified in the
SensibleUi.warn(String format, Object... args)
method
documentation.
If printing stack traces is enabled, to write a stack trace without any
message, pass an empty string as the format
argument and the
exception as the second argument.
If a ProgramDieException
is given as a causing/associated
exception, it is printed differently than other exceptions: a stack trace
will not be printed for it, and its fully qualified class name will be
omitted; just its message will be printed.
If an exception stack trace is printed, the standard error stream will be flushed after printing it. Also, the system locale will be used when printing the stack trace, not the locale specified for this UI.
warn
in interface SensibleUi
format
- the format string as defined by Formatter
args
- the format string arguments optionally followed by a
Throwable
cause/associationIllegalFormatException
- if format
or args
is illegal according to the rules of Formatter
NullPointerException
- if format
is null
StandardIoException
- if an error occurs while writing to the
standard error streampublic void error(String format, Object... args)
A causing/associated exception my be supplied in addition to the message
format and arguments by including it as the last argument in this method's
varargs argument. This behavior is specified in the
SensibleUi.error(String format, Object... args)
method
documentation.
If printing stack traces is enabled, to write a stack trace without any
message, pass an empty string as the format
argument and the
exception as the second argument.
If a ProgramDieException
is given as a causing/associated
exception, it is printed differently than other exceptions: a stack trace
will not be printed for it, and its fully qualified class name will be
omitted; just its message will be printed.
If an exception stack trace is printed, the standard error stream will be flushed after printing it. Also, the system locale will be used when printing the stack trace, not the locale specified for this UI.
error
in interface SensibleUi
format
- the format string as defined by Formatter
args
- the format string arguments optionally followed by a
Throwable
cause/associationIllegalFormatException
- if format
or args
is illegal according to the rules of Formatter
NullPointerException
- if format
is null
StandardIoException
- if an error occurs while writing to the
standard error streampublic void flush()
flush
in interface Flushable
flush
in interface SensibleUi
StandardIoException
- if an error occurs while flushing the standard
output stream, standard error stream, or the consolepublic String prompt(String message, String defaultResponse)
The prompt message should not include a trailing space character or other trailing whitespace; appropriate whitespace or other characters will be added automatically.
The default response will be returned if the console is not present, the user simply presses enter (i.e., an empty string response), or the end of the stream is reached.
This implementation calls flush()
before prompting the user on
the console.
prompt
in interface SensibleUi
message
- the prompt messagedefaultResponse
- the default responseNullPointerException
- if message
is null
StandardIoException
- if an error occurs while flushing the standard
output stream, standard error stream, or console, or while
writing/reading to/from the consolepublic int promptChoice(String message, int defaultResponse, String choices)
The prompt message should not include a trailing space character or other trailing whitespace; appropriate whitespace or other characters will be added automatically.
The default response will be returned if the console is not present, the user simply presses enter (i.e., an empty string response), or the end of the stream is reached.
The choices are encoded in the choices format which is a comma-separated list of choices. A choice may be split into alternatives that are all considered to be equivalent by separating them with a slash. All choices must be lowercase. A backslash escapes the character that follows it thus allowing the encoding of the backslash, comma, and slash characters as choices if needed. The user's response will be converted to lowercase before searching the choices for a match.
Choices Format Examples:
y
" or "n
" in
arbitrary case:
y,n
y
", "yes
",
"n
", or "no
" in arbitrary case:
y/yes,n/no
y
", "yes
",
"yes, please
", "n
", "no
", "no, thank you
",
"h
", or "help
" in arbitrary case:
y/yes/yes\, please,n/no/no\, thank you,h/help
This implementation calls flush()
before prompting the user on
the console.
promptChoice
in interface SensibleUi
message
- the prompt messagedefaultResponse
- the zero-based index of the default response in the
choices list; must be greater than or equal to zerochoices
- the choices encoded in the choices format; must be all
lowercase-1
if the user's response does not match any choice; otherwise (i.e.,
the user's response could not be obtained), the default responsePromptChoicesSyntaxException
- if choices
is malformedIllegalArgumentException
- if defaultResponse
is less than
zeroNullPointerException
- if message
or choices
is
null
StandardIoException
- if an error occurs while flushing the standard
output stream, standard error stream, or console, or while
writing/reading to/from the consolepublic char[] promptPassword(String message, char[] defaultPassword)
The prompt message should not include a trailing space character or other trailing whitespace; appropriate whitespace or other characters will be added automatically.
The default password will be returned if the console is not present, the user simply presses enter (i.e., an empty string password), or the end of the stream is reached.
This implementation calls flush()
before prompting the user on
the console.
promptPassword
in interface SensibleUi
message
- the prompt messagedefaultPassword
- the default passwordNullPointerException
- if message
is null
StandardIoException
- if an error occurs while flushing the standard
output stream, standard error stream, or console, or while
writing/reading to/from the consolepublic DefaultConfigurableSensibleUi.Builder toBuilder()
ConfigurableSensibleUi
The conversion between a UI and a builder is lossless. For example, if a default value is used in a UI because it was not explicitly set in the builder from which it was created, the builder returned by invoking this method on that UI would again consider the value to not be set.
toBuilder
in interface ConfigurableSensibleUi
public static DefaultConfigurableSensibleUi create()
Builder
defaults.