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