    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *      http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017package org.apache.commons.validator.routines.checkdigit;
    018
    019import java.util.Arrays;
    020
    021import org.apache.commons.validator.routines.CodeValidator;
    022
    023/**
    024 * General Modulus 10 Check Digit calculation/validation.
    025 *
    026 * <h2>How it Works</h2>
    027 * <p>
    028 * This implementation calculates/validates the check digit in the following
    029 * way:
    030 * <ul>
    031 * <li>Converting each character to an integer value using
    032 * <code>Character.getNumericValue(char)</code> - negative integer values from
    033 * that method are invalid.</li>
    034 * <li>Calculating a <i>weighted value</i> by multiplying the character's
    035 * integer value by a <i>weighting factor</i>. The <i>weighting factor</i> is
    036 * selected from the configured <code>postitionWeight</code> array based on its
    037 * position. The <code>postitionWeight</code> values are used either
    038 * left-to-right (when <code>useRightPos=false</code>) or right-to-left (when
    039 * <code>useRightPos=true</code>).</li>
    040 * <li>If <code>sumWeightedDigits=true</code>, the <i>weighted value</i> is
    041 * re-calculated by summing its digits.</li>
    042 * <li>The <i>weighted values</i> of each character are totalled.</li>
    043 * <li>The total modulo 10 will be zero for a code with a valid Check Digit.</li>
    044 * </ul>
    045 * <h2>Limitations</h2>
    046 * <p>
    047 * This implementation has the following limitations:
    048 * <ul>
    049 * <li>It assumes the last character in the code is the Check Digit and
    050 * validates that it is a numeric character.</li>
    051 * <li>The only limitation on valid characters are those that
    052 * <code>Character.getNumericValue(char)</code> returns a positive value. If,
    053 * for example, the code should only contain numbers, this implementation does
    054 * not check that.</li>
    055 * <li>There are no checks on code length.</li>
    056 * </ul>
    057 * <p>
    058 * <b>Note:</b> This implementation can be combined with the
    059 * {@link CodeValidator} in order to ensure the length and characters are valid.
    060 *
    061 * <h2>Example Usage</h2>
    062 * <p>
    063 * This implementation was added after a number of Modulus 10 routines and these
    064 * are shown re-implemented using this routine below:
    065 *
    066 * <p>
    067 * <b>ABA Number</b> Check Digit Routine (equivalent of
    068 * {@link ABANumberCheckDigit}). Weighting factors are <code>[1, 7, 3]</code>
    069 * applied from right to left.
    070 *
    071 * <pre>
    072 * CheckDigit routine = new ModulusTenCheckDigit(new int[] { 1, 7, 3 }, true);
    073 * </pre>
    074 *
    075 * <p>
    076 * <b>CUSIP</b> Check Digit Routine (equivalent of {@link CUSIPCheckDigit}).
    077 * Weighting factors are <code>[1, 2]</code> applied from right to left and the
    078 * digits of the <i>weighted value</i> are summed.
    079 *
    080 * <pre>
    081 * CheckDigit routine = new ModulusTenCheckDigit(new int[] { 1, 2 }, true, true);
    082 * </pre>
    083 *
    084 * <p>
    085 * <b>EAN-13 / UPC</b> Check Digit Routine (equivalent of
    086 * {@link EAN13CheckDigit}). Weighting factors are <code>[1, 3]</code> applied
    087 * from right to left.
    088 *
    089 * <pre>
    090 * CheckDigit routine = new ModulusTenCheckDigit(new int[] { 1, 3 }, true);
    091 * </pre>
    092 *
    093 * <p>
    094 * <b>Luhn</b> Check Digit Routine (equivalent of {@link LuhnCheckDigit}).
    095 * Weighting factors are <code>[1, 2]</code> applied from right to left and the
    096 * digits of the <i>weighted value</i> are summed.
    097 *
    098 * <pre>
    099 * CheckDigit routine = new ModulusTenCheckDigit(new int[] { 1, 2 }, true, true);
    100 * </pre>
    101 *
    102 * <p>
    103 * <b>SEDOL</b> Check Digit Routine (equivalent of {@link SedolCheckDigit}).
    104 * Weighting factors are <code>[1, 3, 1, 7, 3, 9, 1]</code> applied from left to
    105 * right.
    106 *
    107 * <pre>
    108 * CheckDigit routine = new ModulusTenCheckDigit(new int[] { 1, 3, 1, 7, 3, 9, 1 });
    109 * </pre>
    110 *
    111 * @since Validator 1.6
    112 * @version $Revision: 1739356 $
    113 */
    114public final class ModulusTenCheckDigit extends ModulusCheckDigit {
    115
    116    private static final long serialVersionUID = -3752929983453368497L;
    117
    118    private final int[] postitionWeight;
    119    private final boolean useRightPos;
    120    private final boolean sumWeightedDigits;
    121
    122    /**
    123     * Construct a modulus 10 Check Digit routine with the specified weighting
    124     * from left to right.
    125     *
    126     * @param postitionWeight the weighted values to apply based on the
    127     *            character position
    128     */
    129    public ModulusTenCheckDigit(int[] postitionWeight) {
    130        this(postitionWeight, false, false);
    131    }
    132
    133    /**
    134     * Construct a modulus 10 Check Digit routine with the specified weighting,
    135     * indicating whether its from the left or right.
    136     *
    137     * @param postitionWeight the weighted values to apply based on the
    138     *            character position
    139     * @param useRightPos <code>true</code> if use positionWeights from right to
    140     *            left
    141     */
    142    public ModulusTenCheckDigit(int[] postitionWeight, boolean useRightPos) {
    143        this(postitionWeight, useRightPos, false);
    144    }
    145
    146    /**
    147     * Construct a modulus 10 Check Digit routine with the specified weighting,
    148     * indicating whether its from the left or right and whether the weighted
    149     * digits should be summed.
    150     *
    151     * @param postitionWeight the weighted values to apply based on the
    152     *            character position
    153     * @param useRightPos <code>true</code> if use positionWeights from right to
    154     *            left
    155     * @param sumWeightedDigits <code>true</code> if sum the digits of the
    156     *            weighted value
    157     */
    158    public ModulusTenCheckDigit(int[] postitionWeight, boolean useRightPos, boolean sumWeightedDigits) {
    159        super(10); // CHECKSTYLE IGNORE MagicNumber
    160        this.postitionWeight = Arrays.copyOf(postitionWeight, postitionWeight.length);
    161        this.useRightPos = useRightPos;
    162        this.sumWeightedDigits = sumWeightedDigits;
    163    }
    164
    165    /**
    166     * Validate a modulus check digit for a code.
    167     * <p>
    168     * Note: assumes last digit is the check digit
    169     *
    170     * @param code The code to validate
    171     * @return <code>true</code> if the check digit is valid, otherwise
    172     *         <code>false</code>
    173     */
    174    @Override
    175    public boolean isValid(String code) {
    176        if (code == null || code.length() == 0) {
    177            return false;
    178        }
    179        if (!Character.isDigit(code.charAt(code.length() - 1))) {
    180            return false;
    181        }
    182
    183        return super.isValid(code);
    184    }
    185
    186    /**
    187     * Convert a character at a specified position to an integer value.
    188     * <p>
    189     * <b>Note:</b> this implementation only handlers values that
    190     * Character.getNumericValue(char) returns a non-negative number.
    191     *
    192     * @param character The character to convert
    193     * @param leftPos The position of the character in the code, counting from
    194     *            left to right (for identifying the position in the string)
    195     * @param rightPos The position of the character in the code, counting from
    196     *            right to left (not used here)
    197     * @return The integer value of the character
    198     * @throws CheckDigitException if Character.getNumericValue(char) returns a
    199     *             negative number
    200     */
    201    @Override
    202    protected int toInt(char character, int leftPos, int rightPos) throws CheckDigitException {
    203        int num = Character.getNumericValue(character);
    204        if (num < 0) {
    205            throw new CheckDigitException("Invalid Character[" + leftPos + "] = '" + character + "'");
    206        }
    207        return num;
    208    }
    209
    210    /**
    211     * Calculates the <i>weighted</i> value of a character in the code at a
    212     * specified position.
    213     *
    214     * @param charValue The numeric value of the character.
    215     * @param leftPos The position of the character in the code, counting from
    216     *            left to right
    217     * @param rightPos The position of the character in the code, counting from
    218     *            right to left
    219     * @return The weighted value of the character.
    220     */
    221    @Override
    222    protected int weightedValue(int charValue, int leftPos, int rightPos) {
    223        int pos = useRightPos ? rightPos : leftPos;
    224        int weight = postitionWeight[(pos - 1) % postitionWeight.length];
    225        int weightedValue = charValue * weight;
    226        if (sumWeightedDigits) {
    227            weightedValue = ModulusCheckDigit.sumDigits(weightedValue);
    228        }
    229        return weightedValue;
    230    }
    231
    232    /**
    233     * Return a string representation of this implementation.
    234     *
    235     * @return a string representation
    236     */
    237    @Override
    238    public String toString() {
    239        return getClass().getSimpleName() + "[postitionWeight=" + Arrays.toString(postitionWeight) + ", useRightPos="
    240                + useRightPos + ", sumWeightedDigits=" + sumWeightedDigits + "]";
    241    }
    242
    243}