org.josef.util

Class Mask

java.lang.Object

org.josef.util.Mask

@Status(stage=DEVELOPMENT,
        unitTests=COMPLETE)
 @Wish(value="Be able to specify a mask character as a literal") @Wish(value="Be able to specify multiple mask characters with a number prefix like:5#-5# instead of:#####-#####")
public final class Mask
extends Object

Mask utility class.
This class aids in adding mask characters to a value and removing mask characters from a value.
The following table shows all possible mask characters.

Mask character	Description
#	A digit from 0 to 9
A	Alphabetic character
L	Alphabetic character, converted to lower case
U	Alphabetic character, converted to upper case
N	Alphanumeric character
?	Any character

Consider for example the format of the Dutch zip code. It consists of 4 digits, a space and then two upper case letters. Now you don't want the user to enter the space, nor want the user to type the two upper case letters. Here is where masking comes in. In this particular example we would use the mask: "#### UU".
This reads as follows: 4 digits, followed by a space, followed by two upper case letters. When you have a value without mask characters like: "3931LA", you can get the mask characters in by calling:
Mask.fromUnmaskedValue("#### UU", "3931LA");. This will return "3931 LA".
When you have a value with mask characters like: "3931 la", you can remove the mask characters by calling:
Mask.fromMaskedValue("#### UU", "3931 la");. This will return "3931LA".
Note: This class only supports single masks of a fixed length. This is fine for Dutch zip codes but is unusable in the UK where they have several different formats to make up a zip code. The ZipCodeOfCountry class handles this problem by supporting different masks that are used in turn.

Version:

1.1 $Revision: 6488 $

Author:

Kees Schotanus

Method Summary

Modifier and Type	Method and Description
static String	fromMaskedValue(String mask, String maskedValue) Converts the supplied maskedValue to a value that does not contain mask characters.
static String	fromUnmaskedValue(String mask, String unmaskedValue) Converts the supplied unmaskedValue to a value that contains mask characters.

Methods inherited from class java.lang.Object

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

Method Detail

fromMaskedValue

public static String fromMaskedValue(String mask,
                                     String maskedValue)

Converts the supplied maskedValue to a value that does not contain mask characters.
For example: When the mask="(AAA)" and the maskedValue="(123)", this method would return "123".
Note: This method still works when in the above case, the maskedValue contains "123". That is, that it contains no mask characters.

Parameters:

mask - The mask.

maskedValue - The masked value (the value possibly containing mask characters) to unmask.

Returns:

The unmasked value of the supplied masked Value, using the supplied mask.

Throws:

NullPointerException - When either the supplied mask or maskedValue is null.

IllegalArgumentException - When the supplied mask is empty or when the supplied maskedValue is longer than the supplied mask.

fromUnmaskedValue

public static String fromUnmaskedValue(String mask,
                                       String unmaskedValue)

Converts the supplied unmaskedValue to a value that contains mask characters.
For example: When the mask="(AAA)" and the unmaskedValue="123", this method would return "(123)". When the mask=(UUU) and the unmaskeValue="abc", this method would return "(ABC)".

Parameters:

mask - The mask.

unmaskedValue - The unmasked value.

Returns:

The masked value of the supplied unmasked Value, using the supplied mask.

Throws:

NullPointerException - When either the supplied mask or the supplied unmaskedValue is null.

IllegalArgumentException - When the supplied mask is empty or when the unmaskedValue is shorter than may be expected from the mask.