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; 018 019import java.io.Serializable; 020 021import org.apache.commons.validator.routines.checkdigit.CheckDigitException; 022import org.apache.commons.validator.routines.checkdigit.EAN13CheckDigit; 023import org.apache.commons.validator.routines.checkdigit.ISSNCheckDigit; 024 025/** 026 * International Standard Serial Number (ISSN) 027 * is an eight-digit serial number used to 028 * uniquely identify a serial publication. 029 * <pre> 030 * The format is: 031 * 032 * ISSN dddd-dddC 033 * where: 034 * d = decimal digit (0-9) 035 * C = checksum (0-9 or X) 036 * 037 * The checksum is formed by adding the first 7 digits multiplied by 038 * the position in the entire number (counting from the right). 039 * 040 * For example, abcd-efg would be 8a + 7b + 6c + 5d + 4e +3f +2g. 041 * The check digit is modulus 11, where the value 10 is represented by 'X' 042 * For example: 043 * ISSN 0317-8471 044 * ISSN 1050-124X 045 * 046 * This class strips off the 'ISSN ' prefix if it is present before passing 047 * the remainder to the checksum routine. 048 * 049 * </pre> 050 * <p> 051 * Note: the {@link #isValid(String)} and {@link #validate(String)} methods strip off any leading 052 * or trailing spaces before doing the validation. 053 * To ensure that only a valid code (without 'ISSN ' prefix) is passed to a method, 054 * use the following code: 055 * <pre> 056 * Object valid = validator.validate(input); 057 * if (valid != null) { 058 * some_method(valid.toString()); 059 * } 060 * </pre> 061 * @since 1.5.0 062 */ 063public class ISSNValidator implements Serializable { 064 065 private static final long serialVersionUID = 4319515687976420405L; 066 067 private static final String ISSN_REGEX = "(?:ISSN )?(\\d{4})-(\\d{3}[0-9X])$"; // We don't include the '-' in the code, so it is 8 chars 068 069 private static final int ISSN_LEN = 8; 070 071 private static final String ISSN_PREFIX = "977"; 072 073 private static final String EAN_ISSN_REGEX = "^(977)(?:(\\d{10}))$"; 074 075 private static final int EAN_ISSN_LEN = 13; 076 077 private static final CodeValidator VALIDATOR = new CodeValidator(ISSN_REGEX, ISSN_LEN, ISSNCheckDigit.ISSN_CHECK_DIGIT); 078 079 private static final CodeValidator EAN_VALIDATOR = new CodeValidator(EAN_ISSN_REGEX, EAN_ISSN_LEN, EAN13CheckDigit.EAN13_CHECK_DIGIT); 080 081 /** ISSN Code Validator */ 082 private static final ISSNValidator ISSN_VALIDATOR = new ISSNValidator(); 083 084 /** 085 * Return a singleton instance of the ISSN validator 086 * 087 * @return A singleton instance of the ISSN validator. 088 */ 089 public static ISSNValidator getInstance() { 090 return ISSN_VALIDATOR; 091 } 092 093 /** 094 * Check the code is a valid EAN code. 095 * <p> 096 * If valid, this method returns the EAN code 097 * 098 * @param code The code to validate. 099 * @return A valid EAN code if valid, otherwise <code>null</code>. 100 * @since 1.7 101 */ 102 public Object validateEan(String code) { 103 return EAN_VALIDATOR.validate(code); 104 } 105 106 /** 107 * Check the code is a valid ISSN code after any transformation 108 * by the validate routine. 109 * @param code The code to validate. 110 * @return <code>true</code> if a valid ISSN 111 * code, otherwise <code>false</code>. 112 */ 113 public boolean isValid(String code) { 114 return VALIDATOR.isValid(code); 115 } 116 117 /** 118 * Check the code is valid ISSN code. 119 * <p> 120 * If valid, this method returns the ISSN code with 121 * the 'ISSN ' prefix removed (if it was present) 122 * 123 * @param code The code to validate. 124 * @return A valid ISSN code if valid, otherwise <code>null</code>. 125 */ 126 public Object validate(String code) { 127 return VALIDATOR.validate(code); 128 } 129 130 /** 131 * Convert an ISSN code to an EAN-13 code. 132 * <p> 133 * This method requires a valid ISSN code. 134 * It may contain a leading 'ISSN ' prefix, 135 * as the input is passed through the {@link #validate(String)} 136 * method. 137 * 138 * @param issn The ISSN code to convert 139 * @param suffix the two digit suffix, e.g. "00" 140 * @return A converted EAN-13 code or <code>null</code> 141 * if the input ISSN code is not valid 142 */ 143 public String convertToEAN13(String issn, String suffix) { 144 145 if (suffix == null || !suffix.matches("\\d\\d")) { 146 throw new IllegalArgumentException("Suffix must be two digits: '" + suffix + "'"); 147 } 148 149 Object result = validate(issn); 150 if (result == null) { 151 return null; 152 } 153 154 // Calculate the new EAN-13 code 155 final String input = result.toString(); 156 String ean13 = ISSN_PREFIX + input.substring(0, input.length() -1) + suffix; 157 try { 158 String checkDigit = EAN13CheckDigit.EAN13_CHECK_DIGIT.calculate(ean13); 159 ean13 += checkDigit; 160 return ean13; 161 } catch (CheckDigitException e) { // Should not happen 162 throw new IllegalArgumentException("Check digit error for '" + ean13 + "' - " + e.getMessage()); 163 } 164 165 } 166 167 /** 168 * Extract an ISSN code from an ISSN-EAN-13 code. 169 * <p> 170 * This method requires a valid ISSN-EAN-13 code with NO formatting 171 * characters. 172 * That is a 13 digit EAN-13 code with the '977' prefix 173 * 174 * @param ean13 The ISSN code to convert 175 * @return A valid ISSN code or <code>null</code> 176 * if the input ISSN EAN-13 code is not valid 177 * @since 1.7 178 */ 179 public String extractFromEAN13(String ean13) { 180 String input = ean13.trim(); 181 if (input.length() != EAN_ISSN_LEN ) { 182 throw new IllegalArgumentException("Invalid length " + input.length() + " for '" + input + "'"); 183 } 184 if (!input.startsWith(ISSN_PREFIX)) { 185 throw new IllegalArgumentException("Prefix must be " + ISSN_PREFIX + " to contain an ISSN: '" + ean13 + "'"); 186 } 187 Object result = validateEan(input); 188 if (result == null) { 189 return null; 190 } 191 // Calculate the ISSN code 192 input = result.toString(); 193 try { 194 //CHECKSTYLE:OFF: MagicNumber 195 String issnBase = input.substring(3,10); // TODO: how to derive these 196 //CHECKSTYLE:ON: MagicNumber 197 String checkDigit = ISSNCheckDigit.ISSN_CHECK_DIGIT.calculate(issnBase); 198 String issn = issnBase + checkDigit; 199 return issn; 200 } catch (CheckDigitException e) { // Should not happen 201 throw new IllegalArgumentException("Check digit error for '" + ean13 + "' - " + e.getMessage()); 202 } 203 } 204}