Mask.java

/*
 *  Licensed to the Apache Software Foundation (ASF) under one
 *  or more contributor license agreements.  See the NOTICE file
 *  distributed with this work for additional information
 *  regarding copyright ownership.  The ASF licenses this file
 *  to you under the Apache License, Version 2.0 (the
 *  "License"); you may not use this file except in compliance
 *  with the License.  You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing,
 *  software distributed under the License is distributed on an
 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 *  KIND, either express or implied.  See the License for the
 *  specific language governing permissions and limitations
 *  under the License.
 */

package org.apache.isis.applib.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Provides a mask that a value entry should conform to.
 * 
 * <p>
 * <b>NOTE</b>: this annotation has not been implemented in the Wicket viewer.
 * Since the Wicket viewer is the only currently released viewer, this annotation
 * has been marked as deprecated to flag up this fact.
 * 
 * <p>
 * The characters that can be used are shown in the following table (adapted
 * from masks used by Swing's MaskFormatter, Java's SimpleDateFormat and also
 * Microsoft's MaskedEdit control):
 * 
 * <table border='2'>
 * <tr>
 * <th align='center'>Character</th>
 * <th align='center'>Description</th>
 * <th align='center'>Source</th>
 * </tr>
 * <tr>
 * <td align='center'>#</td>
 * <td align='left'>Digit placeholder.</td>
 * <td align='left'>MS, Swing</td>
 * </tr>
 * <tr>
 * <td align='center'>.</td>
 * <td align='left'>Decimal placeholder. The actual character used is the one
 * specified as the decimal placeholder in your international settings. This
 * character is treated as a literal for masking purposes.</td>
 * <td align='left'>MS</td>
 * </tr>
 * <tr>
 * <td align='center'>,</td>
 * <td align='left'>Thousands separator. The actual character used is the one
 * specified as the thousands separator in your international settings. This
 * character is treated as a literal for masking purposes.</td>
 * <td align='left'>MS</td>
 * </tr>
 * <tr>
 * <td align='center'>:</td>
 * <td align='left'>Time separator. This character is treated as a literal for
 * masking purposes.</td>
 * <td align='left'>MS</td>
 * </tr>
 * <tr>
 * <td align='center'>/</td>
 * <td align='left'>Date separator. This character is treated as a literal for
 * masking purposes.</td>
 * <td align='left'>MS</td>
 * </tr>
 * <tr>
 * <td align='center'>&</td>
 * <td align='left'>Character placeholder. Valid values for this placeholder are
 * ANSI characters in the following ranges: 32-126 and 128-255.</td>
 * <td align='left'>MS</td>
 * </tr>
 * 
 * <tr>
 * <td align='center'>A</td>
 * <td align='left'>Alphanumeric character placeholder (
 * <code>Character.isLetter</code> or <code>Character.isDigit</code>), with
 * entry required. For example: a ~ z, A ~ Z, or 0 ~ 9.</td>
 * <td align='left'>MS</td>
 * </tr>
 * 
 * <tr>
 * <td align='center'>a</td>
 * <td align='left'>Alphanumeric character placeholder (entry optional).</td>
 * <td align='left'>MS</td>
 * </tr>
 * <tr>
 * <td align='center'>9</td>
 * <td align='left'>Digit placeholder (entry optional). For example: 0 ~ 9.</td>
 * <td align='left'>MS</td>
 * </tr>
 * <tr>
 * <td align='center'>?</td>
 * <td align='left'>Letter placeholder (<code>Character.isLetter</code>). For
 * example: a ~ z or A ~ Z.</td>
 * <td align='left'>MS, Swing</td>
 * </tr>
 * <tr>
 * <td align='center'>U</td>
 * <td align='left'>Any character (<code>Character.isLetter</code>). All
 * lowercase letters are mapped to upper case.</td>
 * <td align='left'>Swing</td>
 * </tr>
 * <tr>
 * <td align='center'>L</td>
 * <td align='left'>Any character (<code>Character.isLetter</code>). All
 * lowercase letters are mapped to lower case.</td>
 * <td align='left'>Swing</td>
 * </tr>
 * <tr>
 * <td align='center'>Literal</td>
 * <td align='left'>All other symbols are displayed as literals; that is, as
 * themselves.</td>
 * <td align='left'>MS</td>
 * </tr>
 * </table>
 * 
 * <p>
 * Can also be specified for types that are annotated as <tt>@Value</tt> types.
 * To apply, the value must have string semantics.
 * 
 * <p>
 * Not yet implemented:
 * <table border='2'>
 * <tr>
 * <th align='center'>Character</th>
 * <th align='center'>Description</th>
 * <th align='center'>Source</th>
 * </tr>
 * <tr>
 * <td align='center'>\ or '</td>
 * <td align='left'>Treat the next character in the mask string as a literal.
 * This allows you to include the '#', '&', 'A', and '?' characters in the mask.
 * This character is treated as a literal for masking purposes.</td>
 * <td align='left'>MS (\), Swing (')</td>
 * </tr>
 * <tr>
 * <td align='center'>H</td>
 * <td align='left'>Character.isLetter or Character.isDigit.</td>
 * <td align='left'>Swing</td>
 * </tr>
 * <tr>
 * <td align='center'>yy or yyyy</td>
 * <td align='left'>Year, eg 1996; 96.</td>
 * <td align='left'>DateFormat</td>
 * </tr>
 * <tr>
 * <td align='center'>MM</td>
 * <td align='left'>Two digit representation of month, eg 07 for July.</td>
 * <td align='left'>DateFormat</td>
 * </tr>
 * <tr>
 * <td align='center'>MMM</td>
 * <td align='left'>Three character representation of month, eg <i>Jul</i> for
 * July.</td>
 * <td align='left'>DateFormat</td>
 * </tr>
 * <tr>
 * <td align='center'>d</td>
 * <td align='left'>Day in month, eg 3 or 28.</td>
 * <td align='left'>DateFormat</td>
 * </tr>
 * <tr>
 * <td align='center'>dd</td>
 * <td align='left'>Two digit representation of day in month, eg 03 or 28.</td>
 * <td align='left'>DateFormat</td>
 * </tr>
 * <tr>
 * <td align='center'>HH</td>
 * <td align='left'>Two digit representation of hour in day (24 hour clock), eg
 * 05 or 19.</td>
 * <td align='left'>DateFormat</td>
 * </tr>
 * <tr>
 * <td align='center'>mm</td>
 * <td align='left'>Minute in hour, eg 02 or 47.</td>
 * <td align='left'>DateFormat</td>
 * </tr>
 * <tr>
 * <td align='center'>ss</td>
 * <td align='left'>Second in minute in hour, eg 08 or 35.</td>
 * <td align='left'>DateFormat</td>
 * </tr>
 * </table>
 * 
 * @deprecated - not supported by the Wicket viewer
 */
@Deprecated
@Inherited
@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER })
@Retention(RetentionPolicy.RUNTIME)
public @interface Mask {
    String value();
}