/*
    * Licensed to the Apache Software Foundation (ASF) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * The ASF licenses this file to You under the Apache License, Version 2.0
    * (the "License"); you may not use this file except in compliance with
    * the License.  You may obtain a copy of the License at
    *
    *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package org.apache.commons.validator.routines;
  
  import java.io.Serializable;
  
  import org.apache.commons.validator.GenericValidator;
  import org.apache.commons.validator.routines.checkdigit.CheckDigit;
  
  /**
   * Generic <b>Code Validation</b> providing format, minimum/maximum
   * length and {@link CheckDigit} validations.
   * <p>
   * Performs the following validations on a code:
   * <ul>
   *   <li>if the code is null, return null/false as appropriate</li>
   *   <li>trim the input. If the resulting code is empty, return null/false as appropriate</li>
   *   <li>Check the <i>format</i> of the code using a <i>regular expression.</i> (if specified)</li>
   *   <li>Check the <i>minimum</i> and <i>maximum</i> length  (if specified) of the <i>parsed</i> code
   *      (i.e. parsed by the <i>regular expression</i>).</li>
   *   <li>Performs {@link CheckDigit} validation on the parsed code (if specified).</li>
   *   <li>The {@link #validate(String)} method returns the trimmed, parsed input (or null if validation failed)</li>
   * </ul>
   * <p>
   * <b>Note</b>
   * The {@link #isValid(String)} method will return true if the input passes validation.
   * Since this includes trimming as well as potentially dropping parts of the input,
   * it is possible for a String to pass validation
   * but fail the checkdigit test if passed directly to it (the check digit routines generally don't trim input
   * nor do they generally check the format/length).
   * To be sure that you are passing valid input to a method use {@link #validate(String)} as follows:
   * <pre>
   * Object valid = validator.validate(input);
   * if (valid != null) {
   *    some_method(valid.toString());
   * }
   * </pre>
   * <p>
   * Configure the validator with the appropriate regular expression, minimum/maximum length
   * and {@link CheckDigit} validator and then call one of the two validation
   * methods provided:</p>
   *    <ul>
   *       <li><code>boolean isValid(code)</code></li>
   *       <li><code>String validate(code)</code></li>
   *    </ul>
   * <p>
   * Codes often include <i>format</i> characters - such as hyphens - to make them
   * more easily human readable. These can be removed prior to length and check digit
   * validation by  specifying them as a <i>non-capturing</i> group in the regular
   * expression (i.e. use the <code>(?:   )</code> notation).
   * <br>
   * Or just avoid using parentheses except for the parts you want to capture
   *
   * @since 1.4
   */
  public final class CodeValidator implements Serializable {
  
      private static final long serialVersionUID = 446960910870938233L;
  
      /** The format regular expression validator. */
      private final RegexValidator regexValidator;
  
      /** The minimum length of the code. */
      private final int minLength;
  
      /** The maximum length of the code. */
      private final int maxLength;
  
      /** The check digit validation routine. */
      private final CheckDigit checkdigit;
  
      /**
       * Constructs a code validator with a specified regular expression,
       * validator and {@link CheckDigit} validation.
       *
       * @param regexValidator The format regular expression validator
       * @param checkdigit The check digit validation routine.
       */
      public CodeValidator(final RegexValidator regexValidator, final CheckDigit checkdigit) {
          this(regexValidator, -1, -1, checkdigit);
      }
  
      /**
       * Constructs a code validator with a specified regular expression,
       * validator, length and {@link CheckDigit} validation.
      *
      * @param regexValidator The format regular expression validator
      * @param length The length of the code
      *  (sets the mimimum/maximum to the same value)
      * @param checkdigit The check digit validation routine
      */
     public CodeValidator(final RegexValidator regexValidator, final int length, final CheckDigit checkdigit) {
         this(regexValidator, length, length, checkdigit);
     }
 
     /**
      * Constructs a code validator with a specified regular expression
      * validator, minimum/maximum length and {@link CheckDigit} validation.
      *
      * @param regexValidator The format regular expression validator
      * @param minLength The minimum length of the code
      * @param maxLength The maximum length of the code
      * @param checkdigit The check digit validation routine
      */
     public CodeValidator(final RegexValidator regexValidator, final int minLength, final int maxLength,
             final CheckDigit checkdigit) {
         this.regexValidator = regexValidator;
         this.minLength = minLength;
         this.maxLength = maxLength;
         this.checkdigit = checkdigit;
     }
 
     /**
      * Constructs a code validator with a specified regular
      * expression and {@link CheckDigit}.
      * The RegexValidator validator is created to be case-sensitive
      *
      * @param regex The format regular expression
      * @param checkdigit The check digit validation routine
      */
     public CodeValidator(final String regex, final CheckDigit checkdigit) {
         this(regex, -1, -1, checkdigit);
     }
 
     /**
      * Constructs a code validator with a specified regular
      * expression, length and {@link CheckDigit}.
      * The RegexValidator validator is created to be case-sensitive
      *
      * @param regex The format regular expression.
      * @param length The length of the code
      *  (sets the mimimum/maximum to the same)
      * @param checkdigit The check digit validation routine
      */
     public CodeValidator(final String regex, final int length, final CheckDigit checkdigit) {
         this(regex, length, length, checkdigit);
     }
 
     /**
      * Constructs a code validator with a specified regular
      * expression, minimum/maximum length and {@link CheckDigit} validation.
      * The RegexValidator validator is created to be case-sensitive
      *
      * @param regex The regular expression
      * @param minLength The minimum length of the code
      * @param maxLength The maximum length of the code
      * @param checkdigit The check digit validation routine
      */
     public CodeValidator(final String regex, final int minLength, final int maxLength,
             final CheckDigit checkdigit) {
         if (!GenericValidator.isBlankOrNull(regex)) {
             this.regexValidator = new RegexValidator(regex);
         } else {
             this.regexValidator = null;
         }
         this.minLength = minLength;
         this.maxLength = maxLength;
         this.checkdigit = checkdigit;
     }
 
     /**
      * Gets the check digit validation routine.
      * <p>
      * <b>N.B.</b> Optional, if not set no Check Digit
      * validation will be performed on the code.
      *
      * @return The check digit validation routine
      */
     public CheckDigit getCheckDigit() {
         return checkdigit;
     }
 
     /**
      * Gets the maximum length of the code.
      * <p>
      * <b>N.B.</b> Optional, if less than zero the
      * maximum length will not be checked.
      *
      * @return The maximum length of the code or
      * <code>-1</code> if the code has no maximum length
      */
     public int getMaxLength() {
         return maxLength;
     }
 
     /**
      * Gets the minimum length of the code.
      * <p>
      * <b>N.B.</b> Optional, if less than zero the
      * minimum length will not be checked.
      *
      * @return The minimum length of the code or
      * <code>-1</code> if the code has no minimum length
      */
     public int getMinLength() {
         return minLength;
     }
 
     /**
      * Gets the <i>regular expression</i> validator.
      * <p>
      * <b>N.B.</b> Optional, if not set no regular
      * expression validation will be performed on the code.
      *
      * @return The regular expression validator
      */
     public RegexValidator getRegexValidator() {
         return regexValidator;
     }
 
     /**
      * Validate the code returning either {@code true}
      * or {@code false}.
      * <p>
      * This calls {@link #validate(String)} and returns false
      * if the return value is null, true otherwise.
      * <p>
      * Note that {@link #validate(String)} trims the input
      * and if there is a {@link RegexValidator} it may also
      * change the input as part of the validation.
      *
      * @param input The code to validate
      * @return {@code true} if valid, otherwise
      * {@code false}
      */
     public boolean isValid(final String input) {
         return validate(input) != null;
     }
 
     /**
      * Validate the code returning either the valid code or
      * {@code null} if invalid.
      * <p>
      * Note that this method trims the input
      * and if there is a {@link RegexValidator} it may also
      * change the input as part of the validation.
      *
      * @param input The code to validate
      * @return The code if valid, otherwise {@code null}
      * if invalid
      */
     public Object validate(final String input) {
         if (input == null) {
             return null;
         }
         String code = input.trim();
         if (code.isEmpty()) {
             return null;
         }
         // validate/reformat using regular expression
         if (regexValidator != null) {
             code = regexValidator.validate(code);
             if (code == null) {
                 return null;
             }
         }
         // check the length (must be done after validate as that can change the code)
         if (minLength >= 0 && code.length() < minLength ||
             maxLength >= 0 && code.length() > maxLength) {
             return null;
         }
         // validate the check digit
         if (checkdigit != null && !checkdigit.isValid(code)) {
             return null;
         }
         return code;
     }
 
 }