001package org.xbib.standardnumber;
002
003import java.util.Collection;
004
005/**
006 * A standard number is a number that
007 *
008 * - is backed by an international standard or a de-facto community use
009 *
010 * - can accept alphanumeric values (digits and letters and separator characters)
011 *
012 * - can be normalizedValue
013 *
014 * - can be verified and raise en error is verification fails
015 *
016 * - must have a createChecksum
017 *
018 * - can be formatted to a printable representation
019 *
020 */
021public interface StandardNumber {
022
023    /**
024     * Return the type of this standard number
025     *
026     * @return the type
027     */
028    String type();
029
030    /**
031     * Set the input value of this standard number. The input must be normalized
032     * and verified before being accepted as valid.
033     * @param value the raw input value
034     * @return this standard number
035     */
036    StandardNumber set(CharSequence value);
037
038    /**
039     * Normalize the value by removing all unwanted characters or
040     * replacing characters with the ones required for verification.
041     * @return this standard number
042     */
043    StandardNumber normalize();
044
045    /**
046     * Check this number for validity.
047     * @return true if valid, false otherwise
048     */
049    boolean isValid();
050
051    /**
052     * Verify the number.
053     * @return this standard number if verification was successful
054     * @throws NumberFormatException if verification failed
055     */
056    StandardNumber verify() throws NumberFormatException;
057
058    /**
059     * Indicate that a correct check sum should be computed.
060     * @return this standard number
061     */
062    StandardNumber createChecksum(boolean withChecksum);
063
064    /**
065     * Return normalized value of this standard number.
066     * In most cases, this is also the canonical form of the standard number.
067     * This is a representation without unneccessary characters, useful
068     * for computation purposes, like comparing for equivalence.
069     * @return the normalized value
070     */
071    String normalizedValue();
072
073    /**
074     * Return a formatted value of this standard number
075     * This is best for human-readable representation, but is
076     * not necessarily a format for computation.
077     *
078     * @return a formatted value
079     */
080    String format();
081
082    StandardNumber reset();
083
084    Collection<String> getTypedVariants();
085}