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>Byte Validation</b> and Conversion routines (<code>java.lang.Byte</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>Byte</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>Byte</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 the default format for the default <code>Locale</code></li>
057     *       <li>using a specified pattern with the default <code>Locale</code></li>
058     *       <li>using the default format for a specified <code>Locale</code></li>
059     *       <li>using a specified pattern with a specified <code>Locale</code></li>
060     *    </ul>
061     *
062     * @version $Revision: 493905 $ $Date: 2007-01-08 03:11:38 +0100 (Mo, 08. Jan 2007) $
063     * @since Validator 1.3.0
064     */
065    public class ByteValidator extends AbstractNumberValidator {
066    
067        private static final ByteValidator VALIDATOR = new ByteValidator();
068    
069        /**
070         * Return a singleton instance of this validator.
071         * @return A singleton instance of the ByteValidator.
072         */
073        public static ByteValidator getInstance() {
074            return VALIDATOR;
075        }
076    
077        /**
078         * Construct a <i>strict</i> instance.
079         */
080        public ByteValidator() {
081            this(true, STANDARD_FORMAT);
082        }
083    
084        /**
085         * <p>Construct an instance with the specified strict setting
086         *    and format type.</p>
087         *    
088         * <p>The <code>formatType</code> specified what type of
089         *    <code>NumberFormat</code> is created - valid types
090         *    are:</p>
091         *    <ul>
092         *       <li>AbstractNumberValidator.STANDARD_FORMAT -to create
093         *           <i>standard</i> number formats (the default).</li>
094         *       <li>AbstractNumberValidator.CURRENCY_FORMAT -to create
095         *           <i>currency</i> number formats.</li>
096         *       <li>AbstractNumberValidator.PERCENT_FORMAT -to create
097         *           <i>percent</i> number formats (the default).</li>
098         *    </ul>
099         * 
100         * @param strict <code>true</code> if strict 
101         *        <code>Format</code> parsing should be used.
102         * @param formatType The <code>NumberFormat</code> type to
103         *        create for validation, default is STANDARD_FORMAT.
104         */
105        public ByteValidator(boolean strict, int formatType) {
106            super(strict, formatType, false);
107        }
108    
109        /**
110         * <p>Validate/convert a <code>Byte</code> using the default
111         *    <code>Locale</code>. 
112         *
113         * @param value The value validation is being performed on.
114         * @return The parsed <code>Byte</code> if valid or <code>null</code>
115         *  if invalid.
116         */
117        public Byte validate(String value) {
118            return (Byte)parse(value, (String)null, (Locale)null);
119        }
120    
121        /**
122         * <p>Validate/convert a <code>Byte</code> using the
123         *    specified <i>pattern</i>. 
124         *
125         * @param value The value validation is being performed on.
126         * @param pattern The pattern used to validate the value against.
127         * @return The parsed <code>Byte</code> if valid or <code>null</code> if invalid.
128         */
129        public Byte validate(String value, String pattern) {
130            return (Byte)parse(value, pattern, (Locale)null);
131        }
132    
133        /**
134         * <p>Validate/convert a <code>Byte</code> using the
135         *    specified <code>Locale</code>. 
136         *
137         * @param value The value validation is being performed on.
138         * @param locale The locale to use for the number format, system default if null.
139         * @return The parsed <code>Byte</code> if valid or <code>null</code> if invalid.
140         */
141        public Byte validate(String value, Locale locale) {
142            return (Byte)parse(value, (String)null, locale);
143        }
144    
145        /**
146         * <p>Validate/convert a <code>Byte</code> using the
147         *    specified pattern and/ or <code>Locale</code>. 
148         *
149         * @param value The value validation is being performed on.
150         * @param pattern The pattern used to validate the value against, or the
151         *        default for the <code>Locale</code> if <code>null</code>.
152         * @param locale The locale to use for the date format, system default if null.
153         * @return The parsed <code>Byte</code> if valid or <code>null</code> if invalid.
154         */
155        public Byte validate(String value, String pattern, Locale locale) {
156            return (Byte)parse(value, pattern, locale);
157        }
158    
159        /**
160         * Check if the value is within a specified range.
161         * 
162         * @param value The <code>Number</code> value to check.
163         * @param min The minimum value of the range.
164         * @param max The maximum value of the range.
165         * @return <code>true</code> if the value is within the
166         *         specified range.
167         */
168        public boolean isInRange(byte value, byte min, byte max) {
169            return (value >= min && value <= max);
170        }
171    
172        /**
173         * Check if the value is within a specified range.
174         * 
175         * @param value The <code>Number</code> value to check.
176         * @param min The minimum value of the range.
177         * @param max The maximum value of the range.
178         * @return <code>true</code> if the value is within the
179         *         specified range.
180         */
181        public boolean isInRange(Byte value, byte min, byte max) {
182            return isInRange(value.byteValue(), min, max);
183        }
184    
185        /**
186         * Check if the value is greater than or equal to a minimum.
187         * 
188         * @param value The value validation is being performed on.
189         * @param min The minimum value.
190         * @return <code>true</code> if the value is greater than
191         *         or equal to the minimum.
192         */
193        public boolean minValue(byte value, byte min) {
194            return (value >= min);
195        }
196    
197        /**
198         * Check if the value is greater than or equal to a minimum.
199         * 
200         * @param value The value validation is being performed on.
201         * @param min The minimum value.
202         * @return <code>true</code> if the value is greater than
203         *         or equal to the minimum.
204         */
205        public boolean minValue(Byte value, byte min) {
206            return minValue(value.byteValue(), min);
207        }
208    
209        /**
210         * Check if the value is less than or equal to a maximum.
211         * 
212         * @param value The value validation is being performed on.
213         * @param max The maximum value.
214         * @return <code>true</code> if the value is less than
215         *         or equal to the maximum.
216         */
217        public boolean maxValue(byte value, byte max) {
218            return (value <= max);
219        }
220    
221        /**
222         * Check if the value is less than or equal to a maximum.
223         * 
224         * @param value The value validation is being performed on.
225         * @param max The maximum value.
226         * @return <code>true</code> if the value is less than
227         *         or equal to the maximum.
228         */
229        public boolean maxValue(Byte value, byte max) {
230            return maxValue(value.byteValue(), max);
231        }
232    
233        /**
234         * <p>Perform further validation and convert the <code>Number</code> to
235         * a <code>Byte</code>.</p>
236         * 
237         * @param value The parsed <code>Number</code> object created.
238         * @param formatter The Format used to parse the value with.
239         * @return The parsed <code>Number</code> converted to a 
240         *   <code>Byte</code> if valid or <code>null</code> if invalid.
241         */
242        protected Object processParsedValue(Object value, Format formatter) {
243    
244            long longValue = ((Number)value).longValue();
245    
246            if (longValue < Byte.MIN_VALUE || 
247                longValue > Byte.MAX_VALUE) {
248                return null;
249            } else {
250                return new Byte((byte)longValue);
251            }
252        }
253    
254    }