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