20.4 The MaskFormatter Class

MaskFormatter is a subclass of DefaultFormatter that formats strings by matching them against a mask. The mask is a string of literals and nonliterals. The nonliterals (listed and described in Table 20-4) are wildcards that match a family of characters. Literals match only themselves. A single quote preceding a nonliteral (or another single quote) turns it into a literal. So, for example, the mask "ABa'A#''Hb" consists of the nonliteral A, the literal B, the literal a, the literal A, the nonliteral #, the literal ', the nonliteral H, and the literal b. The string "1BaA1'1b" matches this mask.

Table 20-4. Mask nonliterals (case-sensitive)

char	Matches	Notes
*	Any character
A	Any alphanumeric character	Tested by Character.isLetterOrDigit( )
?	Any alphabetic character	Tested by Character.isLetter( )
U	Uppercase alphabetic	Like ? but lowercase is mapped to uppercase
L	Lowercase alphabetic	Like ? but uppercase is mapped to lowercase
#	Any numeric character	Tested by Character.isDigit( )
H	Any hexadecimal numeric	Like # but includes abcdefABCDEF
'		Precedes any character in this table to create a literal

The JFormattedTextField in Figure 19-1 (and the code that follows it) uses a simple MaskFormatter with mask "UUUUU".

A MaskFormatter installed on a JFormattedTextField controls the caret so that by default it skips over literals and lands on nonliterals, which is nice. It can also be configured (by setting the valueContainsLiteralCharacters property to false) to have getValue( ) skip the literals, so the above string would be returned as "111" instead of "1BaA1'1b".

MaskFormatter works with Unicode characters, so, for example, the nonliteral # matches any Unicode DECIMAL_DIGIT_NUMBER, not just ASCII 0-9. (If you think this might be a problem, take a look at the validCharacters property.) In general, one character in the mask matches exactly one character of the input string, but with Unicode there may be a few languages where this is not always the case.

If you're trying to do something more complicated than MaskFormatter allows, such as specifying a more granular group of characters or permitting strings to vary in length, see Section 20.9, later in this chapter.

20.4.1 Properties

Table 20-5 shows the properties defined by MaskFormatter.

Table 20-5. MaskFormatter properties

Property	Data type	get	is	set	Default value
allowsInvalido	boolean	·		·	false
invalidCharacters	String	·		·	null
mask	String	·		·	null
placeholder	char	·		·	' ' (space)
placeholderCharacter	String	·		·	null
validCharacters	String	·		·	null
valueContainsLiteralCharacters	boolean	·		·	true
ooverridden See also properties from the DefaultFormatter class (Table 20-3).

The allowsInvalid property is listed here because MaskFormatter overrides it to default to false (which is usually what you want with MaskFormatter) and uses it to control an additional aspect of its behavior. If allowsInvalid is false, the field's caret skips over literals and lands on nonliterals.

The mask property described earlier is key to MaskFormatter. It can be set in the constructor or through the setMask( ) method, both of which are declared to throw a ParseException if the mask is invalid. This is an annoyance because the only way to make an invalid mask is to escape a literal (or to put a single ' at the end), and even then no exception actually gets thrown (at least not in Version 1.4.1).

The placeholder and placeholderCharacter properties determine what happens if the string is shorter than the mask. Let's say the mask has length 6, but the input string is only 4 characters long. If the 5^th slot of the mask is a literal, then that literal is copied into the 5^th slot of the string. If not, the 5^th slot of the placeholder string is consulted. If placeholder is not null and has a length of at least 5, and if this is the formatter's initial attempt at formatting (not a subsequent attempt), then the 5^th slot of the placeholder string is copied. Otherwise, the value of placeholderCharacter is copied. (If the input string is longer than the mask, excess characters are ignored.)

validCharacters and invalidCharacters place restrictions on which characters can match nonliterals in the mask. The type of these properties is String, but think of them as (case-sensitive) sets of characters. If validCharacters is not null, then any character matching a nonliteral must appear in the validCharacters string. Excluding a character from the validCharacters string prevents it from matching anything. If invalidCharacters is not null, then any character appearing in the invalidCharacters string is also illegal, even if it also appears in the validCharacters string.

If the valueContainsLiteralCharacters property is set to false, then the stringToValue( ) method (and hence the field's getValue( ) method) strips the literals out of the string it returns. For example, if the mask is 20## and the field holds 2013, getValue( ) returns 2013 if valueContainsLiteralCharacters is true, but 13 if valueContainsLiteralCharacters is false.

20.4.2 Constructors

public MaskFormatter( )

Create a new MaskFormatter with no mask.

public MaskFormatter(String mask) throws java.text.ParseException

Create a new MaskFormatter with the specified mask.

20.4.3 Public Methods

public abstract Object stringToValue(String text) throws java.text.ParseException

This method is overridden to strip out any mask literals from text (but only if valueContainsLiteralCharacters is false) before delegating to the superclass. The valueClass property is honored. (See DefaultFormatter's stringToValue( ) method.)

public abstract String valueToString(Object value) throws java.text.ParseException

This method returns value.toString( ), appending placeholder or literal mask characters if necessary.