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     */
017    package org.apache.commons.validator.routines;
018    
019    import java.math.BigInteger;
020    import java.text.Format;
021    import java.util.Locale;
022    
023    /**
024     * <p><b>BigInteger Validation</b> and Conversion routines (<code>java.math.BigInteger</code>).</p>
025     *
026     * <p>This validator provides a number of methods for
027     *    validating/converting a <code>String</code> value to
028     *    a <code>BigInteger</code> using <code>java.text.NumberFormat</code>
029     *    to parse either:</p>
030     *    <ul>
031     *       <li>using the default format for the default <code>Locale</code></li>
032     *       <li>using a specified pattern with the default <code>Locale</code></li>
033     *       <li>using the default format for a specified <code>Locale</code></li>
034     *       <li>using a specified pattern with a specified <code>Locale</code></li>
035     *    </ul>
036     *    
037     * <p>Use one of the <code>isValid()</code> methods to just validate or
038     *    one of the <code>validate()</code> methods to validate and receive a
039     *    <i>converted</i> <code>BigInteger</code> value.</p>
040     * 
041     * <p>Once a value has been sucessfully converted the following
042     *    methods can be used to perform minimum, maximum and range checks:</p>
043     *    <ul>
044     *       <li><code>minValue()</code> checks whether the value is greater
045     *           than or equal to a specified minimum.</li>
046     *       <li><code>maxValue()</code> checks whether the value is less
047     *           than or equal to a specified maximum.</li>
048     *       <li><code>isInRange()</code> checks whether the value is within
049     *           a specified range of values.</li>
050     *    </ul>
051     * 
052     * <p>So that the same mechanism used for parsing an <i>input</i> value 
053     *    for validation can be used to format <i>output</i>, corresponding
054     *    <code>format()</code> methods are also provided. That is you can 
055     *    format either:</p>
056     *    <ul>
057     *       <li>using the default format for the default <code>Locale</code></li>
058     *       <li>using a specified pattern with the default <code>Locale</code></li>
059     *       <li>using the default format for a specified <code>Locale</code></li>
060     *       <li>using a specified pattern with a specified <code>Locale</code></li>
061     *    </ul>
062     *
063     * @version $Revision: 493905 $ $Date: 2007-01-08 03:11:38 +0100 (Mo, 08. Jan 2007) $
064     * @since Validator 1.3.0
065     */
066    public class BigIntegerValidator extends AbstractNumberValidator {
067    
068        private static final BigIntegerValidator VALIDATOR = new BigIntegerValidator();
069    
070        /**
071         * Return a singleton instance of this validator.
072         * @return A singleton instance of the BigIntegerValidator.
073         */
074        public static BigIntegerValidator getInstance() {
075            return VALIDATOR;
076        }
077    
078        /**
079         * Construct a <i>strict</i> instance.
080         */
081        public BigIntegerValidator() {
082            this(true, STANDARD_FORMAT);
083        }
084    
085        /**
086         * <p>Construct an instance with the specified strict setting
087         *    and format type.</p>
088         *    
089         * <p>The <code>formatType</code> specified what type of
090         *    <code>NumberFormat</code> is created - valid types
091         *    are:</p>
092         *    <ul>
093         *       <li>AbstractNumberValidator.STANDARD_FORMAT -to create
094         *           <i>standard</i> number formats (the default).</li>
095         *       <li>AbstractNumberValidator.CURRENCY_FORMAT -to create
096         *           <i>currency</i> number formats.</li>
097         *       <li>AbstractNumberValidator.PERCENT_FORMAT -to create
098         *           <i>percent</i> number formats (the default).</li>
099         *    </ul>
100         * 
101         * @param strict <code>true</code> if strict 
102         *        <code>Format</code> parsing should be used.
103         * @param formatType The <code>NumberFormat</code> type to
104         *        create for validation, default is STANDARD_FORMAT.
105         */
106        public BigIntegerValidator(boolean strict, int formatType) {
107            super(strict, formatType, false);
108        }
109    
110        /**
111         * <p>Validate/convert a <code>BigInteger</code> using the default
112         *    <code>Locale</code>. 
113         *
114         * @param value The value validation is being performed on.
115         * @return The parsed <code>BigInteger</code> if valid or <code>null</code>
116         *  if invalid.
117         */
118        public BigInteger validate(String value) {
119            return (BigInteger)parse(value, (String)null, (Locale)null);
120        }
121    
122        /**
123         * <p>Validate/convert a <code>BigInteger</code> using the
124         *    specified <i>pattern</i>. 
125         *
126         * @param value The value validation is being performed on.
127         * @param pattern The pattern used to validate the value against.
128         * @return The parsed <code>BigInteger</code> if valid or <code>null</code> if invalid.
129         */
130        public BigInteger validate(String value, String pattern) {
131            return (BigInteger)parse(value, pattern, (Locale)null);
132        }
133    
134        /**
135         * <p>Validate/convert a <code>BigInteger</code> using the
136         *    specified <code>Locale</code>. 
137         *
138         * @param value The value validation is being performed on.
139         * @param locale The locale to use for the number format, system default if null.
140         * @return The parsed <code>BigInteger</code> if valid or <code>null</code> if invalid.
141         */
142        public BigInteger validate(String value, Locale locale) {
143            return (BigInteger)parse(value, (String)null, locale);
144        }
145    
146        /**
147         * <p>Validate/convert a <code>BigInteger</code> using the
148         *    specified pattern and/ or <code>Locale</code>. 
149         *
150         * @param value The value validation is being performed on.
151         * @param pattern The pattern used to validate the value against, or the
152         *        default for the <code>Locale</code> if <code>null</code>.
153         * @param locale The locale to use for the date format, system default if null.
154         * @return The parsed <code>BigInteger</code> if valid or <code>null</code> if invalid.
155         */
156        public BigInteger validate(String value, String pattern, Locale locale) {
157            return (BigInteger)parse(value, pattern, locale);
158        }
159    
160        /**
161         * Check if the value is within a specified range.
162         * 
163         * @param value The <code>Number</code> value to check.
164         * @param min The minimum value of the range.
165         * @param max The maximum value of the range.
166         * @return <code>true</code> if the value is within the
167         *         specified range.
168         */
169        public boolean isInRange(BigInteger value, long min, long max) {
170            return (value.longValue() >= min && value.longValue() <= max);
171        }
172    
173        /**
174         * Check if the value is greater than or equal to a minimum.
175         * 
176         * @param value The value validation is being performed on.
177         * @param min The minimum value.
178         * @return <code>true</code> if the value is greater than
179         *         or equal to the minimum.
180         */
181        public boolean minValue(BigInteger value, long min) {
182            return (value.longValue() >= min);
183        }
184    
185        /**
186         * Check if the value is less than or equal to a maximum.
187         * 
188         * @param value The value validation is being performed on.
189         * @param max The maximum value.
190         * @return <code>true</code> if the value is less than
191         *         or equal to the maximum.
192         */
193        public boolean maxValue(BigInteger value, long max) {
194            return (value.longValue() <= max);
195        }
196    
197        /**
198         * Convert the parsed value to a <code>BigInteger</code>.
199         * 
200         * @param value The parsed <code>Number</code> object created.
201         * @param formatter The Format used to parse the value with.
202         * @return The parsed <code>Number</code> converted to a 
203         *         <code>BigInteger</code>.
204         */
205        protected Object processParsedValue(Object value, Format formatter) {
206            return BigInteger.valueOf(((Number)value).longValue());
207        }
208    }