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 org.apache.commons.validator.routines.checkdigit.CheckDigit;
020import org.apache.commons.validator.routines.checkdigit.LuhnCheckDigit;
021import java.io.Serializable;
022import java.util.Collections;
023import java.util.List;
024import java.util.ArrayList;
025
026/**
027 * Perform credit card validations.
028 *
029 * <p>
030 * By default, all supported card types are allowed.  You can specify which
031 * cards should pass validation by configuring the validation options. For
032 * example,
033 * </p>
034 *
035 * <pre>
036 * <code>CreditCardValidator ccv = new CreditCardValidator(CreditCardValidator.AMEX + CreditCardValidator.VISA);</code>
037 * </pre>
038 *
039 * <p>
040 * configures the validator to only pass American Express and Visa cards.
041 * If a card type is not directly supported by this class, you can implement
042 * the CreditCardType interface and pass an instance into the
043 * <code>addAllowedCardType</code> method.
044 * </p>
045 *
046 * <p>
047 * For a similar implementation in Perl, reference Sean M. Burke's
048 * <a href="http://www.speech.cs.cmu.edu/~sburke/pub/luhn_lib.html">script</a>.
049 * More information can be found in Michael Gilleland's essay 
050 * <a href="http://web.archive.org/web/20120614072656/http://www.merriampark.com/anatomycc.htm">Anatomy of Credit Card Numbers</a>.
051 * </p>
052 *
053 * @version $Revision: 1713225 $
054 * @since Validator 1.4
055 */
056public class CreditCardValidator implements Serializable {
057
058    private static final long serialVersionUID = 5955978921148959496L;
059
060    /**
061     * Option specifying that no cards are allowed.  This is useful if
062     * you want only custom card types to validate so you turn off the
063     * default cards with this option.
064     *
065     * <pre>
066     * <code>
067     * CreditCardValidator v = new CreditCardValidator(CreditCardValidator.NONE);
068     * v.addAllowedCardType(customType);
069     * v.isValid(aCardNumber);
070     * </code>
071     * </pre>
072     */
073    public static final long NONE = 0;
074
075    /**
076     * Option specifying that American Express cards are allowed.
077     */
078    public static final long AMEX = 1 << 0;
079
080    /**
081     * Option specifying that Visa cards are allowed.
082     */
083    public static final long VISA = 1 << 1;
084
085    /**
086     * Option specifying that Mastercard cards are allowed.
087     */
088    public static final long MASTERCARD = 1 << 2;
089
090    /**
091     * Option specifying that Discover cards are allowed.
092     */
093    public static final long DISCOVER = 1 << 3;
094
095    /**
096     * Option specifying that Diners cards are allowed.
097     */
098    public static final long DINERS = 1 << 4;
099
100    /**
101     * Option specifying that VPay (Visa) cards are allowed.
102     * @since 1.5.0
103     */
104    public static final long VPAY = 1 << 5;
105
106
107    /**
108     * The CreditCardTypes that are allowed to pass validation.
109     */
110    private final List<CodeValidator> cardTypes = new ArrayList<CodeValidator>();
111
112    /**
113     * Luhn checkdigit validator for the card numbers.
114     */
115    private static final CheckDigit LUHN_VALIDATOR = LuhnCheckDigit.LUHN_CHECK_DIGIT;
116
117    /** American Express (Amex) Card Validator */
118    public static final CodeValidator AMEX_VALIDATOR = new CodeValidator("^(3[47]\\d{13})$", LUHN_VALIDATOR);
119
120    /** Diners Card Validator */
121    public static final CodeValidator DINERS_VALIDATOR = new CodeValidator("^(30[0-5]\\d{11}|3095\\d{10}|36\\d{12}|3[8-9]\\d{12})$", LUHN_VALIDATOR);
122
123    /** Discover Card regular expressions */
124    private static final RegexValidator DISCOVER_REGEX = new RegexValidator(new String[] {"^(6011\\d{12})$", "^(64[4-9]\\d{13})$", "^(65\\d{14})$"});
125
126    /** Discover Card Validator */
127    public static final CodeValidator DISCOVER_VALIDATOR = new CodeValidator(DISCOVER_REGEX, LUHN_VALIDATOR);
128
129    /** Mastercard Card Validator */
130    public static final CodeValidator MASTERCARD_VALIDATOR = new CodeValidator("^(5[1-5]\\d{14})$", LUHN_VALIDATOR);
131
132    /** Visa Card Validator */
133    public static final CodeValidator VISA_VALIDATOR = new CodeValidator("^(4)(\\d{12}|\\d{15})$", LUHN_VALIDATOR);
134
135    /** VPay (Visa) Card Validator 
136     * @since 1.5.0
137     */
138    public static final CodeValidator VPAY_VALIDATOR = new CodeValidator("^(4)(\\d{12,18})$", LUHN_VALIDATOR);
139
140    /**
141     * Create a new CreditCardValidator with default options.
142     */
143    public CreditCardValidator() {
144        this(AMEX + VISA + MASTERCARD + DISCOVER);
145    }
146
147    /**
148     * Create a new CreditCardValidator with the specified options.
149     * @param options Pass in
150     * CreditCardValidator.VISA + CreditCardValidator.AMEX to specify that
151     * those are the only valid card types.
152     */
153    public CreditCardValidator(long options) {
154        super();
155
156        if (isOn(options, VISA)) {
157            this.cardTypes.add(VISA_VALIDATOR);
158        }
159
160        if (isOn(options, VPAY)) {
161            this.cardTypes.add(VPAY_VALIDATOR);
162        }
163
164        if (isOn(options, AMEX)) {
165            this.cardTypes.add(AMEX_VALIDATOR);
166        }
167
168        if (isOn(options, MASTERCARD)) {
169            this.cardTypes.add(MASTERCARD_VALIDATOR);
170        }
171
172        if (isOn(options, DISCOVER)) {
173            this.cardTypes.add(DISCOVER_VALIDATOR);
174        }
175
176        if (isOn(options, DINERS)) {
177            this.cardTypes.add(DINERS_VALIDATOR);
178        }
179    }
180
181    /**
182     * Create a new CreditCardValidator with the specified {@link CodeValidator}s.
183     * @param creditCardValidators Set of valid code validators
184     */
185    public CreditCardValidator(CodeValidator[] creditCardValidators) {
186        if (creditCardValidators == null) {
187            throw new IllegalArgumentException("Card validators are missing");
188        }
189        Collections.addAll(cardTypes, creditCardValidators);
190    }
191
192    /**
193     * Checks if the field is a valid credit card number.
194     * @param card The card number to validate.
195     * @return Whether the card number is valid.
196     */
197    public boolean isValid(String card) {
198        if (card == null || card.length() == 0) {
199            return false;
200        }
201        for (CodeValidator cardType : cardTypes) {
202            if (cardType.isValid(card)) {
203                return true;
204            }
205        }
206        return false;
207    }
208
209    /**
210     * Checks if the field is a valid credit card number.
211     * @param card The card number to validate.
212     * @return The card number if valid or <code>null</code>
213     * if invalid.
214     */
215    public Object validate(String card) {
216        if (card == null || card.length() == 0) {
217            return null;
218        }
219        Object result = null;
220        for (CodeValidator cardType : cardTypes) {
221            result = cardType.validate(card);
222            if (result != null) {
223                return result;
224            }
225        }
226        return null;
227
228    }
229    /**
230     * Tests whether the given flag is on.  If the flag is not a power of 2
231     * (ie. 3) this tests whether the combination of flags is on.
232     *
233     * @param options The options specified.
234     * @param flag Flag value to check.
235     *
236     * @return whether the specified flag value is on.
237     */
238    private boolean isOn(long options, long flag) {
239        return (options & flag) > 0;
240    }
241
242}