com.fedmest.cw.keyboard.validators
Class CharChoiceValidator

java.lang.Object
  com.fedmest.cw.keyboard.validators.CharChoiceValidator

All Implemented Interfaces:

KeyboardInputValidator<java.lang.Character>

public final class CharChoiceValidator
extends java.lang.Object
implements KeyboardInputValidator<java.lang.Character>

This class checks for single-character input within a range of allowed characters. It is suited for simple text menus based on one-character choices, but it can generically be used to limit the characters accepted as input in all sorts of contexts. Create the class by specifying the characters that are allowed as input and simply let your KeyboardUtils instance get the input for you. The returned value is the character that was selected. If the user canceled input on a cancelable KeyboardUtils, the class will return an empty character '\0', so you can safely expect it to always return a valid char primitive type (as opposed to null.

Version:

1.0

Author:

Federico Mestrone

Constructor Summary

CharChoiceValidator(char[] allowedChars)
Creates a new instance of this validator with an array of characters to be allowed as input.

CharChoiceValidator(java.lang.String allowedChars)
Creates a new instance of this validator with a String containing the characters to be allowed as input.

Method Summary

java.lang.Character	cancelValue() Allows you to specify the return value to offer when the user cancels input on a cancelable instance of KeyboardUtils .
java.lang.Character	checkInput(java.lang.String txt) Takes the input string, checks its validity and converts it to the data type specified by the type argument.
boolean	isCaseSensitive() Tells you whether this instance of the validator will take case into account when matching characters.
void	resetErrorMessages() This method resets the error messages that will be displayed to users on validation failure to the default text ("Invalid choice - retry").
void	setCaseSensitive(boolean caseSensitive) Specifies whether the validation of the characters should take case into consideration.
void	setErrorMessages(java.lang.String errorMessage) Sets the error messages that will be displayed to the user if validation fails either because the input string was longer than one character or because the input character is not among the allowed ones.
void	setErrorMessages(java.lang.String errorMessage1, java.lang.String errorMessage2) Sets the error messages that will be displayed to the user if validation fails either because the input string was longer than one character or because the input character is not among the allowed ones.

Methods inherited from class java.lang.Object

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

Constructor Detail

CharChoiceValidator

public CharChoiceValidator(char[] allowedChars)

Creates a new instance of this validator with an array of characters to be allowed as input.

Parameters:

allowedChars - an array of the allowed characters

CharChoiceValidator

public CharChoiceValidator(java.lang.String allowedChars)

Creates a new instance of this validator with a String containing the characters to be allowed as input.

Parameters:

allowedChars - a string whose characters will be used as allowed characters

Method Detail

resetErrorMessages

public void resetErrorMessages()

This method resets the error messages that will be displayed to users on validation failure to the default text ("Invalid choice - retry").

See Also:

setErrorMessages(String, String), setErrorMessages(String)

setErrorMessages

public void setErrorMessages(java.lang.String errorMessage)

Sets the error messages that will be displayed to the user if validation fails either because the input string was longer than one character or because the input character is not among the allowed ones. Both conditions will return the same message.

Parameters:

errorMessage - the new error messages to display to users when validation fails for any reason.

See Also:

setErrorMessages(String, String), resetErrorMessages()

setErrorMessages

public void setErrorMessages(java.lang.String errorMessage1,
                             java.lang.String errorMessage2)

Sets the error messages that will be displayed to the user if validation fails either because the input string was longer than one character or because the input character is not among the allowed ones.

Parameters:

errorMessage1 - the new error message to display to users when the input string is longer than one character

errorMessage2 - the new error message to display to users when the input character is not among the ones allowed

See Also:

setErrorMessages(String), resetErrorMessages()

setCaseSensitive

public void setCaseSensitive(boolean caseSensitive)

Specifies whether the validation of the characters should take case into consideration.

Parameters:

caseSensitive - set his to true if case should be taken into account in the validation procedure, or to false if case should not make a difference.

isCaseSensitive

public boolean isCaseSensitive()

Tells you whether this instance of the validator will take case into account when matching characters.

Returns:

true if the instance is case sensitive,
false if it is case insensitive

checkInput

public java.lang.Character checkInput(java.lang.String txt)
                               throws KeyboardInputException

Description copied from interface: KeyboardInputValidator

Takes the input string, checks its validity and converts it to the data type specified by the type argument. If validation fails, a KeyboardInputException is raised and the user will have to type their input again. If a null reference is passed into the method, the method may throw a NullPointerException, so programmers do not need to worry about checking for null pointers.

Specified by:

checkInput in interface KeyboardInputValidator<java.lang.Character>

Parameters:

txt - the input text. If the string is null, NullPointerException will be thrown.

Returns:

the result of converting the typed string into the data type expected

Throws:

KeyboardInputException - if validation against the input string failed

cancelValue

public java.lang.Character cancelValue()

Description copied from interface: KeyboardInputValidator

Allows you to specify the return value to offer when the user cancels input on a cancelable instance of KeyboardUtils . Though null should be returned in most cases, this method is useful when - for example - you want to return a primitive type from your validator and can't use null as a return value without causing a bit of inconvenienve in your application code (explicit unboxing and checks for null values).

Specified by:

cancelValue in interface KeyboardInputValidator<java.lang.Character>

Returns:

the value to return when user cancels input