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}