001 package org.nakedobjects.applib.annotation;
002
003 import java.lang.annotation.ElementType;
004 import java.lang.annotation.Inherited;
005 import java.lang.annotation.Retention;
006 import java.lang.annotation.RetentionPolicy;
007 import java.lang.annotation.Target;
008
009
010 /**
011 * Provides a mask that a value entry should conform to
012 *
013 * A mask to apply to string attributes.
014 *
015 * <p>
016 * The characters that can be used are shown in the following table (adapted from masks used by Swing's
017 * MaskFormatter, Java's SimpleDateFormat and also Microsoft's MaskedEdit control):
018 *
019 * <table border='2'>
020 * <tr>
021 * <th align='center'>Character</th>
022 * <th align='center'>Description</th>
023 * <th align='center'>Source</th>
024 * </tr>
025 * <tr>
026 * <td align='center'>#</td>
027 * <td align='left'>Digit placeholder.</td>
028 * <td align='left'>MS, Swing</td>
029 * </tr>
030 * <tr>
031 * <td align='center'>.</td>
032 * <td align='left'>Decimal placeholder. The actual character used is the one specified as the decimal
033 * placeholder in your international settings. This character is treated as a literal for masking purposes.</td>
034 * <td align='left'>MS</td>
035 * </tr>
036 * <tr>
037 * <td align='center'>,</td>
038 * <td align='left'>Thousands separator. The actual character used is the one specified as the thousands
039 * separator in your international settings. This character is treated as a literal for masking purposes.</td>
040 * <td align='left'>MS</td>
041 * </tr>
042 * <tr>
043 * <td align='center'>:</td>
044 * <td align='left'>Time separator. This character is treated as a literal for masking purposes.</td>
045 * <td align='left'>MS</td>
046 * </tr>
047 * <tr>
048 * <td align='center'>/</td>
049 * <td align='left'>Date separator. This character is treated as a literal for masking purposes.</td>
050 * <td align='left'>MS</td>
051 * </tr>
052 * <tr>
053 * <td align='center'>&</td>
054 * <td align='left'>Character placeholder. Valid values for this placeholder are ANSI characters in the
055 * following ranges: 32-126 and 128-255.</td>
056 * <td align='left'>MS</td>
057 * </tr>
058 *
059 * <tr>
060 * <td align='center'>A</td>
061 * <td align='left'>Alphanumeric character placeholder (<code>Character.isLetter</code> or
062 * <code>Character.isDigit</code>), with entry required. For example: a ~ z, A ~ Z, or 0 ~ 9.</td>
063 * <td align='left'>MS</td>
064 * </tr>
065 *
066 * <tr>
067 * <td align='center'>a</td>
068 * <td align='left'>Alphanumeric character placeholder (entry optional).</td>
069 * <td align='left'>MS</td>
070 * </tr>
071 * <tr>
072 * <td align='center'>9</td>
073 * <td align='left'>Digit placeholder (entry optional). For example: 0 ~ 9.</td>
074 * <td align='left'>MS</td>
075 * </tr>
076 * <tr>
077 * <td align='center'>?</td>
078 * <td align='left'>Letter placeholder (<code>Character.isLetter</code>). For example: a ~ z or A ~ Z.</td>
079 * <td align='left'>MS, Swing</td>
080 * </tr>
081 * <tr>
082 * <td align='center'>U</td>
083 * <td align='left'>Any character (<code>Character.isLetter</code>). All lowercase letters are mapped to
084 * upper case.</td>
085 * <td align='left'>Swing</td>
086 * </tr>
087 * <tr>
088 * <td align='center'>L</td>
089 * <td align='left'>Any character (<code>Character.isLetter</code>). All lowercase letters are mapped to
090 * lower case.</td>
091 * <td align='left'>Swing</td>
092 * </tr>
093 * <tr>
094 * <td align='center'>Literal</td>
095 * <td align='left'>All other symbols are displayed as literals; that is, as themselves.</td>
096 * <td align='left'>MS</td>
097 * </tr>
098 * </table>
099 *
100 * <p>
101 * Can also be specified for types that are annotated as <tt>@Value</tt> types. To apply, the value must have string semantics.
102 *
103 * <p>
104 * Not yet implemented: <table border='2'>
105 * <tr>
106 * <th align='center'>Character</th>
107 * <th align='center'>Description</th>
108 * <th align='center'>Source</th>
109 * </tr>
110 * <tr>
111 * <td align='center'>\ or '</td>
112 * <td align='left'>Treat the next character in the mask string as a literal. This allows you to include the
113 * '#', '&', 'A', and '?' characters in the mask. This character is treated as a literal for masking purposes.</td>
114 * <td align='left'>MS (\), Swing (')</td>
115 * </tr>
116 * <tr>
117 * <td align='center'>H</td>
118 * <td align='left'>Character.isLetter or Character.isDigit.</td>
119 * <td align='left'>Swing</td>
120 * </tr>
121 * <tr>
122 * <td align='center'>yy or yyyy</td>
123 * <td align='left'>Year, eg 1996; 96.</td>
124 * <td align='left'>DateFormat</td>
125 * </tr>
126 * <tr>
127 * <td align='center'>MM</td>
128 * <td align='left'>Two digit representation of month, eg 07 for July.</td>
129 * <td align='left'>DateFormat</td>
130 * </tr>
131 * <tr>
132 * <td align='center'>MMM</td>
133 * <td align='left'>Three character representation of month, eg <i>Jul</i> for July.</td>
134 * <td align='left'>DateFormat</td>
135 * </tr>
136 * <tr>
137 * <td align='center'>d</td>
138 * <td align='left'>Day in month, eg 3 or 28.</td>
139 * <td align='left'>DateFormat</td>
140 * </tr>
141 * <tr>
142 * <td align='center'>dd</td>
143 * <td align='left'>Two digit representation of day in month, eg 03 or 28.</td>
144 * <td align='left'>DateFormat</td>
145 * </tr>
146 * <tr>
147 * <td align='center'>HH</td>
148 * <td align='left'>Two digit representation of hour in day (24 hour clock), eg 05 or 19.</td>
149 * <td align='left'>DateFormat</td>
150 * </tr>
151 * <tr>
152 * <td align='center'>mm</td>
153 * <td align='left'>Minute in hour, eg 02 or 47.</td>
154 * <td align='left'>DateFormat</td>
155 * </tr>
156 * <tr>
157 * <td align='center'>ss</td>
158 * <td align='left'>Second in minute in hour, eg 08 or 35.</td>
159 * <td align='left'>DateFormat</td>
160 * </tr>
161 * </table>
162 *
163 */
164 @Inherited
165 @Target( { ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER })
166 @Retention(RetentionPolicy.RUNTIME)
167 public @interface Mask {
168 String value();
169 }
170
171 // Copyright (c) Naked Objects Group Ltd.