com.fedmest.cw.keyboard
Class KeyboardUtils

java.lang.Object
  com.fedmest.cw.keyboard.KeyboardUtils

Direct Known Subclasses:

KeyboardUtilsDefImpl

public abstract class KeyboardUtils
extends java.lang.Object

The KeyboardUtils class is an abstract class that defines the interface for easily accessing the keyboard. It offers a method (newDefaultKeyboard()) that returns the default implementation of itself. Various methods allow the programmer to retrieve the basic data types from the input string with a simple call, while the use of the KeyboardInputValidator framework simplifies access to more complex input requirements.

This class - and all other classes in this framework - is not thread-safe and is not meant to be used in multithreaded applications.

Version:

1.0

Author:

Federico Mestrone

Constructor Summary

KeyboardUtils()

Method Summary

protected abstract java.lang.String	addErrTag(java.lang.String msg) Adds the error tag to a string.
protected abstract java.lang.String	addPrompt(java.lang.String msg) Adds the input prompt to a string.
void	error(java.lang.String msg) Displays an error message to the user.
boolean	isCancelable() Tells you whether the current instance of KeyboardUtils allows the user to cancel input.
static KeyboardUtils	newDefaultKeyboard() Returns the default implementation of this abstract class.
void	prompt(java.lang.String msg) Displays an input prompt to the user.
int	readBinaryFromKeyboard() Reads an int value from the keyboard in binary notation without a prompt to the user.
int	readBinaryFromKeyboard(java.lang.String msg) Reads an int value from the keyboard in binary notation.
boolean	readBoolFromKeyboard() Reads a boolean response from the keyboard without a prompt to the user.
boolean	readBoolFromKeyboard(java.lang.String msg) Reads a boolean response from the keyboard.
char	readCharFromKeyboard() Reads a character from the keyboard without a prompt to the user.
char	readCharFromKeyboard(java.lang.String msg) Reads a character from the keyboard.
double	readDoubleFromKeyboard() Reads a double floating point value from the keyboard without a prompt to the user.
double	readDoubleFromKeyboard(java.lang.String msg) Reads a double floating point value from the keyboard.
float	readFloatFromKeyboard() Reads a floating point value from the keyboard without a prompt to the user.
float	readFloatFromKeyboard(java.lang.String msg) Reads a floating point value from the keyboard.
java.lang.String	readFromKeyboard() Reads a new line of text from the keyboard and returns it as it was typed.
<T> T	readFromKeyboard(KeyboardInputValidator<T> v) Reads a new line of text from the keyboard without printing out any prompt to the user and uses the specified KeyboardInputValidator to verify the input and convert it to the type offered by the validator itself.
java.lang.String	readFromKeyboard(java.lang.String msg) Prints a prompt to the user on System.out, then reads a new line of text from the keyboard and returns it as it was typed.
<T> T	readFromKeyboard(java.lang.String msg, KeyboardInputValidator<T> v) Prints a prompt to the user on System.out, then reads a new line of text from the keyboard and uses the specified KeyboardInputValidator to verify the input and convert it to the type offered by the validator itself.
int	readHexFromKeyboard() Reads an int value from the keyboard in hexadecimal notation without a prompt to the user.
int	readHexFromKeyboard(java.lang.String msg) Reads an int value from the keyboard in hexadecimal notation.
int	readIntFromKeyboard() Reads an int value from the keyboard without a prompt to the user.
int	readIntFromKeyboard(java.lang.String msg) Reads an int value from the keyboard.
int	readIntFromKeyboard(java.lang.String msg, int radix) Reads an int value from the keyboard in the specified number base.
long	readLongFromKeyboard() Reads a long value from the keyboard without a prompt to the user.
long	readLongFromKeyboard(java.lang.String msg) Reads a long value from the keyboard.
long	readLongFromKeyboard(java.lang.String msg, int radix) Reads an long value from the keyboard in the specified number base.
int	readOctalFromKeyboard() Reads an int value from the keyboard in octal notation without a prompt to the user.
int	readOctalFromKeyboard(java.lang.String msg) Reads an int value from the keyboard in octal notation.
void	setCancelable(boolean cancelable) Specifies whether the current instance of KeyboardUtils allows the user to cancel input.
protected abstract boolean	shouldCancel(java.lang.String msg) Checks whether a cancel sequence was typed.
boolean	wasCanceled() Tells you whether the user canceled input.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KeyboardUtils

public KeyboardUtils()

Method Detail

newDefaultKeyboard

public static final KeyboardUtils newDefaultKeyboard()

Returns the default implementation of this abstract class.

Returns:

an instance of KeyboardUtilsDefImpl

readFromKeyboard

public java.lang.String readFromKeyboard()

Reads a new line of text from the keyboard and returns it as it was typed. No validation or conversion occurs.

Returns:

the string typed by the user on the keyboard.

readFromKeyboard

public java.lang.String readFromKeyboard(java.lang.String msg)

Prints a prompt to the user on System.out, then reads a new line of text from the keyboard and returns it as it was typed. No validation or conversion occurs.

Parameters:

msg - the prompt to show the user. The prompt string will feature a set of characters to alert the user that input is expected - the specific sequence of characters for the prompt depends on the KeyboardUtils implementation being used.

Returns:

the string typed by the user on the keyboard.

readFromKeyboard

public <T> T readFromKeyboard(KeyboardInputValidator<T> v)

Reads a new line of text from the keyboard without printing out any prompt to the user and uses the specified KeyboardInputValidator to verify the input and convert it to the type offered by the validator itself. The method will keep on asking for input until a valid string is typed, unless the instance is cancelable.

Type Parameters:

T - the type of data that the input string will be converted to.

Parameters:

v - an instance of the validator object that should be used against the keyboard input

Returns:

the string typed by the user on the keyboard.

readFromKeyboard

public <T> T readFromKeyboard(java.lang.String msg,
                              KeyboardInputValidator<T> v)

Prints a prompt to the user on System.out, then reads a new line of text from the keyboard and uses the specified KeyboardInputValidator to verify the input and convert it to the type offered by the validator itself. The method will keep on asking for input until a valid string is typed, unless the instance is cancelable.

Type Parameters:

T - the type of data that the input string will be converted to.

Parameters:

msg - the prompt to show the user. The prompt string will feature a set of characters to alert the user that input is expected - the specific sequence of characters for the prompt depends on the KeyboardUtils implementation being used.

v - an instance of the validator object that should be used against the keyboard input

Returns:

the string typed by the user on the keyboard.

readIntFromKeyboard

public int readIntFromKeyboard()

Reads an int value from the keyboard without a prompt to the user. This method internally uses an IntValidator.

Returns:

the int that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readIntFromKeyboard

public int readIntFromKeyboard(java.lang.String msg)

Reads an int value from the keyboard. This method internally uses an IntValidator.

Parameters:

msg - a prompt on System.out for the user.

Returns:

the int that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readHexFromKeyboard

public int readHexFromKeyboard()

Reads an int value from the keyboard in hexadecimal notation without a prompt to the user. This method internally uses an IntValidator.

Returns:

the int that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readHexFromKeyboard

public int readHexFromKeyboard(java.lang.String msg)

Reads an int value from the keyboard in hexadecimal notation. This method internally uses an IntValidator.

Parameters:

msg - a prompt on System.out for the user.

Returns:

the int that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readOctalFromKeyboard

public int readOctalFromKeyboard()

Reads an int value from the keyboard in octal notation without a prompt to the user. This method internally uses an IntValidator.

Returns:

the int that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readOctalFromKeyboard

public int readOctalFromKeyboard(java.lang.String msg)

Reads an int value from the keyboard in octal notation. This method internally uses an IntValidator.

Parameters:

msg - a prompt on System.out for the user.

Returns:

the int that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readBinaryFromKeyboard

public int readBinaryFromKeyboard()

Reads an int value from the keyboard in binary notation without a prompt to the user. This method internally uses an IntValidator.

Returns:

the int that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readBinaryFromKeyboard

public int readBinaryFromKeyboard(java.lang.String msg)

Reads an int value from the keyboard in binary notation. This method internally uses an IntValidator.

Parameters:

msg - a prompt on System.out for the user.

Returns:

the int that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readIntFromKeyboard

public int readIntFromKeyboard(java.lang.String msg,
                               int radix)

Reads an int value from the keyboard in the specified number base. This method internally uses an IntValidator.

Parameters:

msg - a prompt on System.out for the user.

radix - the number base of the integer to parse.

Returns:

the int that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readLongFromKeyboard

public long readLongFromKeyboard()

Reads a long value from the keyboard without a prompt to the user. This method internally uses a LongValidator.

Returns:

the long that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readLongFromKeyboard

public long readLongFromKeyboard(java.lang.String msg)

Reads a long value from the keyboard. This method internally uses a LongValidator.

Parameters:

msg - a prompt on System.out for the user.

Returns:

the long that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readLongFromKeyboard

public long readLongFromKeyboard(java.lang.String msg,
                                 int radix)

Reads an long value from the keyboard in the specified number base. This method internally uses a LongValidator.

Parameters:

msg - a prompt on System.out for the user.

radix - the number base of the long to parse.

Returns:

the long that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readFloatFromKeyboard

public float readFloatFromKeyboard()

Reads a floating point value from the keyboard without a prompt to the user. This method internally uses a FloatValidator.

Returns:

the floating point number that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readFloatFromKeyboard

public float readFloatFromKeyboard(java.lang.String msg)

Reads a floating point value from the keyboard. This method internally uses a FloatValidator.

Parameters:

msg - a prompt on System.out for the user.

Returns:

the floating point number that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readDoubleFromKeyboard

public double readDoubleFromKeyboard()

Reads a double floating point value from the keyboard without a prompt to the user. This method internally uses a DoubleValidator.

Returns:

the double floating point number that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readDoubleFromKeyboard

public double readDoubleFromKeyboard(java.lang.String msg)

Reads a double floating point value from the keyboard. This method internally uses a DoubleValidator.

Parameters:

msg - a prompt on System.out for the user.

Returns:

the double floating point number that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readBoolFromKeyboard

public boolean readBoolFromKeyboard()

Reads a boolean response from the keyboard without a prompt to the user. This method internally uses a BooleanValidator. Accepted values are "yes", "true", "ok", "no" and "false". Case is irrelevant.

Returns:

true if the user typed "yes", "true" or "ok",
false if they typed "no" or "false".

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readBoolFromKeyboard

public boolean readBoolFromKeyboard(java.lang.String msg)

Reads a boolean response from the keyboard. This method internally uses a BooleanValidator. Accepted values are "yes", "true", "ok", "no" and "false". Case is irrelevant.

Parameters:

msg - a prompt on System.out for the user.

Returns:

true if the user typed "yes", "true" or "ok",
false if they typed "no" or "false".

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readCharFromKeyboard

public char readCharFromKeyboard()

Reads a character from the keyboard without a prompt to the user. It also makes sure that only one character was typed. This method internally uses a CharValidator.

Returns:

the character that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

readCharFromKeyboard

public char readCharFromKeyboard(java.lang.String msg)

Reads a character from the keyboard. It also makes sure that only one character was typed. This method internally uses a CharValidator.

Parameters:

msg - a prompt on System.out for the user.

Returns:

the character that the user typed

See Also:

readFromKeyboard(String, KeyboardInputValidator)

isCancelable

public boolean isCancelable()

Tells you whether the current instance of KeyboardUtils allows the user to cancel input.

Returns:

true if user can cancel input,
false if user has to type a valid value before they can continue

setCancelable

public void setCancelable(boolean cancelable)

Specifies whether the current instance of KeyboardUtils allows the user to cancel input.

Parameters:

cancelable - specifies whether the user can cancel input (true) or has to type a valid value before continuing (false)

wasCanceled

public boolean wasCanceled()

Tells you whether the user canceled input. If this method returns true, the client application must discard whatever return value was offered by a readFromKeyboard() method. The methods will return null if possible, but for primitive types a dummy value will be returned that must be ignored.

Returns:

true if user canceled input and return value from readFromKeyboard() method is to be discarded,
false if the user typed a valid value that the application can use.

error

public void error(java.lang.String msg)

Displays an error message to the user. It uses an error tag that depends on the KeyboardUtils implementation being used. The method will also add the prompt character sequence, so that input can be retried.

Parameters:

msg - the error message that will displayed on System.out for the user.

prompt

public void prompt(java.lang.String msg)

Displays an input prompt to the user. The user is thus made aware that they are expected to type some information on the keyboard. The message will be combined with the input prompt.

Parameters:

msg - the message that will displayed on System.out for the user.

addPrompt

protected abstract java.lang.String addPrompt(java.lang.String msg)

Adds the input prompt to a string. Override this method in your implementations of KeyboardUtils to specify how the error tag combines with the error message.

Parameters:

msg - the message that should be combined with the input prompt character sequence.

Returns:

the string containing the error message and error tag ready for display.

addErrTag

protected abstract java.lang.String addErrTag(java.lang.String msg)

Adds the error tag to a string. Override this method in your implementations of this class to specify how the user message combines with the input prompt.

Parameters:

msg - the message that should be combined with the error tag character sequence.

Returns:

the string containing the user message and input prompt ready for display.

shouldCancel

protected abstract boolean shouldCancel(java.lang.String msg)

Checks whether a cancel sequence was typed. Override this method in your implementations of KeyboardUtils to specify whether the string typed by the user is a request to cancel current input. This method will not be invoked by the framework if the instance if not cancelable and canceling will not be possible.

Parameters:

msg - the message that the user type on the keyboard.

Returns:

true if the string means the user intends to cancel input,
false if the string is not a request to cancel and should be validated and possibly converted before returning it.

See Also:

isCancelable(), setCancelable(boolean), wasCanceled()