    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.ISBN10CheckDigit;
    024
    025/**
    026 * <b>ISBN-10</b> and <b>ISBN-13</b> Code Validation.
    027 * <p>
    028 * This validator validates the code is either a valid ISBN-10
    029 * (using a {@link CodeValidator} with the {@link ISBN10CheckDigit})
    030 * or a valid ISBN-13 code (using a {@link CodeValidator} with the
    031 * the {@link EAN13CheckDigit} routine).
    032 * <p>
    033 * The <code>validate()</code> methods return the ISBN code with formatting
    034 * characters removed if valid or <code>null</code> if invalid.
    035 * <p>
    036 * This validator also provides the facility to convert ISBN-10 codes to
    037 * ISBN-13 if the <code>convert</code> property is {@code true}.
    038 * <p>
    039 * From 1st January 2007 the book industry will start to use a new 13 digit
    040 * ISBN number (rather than this 10 digit ISBN number). ISBN-13 codes are
    041 * <a href="http://en.wikipedia.org/wiki/European_Article_Number">EAN</a>
    042 * codes, for more information see:</p>
    043 *
    044 * <ul>
    045 *   <li><a href="http://en.wikipedia.org/wiki/ISBN">Wikipedia - International
    046 *       Standard Book Number (ISBN)</a>.</li>
    047 *   <li>EAN - see
    048 *       <a href="http://en.wikipedia.org/wiki/European_Article_Number">Wikipedia -
    049 *       European Article Number</a>.</li>
    050 *   <li><a href="http://www.isbn.org/standards/home/isbn/transition.asp">ISBN-13
    051 *       Transition details</a>.</li>
    052 * </ul>
    053 *
    054 * <p>ISBN-13s are either prefixed with 978 or 979. 978 prefixes are only assigned
    055 * to the ISBN agency. 979 prefixes may be assigned to ISBNs or ISMNs
    056 * (<a href="https://www.ismn-international.org/">International
    057 * Standard Music Numbers</a>).
    058 * <ul>
    059 *     <li>979-0 are assigned to the ISMN agency</li>
    060 *     <li>979-10, 979-11, 979-12 are assigned to the ISBN agency</li>
    061 * </ul>
    062 * All other 979 prefixed EAN-13 numbers have not yet been assigned to an agency. The
    063 * validator validates all 13 digit codes with 978 or 979 prefixes.
    064 *
    065 * @since 1.4
    066 */
    067public class ISBNValidator implements Serializable {
    068
    069    private static final int ISBN_10_LEN = 10;
    070
    071    private static final long serialVersionUID = 4319515687976420405L;
    072
    073    private static final String SEP = "(?:\\-|\\s)";
    074    private static final String GROUP = "(\\d{1,5})";
    075    private static final String PUBLISHER = "(\\d{1,7})";
    076    private static final String TITLE = "(\\d{1,6})";
    077
    078    /**
    079     * ISBN-10 consists of 4 groups of numbers separated by either dashes (-)
    080     * or spaces.  The first group is 1-5 characters, second 1-7, third 1-6,
    081     * and fourth is 1 digit or an X.
    082     */
    083    static final String ISBN10_REGEX = "^(?:(\\d{9}[0-9X])|(?:" + GROUP + SEP + PUBLISHER + SEP + TITLE + SEP + "([0-9X])))$";
    084
    085    /**
    086     * ISBN-13 consists of 5 groups of numbers separated by either dashes (-)
    087     * or spaces.  The first group is 978 or 979, the second group is
    088     * 1-5 characters, third 1-7, fourth 1-6, and fifth is 1 digit.
    089     */
    090    static final String ISBN13_REGEX = "^(978|979)(?:(\\d{10})|(?:" + SEP + GROUP + SEP + PUBLISHER + SEP + TITLE + SEP + "([0-9])))$";
    091
    092    /** ISBN Code Validator (which converts ISBN-10 codes to ISBN-13 */
    093    private static final ISBNValidator ISBN_VALIDATOR = new ISBNValidator();
    094
    095    /** ISBN Code Validator (which converts ISBN-10 codes to ISBN-13 */
    096    private static final ISBNValidator ISBN_VALIDATOR_NO_CONVERT = new ISBNValidator(false);
    097
    098    /**
    099     * Return a singleton instance of the ISBN validator which
    100     * converts ISBN-10 codes to ISBN-13.
    101     *
    102     * @return A singleton instance of the ISBN validator.
    103     */
    104    public static ISBNValidator getInstance() {
    105        return ISBN_VALIDATOR;
    106    }
    107
    108    /**
    109     * Return a singleton instance of the ISBN validator specifying
    110     * whether ISBN-10 codes should be converted to ISBN-13.
    111     *
    112     * @param convert {@code true} if valid ISBN-10 codes
    113     * should be converted to ISBN-13 codes or {@code false}
    114     * if valid ISBN-10 codes should be returned unchanged.
    115     * @return A singleton instance of the ISBN validator.
    116     */
    117    public static ISBNValidator getInstance(final boolean convert) {
    118        return convert ? ISBN_VALIDATOR : ISBN_VALIDATOR_NO_CONVERT;
    119    }
    120
    121    /** ISBN-10 Code Validator */
    122    private final CodeValidator isbn10Validator = new CodeValidator(ISBN10_REGEX, 10, ISBN10CheckDigit.ISBN10_CHECK_DIGIT);
    123
    124    /** ISBN-13 Code Validator */
    125    private final CodeValidator isbn13Validator = new CodeValidator(ISBN13_REGEX, 13, EAN13CheckDigit.EAN13_CHECK_DIGIT);
    126
    127    private final boolean convert;
    128
    129    /**
    130     * Constructs an ISBN validator which converts ISBN-10 codes
    131     * to ISBN-13.
    132     */
    133    public ISBNValidator() {
    134        this(true);
    135    }
    136
    137    /**
    138     * Constructs an ISBN validator indicating whether
    139     * ISBN-10 codes should be converted to ISBN-13.
    140     *
    141     * @param convert {@code true} if valid ISBN-10 codes
    142     * should be converted to ISBN-13 codes or {@code false}
    143     * if valid ISBN-10 codes should be returned unchanged.
    144     */
    145    public ISBNValidator(final boolean convert) {
    146        this.convert = convert;
    147    }
    148
    149    /**
    150     * Convert an ISBN-10 code to an ISBN-13 code.
    151     * <p>
    152     * This method requires a valid ISBN-10 with NO formatting
    153     * characters.
    154     *
    155     * @param isbn10 The ISBN-10 code to convert
    156     * @return A converted ISBN-13 code or <code>null</code>
    157     * if the ISBN-10 code is not valid
    158     */
    159    public String convertToISBN13(final String isbn10) {
    160
    161        if (isbn10 == null) {
    162            return null;
    163        }
    164
    165        final String input = isbn10.trim();
    166        if (input.length() != ISBN_10_LEN) {
    167            throw new IllegalArgumentException("Invalid length " + input.length() + " for '" + input + "'");
    168        }
    169
    170        // Calculate the new ISBN-13 code (drop the original checkdigit)
    171        String isbn13 = "978" + input.substring(0, ISBN_10_LEN - 1);
    172        try {
    173            final String checkDigit = isbn13Validator.getCheckDigit().calculate(isbn13);
    174            isbn13 += checkDigit;
    175            return isbn13;
    176        } catch (final CheckDigitException e) {
    177            throw new IllegalArgumentException("Check digit error for '" + input + "' - " + e.getMessage());
    178        }
    179
    180    }
    181
    182    /**
    183     * Check the code is either a valid ISBN-10 or ISBN-13 code.
    184     *
    185     * @param code The code to validate.
    186     * @return {@code true} if a valid ISBN-10 or
    187     * ISBN-13 code, otherwise {@code false}.
    188     */
    189    public boolean isValid(final String code) {
    190        return isValidISBN13(code) || isValidISBN10(code);
    191    }
    192
    193    /**
    194     * Check the code is a valid ISBN-10 code.
    195     *
    196     * @param code The code to validate.
    197     * @return {@code true} if a valid ISBN-10
    198     * code, otherwise {@code false}.
    199     */
    200    public boolean isValidISBN10(final String code) {
    201        return isbn10Validator.isValid(code);
    202    }
    203
    204    /**
    205     * Check the code is a valid ISBN-13 code.
    206     *
    207     * @param code The code to validate.
    208     * @return {@code true} if a valid ISBN-13
    209     * code, otherwise {@code false}.
    210     */
    211    public boolean isValidISBN13(final String code) {
    212        return isbn13Validator.isValid(code);
    213    }
    214
    215    /**
    216     * Check the code is either a valid ISBN-10 or ISBN-13 code.
    217     * <p>
    218     * If valid, this method returns the ISBN code with
    219     * formatting characters removed (i.e. space or hyphen).
    220     * <p>
    221     * Converts an ISBN-10 codes to ISBN-13 if
    222     * <code>convertToISBN13</code> is {@code true}.
    223     *
    224     * @param code The code to validate.
    225     * @return A valid ISBN code if valid, otherwise <code>null</code>.
    226     */
    227    public String validate(final String code) {
    228        String result = validateISBN13(code);
    229        if (result == null) {
    230            result = validateISBN10(code);
    231            if (result != null && convert) {
    232                result = convertToISBN13(result);
    233            }
    234        }
    235        return result;
    236    }
    237
    238    /**
    239     * Check the code is a valid ISBN-10 code.
    240     * <p>
    241     * If valid, this method returns the ISBN-10 code with
    242     * formatting characters removed (i.e. space or hyphen).
    243     *
    244     * @param code The code to validate.
    245     * @return A valid ISBN-10 code if valid,
    246     * otherwise <code>null</code>.
    247     */
    248    public String validateISBN10(final String code) {
    249        final Object result = isbn10Validator.validate(code);
    250        return result == null ? null : result.toString();
    251    }
    252
    253    /**
    254     * Check the code is a valid ISBN-13 code.
    255     * <p>
    256     * If valid, this method returns the ISBN-13 code with
    257     * formatting characters removed (i.e. space or hyphen).
    258     *
    259     * @param code The code to validate.
    260     * @return A valid ISBN-13 code if valid,
    261     * otherwise <code>null</code>.
    262     */
    263    public String validateISBN13(final String code) {
    264        final Object result = isbn13Validator.validate(code);
    265        return result == null ? null : result.toString();
    266    }
    267
    268}