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}