net.nicholaswilliams.java.licensing.licensor.interfaces.cli.spi

Interface TextInterfaceDevice

All Superinterfaces:

Flushable, OutputDevice, PasswordPrompter

All Known Implementing Classes:

AbstractTextInterfaceDevice, ConsoleInterfaceDevice

public interface TextInterfaceDevice
extends PasswordPrompter, Flushable, OutputDevice

Specifies an interface for interacting with text devices in order to abstract the details of interaction away from the application code. In nearly all circumstances, the implementation used will be the ConsoleInterfaceDevice.

Much of the documentation for the methods in this class was derived from the documentation for Console and Runtime because the default and intended implementation wraps the methods of those classes.

Since:

1.0.0

Version:

1.0.0

Author:

Nick Williams

Field Summary

Fields

Modifier and Type	Field and Description
static TextInterfaceDevice	CONSOLE

Method Summary

Methods

Modifier and Type	Method and Description
PrintStream	err() Gets the standard error stream.
void	exit() Terminates the currently running application normally (with a status code of zero).
void	exit(int exitCode) Terminates the currently running application.
TextInterfaceDevice	format(String format, Object... arguments) Writes a formatted string to this device's output stream using the specified format string and arguments.
Reader	getReader() Retrieves the unique Reader object associated with this interface device.
PrintWriter	getWriter() Retrieves the unique PrintWriter object associated with this interface device.
InputStream	in() Gets the standard input stream.
PrintStream	out() Gets the standard output stream.
void	printErr(char c) Prints a char to standard-err.
void	printErr(Object o) Prints an Object to standard-out.
void	printErr(String s) Prints a String to standard-err.
void	printErrLn() Terminates the current standard-err line by writing the line separator string.
void	printErrLn(char c) Prints a char to standard-err, then terminates the current line by writing the line separator string.
void	printErrLn(Object o) Prints an Object to standard-err, then terminates the current line by writing the line separator string.
void	printErrLn(String s) Prints a String to standard-err, then terminates the current line by writing the line separator string.
TextInterfaceDevice	printf(String format, Object... arguments) A convenience method to write a formatted string to this device's output stream using the specified format string and arguments.
void	printOut(char c) Prints a char to standard-out.
void	printOut(Object o) Prints an Object to standard-out.
void	printOut(String s) Prints a String to standard-out.
void	printOutLn() Terminates the current standard-out line by writing the line separator string.
void	printOutLn(char c) Prints a char to standard-out, then terminates the current line by writing the line separator string.
void	printOutLn(Object o) Prints an Object to standard-out, then terminates the current line by writing the line separator string.
void	printOutLn(String s) Prints a String to standard-out, then terminates the current line by writing the line separator string.
String	readLine() Reads a single line of text from the device.
String	readLine(String format, Object... arguments) Provides a formatted prompt, then reads a single line of text from the device.
char[]	readPassword() Reads a password or passphrase from the device with echoing disabled.
char[]	readPassword(String format, Object... arguments) Provides a formatted prompt, then reads a password or passphrase from the device with echoing disabled.
void	registerShutdownHook(Thread hook) Registers a new application shutdown hook.
boolean	unregisterShutdownHook(Thread hook) De-registers a previously-registered application shutdown hook.

Methods inherited from interface net.nicholaswilliams.java.licensing.licensor.interfaces.spi.PasswordPrompter

passwordsMatch, promptForValidPassword, promptForValidPassword

Methods inherited from interface java.io.Flushable

flush

Methods inherited from interface net.nicholaswilliams.java.licensing.licensor.interfaces.spi.OutputDevice

outputErrorMessage, outputMessage

Field Detail

CONSOLE

static final TextInterfaceDevice CONSOLE

Method Detail

registerShutdownHook

void registerShutdownHook(Thread hook)
                          throws IllegalArgumentException,
                                 IllegalStateException,
                                 SecurityException

Registers a new application shutdown hook. For the standard behavior, implemented by the default implementation, see the documentation for Runtime.addShutdownHook(Thread).

Parameters:

hook - An initialized but unstarted Thread object

Throws:

IllegalArgumentException - if the specified hook has already been registered, or if it can be determined that the hook is already running or has already been run.

IllegalStateException - if the application is already in the process of shutting down.

SecurityException - if registering shutdown hooks is forbidden.

unregisterShutdownHook

boolean unregisterShutdownHook(Thread hook)
                               throws IllegalStateException,
                                      SecurityException

De-registers a previously-registered application shutdown hook.

Parameters:

hook - The hook to remove

Returns:

true if the specified hook had previously been registered and was successfully de-registered, false otherwise

Throws:

IllegalStateException - if the virtual machine is already in the process of shutting down.

SecurityException - if registering shutdown hooks is forbidden.

exit

void exit()

Terminates the currently running application normally (with a status code of zero).

exit

void exit(int exitCode)

Terminates the currently running application. The argument serves as a status code; by convention, a nonzero status code indicates abnormal termination.

Parameters:

exitCode - The exit status to exit with

format

TextInterfaceDevice format(String format,
                         Object... arguments)
                           throws IllegalFormatException

Writes a formatted string to this device's output stream using the specified format string and arguments.

Parameters:

format - A format string as described in #syntax

arguments - 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.

Returns:

this device.

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.

printf

TextInterfaceDevice printf(String format,
                         Object... arguments)
                           throws IllegalFormatException,
                                  IOError

A convenience method to write a formatted string to this device's output stream using the specified format string and arguments.

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

Parameters:

format - A format string as described in #syntax

arguments - 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.

Returns:

this device.

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.

readLine

String readLine()
                throws IOError

Reads a single line of text from the device.

Returns:

a string containing the line read from the interface device input, not including any line-termination characters, or null if an end of stream has been reached.

Throws:

IOError - if an I/O error occurs.

readLine

String readLine(String format,
              Object... arguments)
                throws IllegalFormatException,
                       IOError

Provides a formatted prompt, then reads a single line of text from the device.

Parameters:

format - A format string as described in #syntax

arguments - 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.

Returns:

a string containing the line read from the interface device input, not including any line-termination characters, or null if an end of stream has been reached.

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.

readPassword

char[] readPassword()
                    throws IOError

Reads a password or passphrase from the device with echoing disabled.

Specified by:

readPassword in interface PasswordPrompter

Returns:

a character array containing the password or passphrase read from the device, not including any line-termination characters, or null if an end of stream has been reached.

Throws:

IOError - if an I/O error occurs.

readPassword

char[] readPassword(String format,
                  Object... arguments)
                    throws IllegalFormatException,
                           IOError

Provides a formatted prompt, then reads a password or passphrase from the device with echoing disabled.

Specified by:

readPassword in interface PasswordPrompter

Parameters:

format - A format string as described in #syntax

arguments - 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.

Returns:

a character array containing the password or passphrase read from the device, not including any line-termination characters, or null if an end of stream has been reached.

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.

printOut

void printOut(char c)
              throws IOError

Prints a char to standard-out.

Parameters:

c - The char to be printed

Throws:

IOError - if an I/O error occurs.

printOut

void printOut(String s)
              throws IOError

Prints a String to standard-out.

Parameters:

s - The String to be printed

Throws:

IOError - if an I/O error occurs.

printOut

void printOut(Object o)
              throws IOError

Prints an Object to standard-out.

Parameters:

o - The Object to be printed

Throws:

IOError - if an I/O error occurs.

printErr

void printErr(char c)
              throws IOError

Prints a char to standard-err.

Parameters:

c - The char to be printed

Throws:

IOError - if an I/O error occurs.

printErr

void printErr(String s)
              throws IOError

Prints a String to standard-err.

Parameters:

s - The String to be printed

Throws:

IOError - if an I/O error occurs.

printErr

void printErr(Object o)
              throws IOError

Prints an Object to standard-out.

Parameters:

o - The Object to be printed

Throws:

IOError - if an I/O error occurs.

printOutLn

void printOutLn()
                throws IOError

Terminates the current standard-out line by writing the line separator string.

Throws:

IOError - if an I/O error occurs.

printOutLn

void printOutLn(char c)
                throws IOError

Prints a char to standard-out, then terminates the current line by writing the line separator string.

Parameters:

c - The char to be printed

Throws:

IOError - if an I/O error occurs.

printOutLn

void printOutLn(String s)
                throws IOError

Prints a String to standard-out, then terminates the current line by writing the line separator string.

Parameters:

s - The String to be printed

Throws:

IOError - if an I/O error occurs.

printOutLn

void printOutLn(Object o)
                throws IOError

Prints an Object to standard-out, then terminates the current line by writing the line separator string.

Parameters:

o - The Object to be printed

Throws:

IOError - if an I/O error occurs.

printErrLn

void printErrLn()
                throws IOError

Terminates the current standard-err line by writing the line separator string.

Throws:

IOError - if an I/O error occurs.

printErrLn

void printErrLn(char c)
                throws IOError

Prints a char to standard-err, then terminates the current line by writing the line separator string.

Parameters:

c - The char to be printed

Throws:

IOError - if an I/O error occurs.

printErrLn

void printErrLn(String s)
                throws IOError

Prints a String to standard-err, then terminates the current line by writing the line separator string.

Parameters:

s - The String to be printed

Throws:

IOError - if an I/O error occurs.

printErrLn

void printErrLn(Object o)
                throws IOError

Prints an Object to standard-err, then terminates the current line by writing the line separator string.

Parameters:

o - The Object to be printed

Throws:

IOError - if an I/O error occurs.

getReader

Reader getReader()

Retrieves the unique Reader object associated with this interface device. For more information regarding the uses of this method, see the documentation for Console.reader().

Returns:

the reader associated with this interface.

getWriter

PrintWriter getWriter()

Retrieves the unique PrintWriter object associated with this interface device.

Returns:

the print writer associated with this interface.

in

InputStream in()

Gets the standard input stream.

Returns:

the standard input stream.

out

PrintStream out()

Gets the standard output stream.

Returns:

the standard output stream.

err

PrintStream err()

Gets the standard error stream.

Returns:

the standard error stream.