View Javadoc

1   /*
2    * $Id: AbstractFormatValidator.java 386637 2006-03-17 13:22:26Z niallp $
3    * $Revision: 386637 $
4    * $Date: 2006-03-17 13:22:26 +0000 (Fri, 17 Mar 2006) $
5    *
6    * ====================================================================
7    * Copyright 2006 The Apache Software Foundation
8    *
9    * Licensed under the Apache License, Version 2.0 (the "License");
10   * you may not use this file except in compliance with the License.
11   * You may obtain a copy of the License at
12   *
13   *     http://www.apache.org/licenses/LICENSE-2.0
14   *
15   * Unless required by applicable law or agreed to in writing, software
16   * distributed under the License is distributed on an "AS IS" BASIS,
17   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18   * See the License for the specific language governing permissions and
19   * limitations under the License.
20   */
21  package org.apache.commons.validator.routines;
22  
23  import java.text.Format;
24  import java.text.ParsePosition;
25  import java.util.Locale;
26  import java.io.Serializable;
27  
28  /***
29   * <p>Abstract class for <i>Format</i> based Validation.</p>
30   *
31   * <p>This is a <i>base</i> class for building Date and Number
32   *    Validators using format parsing.</p>
33   * 
34   * @version $Revision: 386637 $ $Date: 2006-03-17 13:22:26 +0000 (Fri, 17 Mar 2006) $
35   * @since Validator 1.3.0
36   */
37  public abstract class AbstractFormatValidator implements Serializable {
38  
39      private boolean strict = true;
40  
41      /***
42       * Construct an instance with the specified strict setting.
43       * 
44       * @param strict <code>true</code> if strict 
45       *        <code>Format</code> parsing should be used.
46       */
47      public AbstractFormatValidator(boolean strict) {
48          this.strict = strict;
49      }
50  
51      /***
52       * <p>Indicates whether validated values should adhere
53       *    strictly to the <code>Format</code> used.</p>
54       * 
55       * <p>Typically implementations of <code>Format</code>
56       *    ignore invalid characters at the end of the value
57       *    and just stop parsing. For example parsing a date
58       *    value of <code>01/01/20x0</code> using a pattern
59       *    of <code>dd/MM/yyyy</code> will result in a year
60       *    of <code>20</code> if <code>strict</code> is set
61       *    to <code>false</code>, whereas setting <code>strict</code>
62       *    to <code>true</code> will cause this value to fail
63       *    validation.</p>
64       * 
65       * @return <code>true</code> if strict <code>Format</code>
66       *         parsing should be used.
67       */
68      public boolean isStrict() {
69          return strict;
70      }
71  
72      /***
73       * <p>Validate using the default <code>Locale</code>. 
74       * 
75       * @param value The value validation is being performed on.
76       * @return <code>true</code> if the value is valid.
77       */
78      public boolean isValid(String value) {
79          return isValid(value, (String)null, (Locale)null);
80      }
81  
82      /***
83       * <p>Validate using the specified <i>pattern</i>. 
84       * 
85       * @param value The value validation is being performed on.
86       * @param pattern The pattern used to validate the value against.
87       * @return <code>true</code> if the value is valid.
88       */
89      public boolean isValid(String value, String pattern) {
90          return isValid(value, pattern, (Locale)null);
91      }
92  
93      /***
94       * <p>Validate using the specified <code>Locale</code>. 
95       * 
96       * @param value The value validation is being performed on.
97       * @param locale The locale to use for the Format, defaults to the default
98       * @return <code>true</code> if the value is valid.
99       */
100     public boolean isValid(String value, Locale locale) {
101         return isValid(value, (String)null, locale);
102     }
103 
104     /***
105      * <p>Validate using the specified pattern and/or <code>Locale</code>. 
106      * 
107      * @param value The value validation is being performed on.
108      * @param pattern The pattern used to format the value.
109      * @param locale The locale to use for the Format, defaults to the default
110      * @return <code>true</code> if the value is valid.
111      */
112     public abstract boolean isValid(String value, String pattern, Locale locale);
113 
114     /***
115      * <p>Format an object into a <code>String</code> using
116      * the default Locale.</p>
117      *
118      * @param value The value validation is being performed on.
119      * @return The value formatted as a <code>String</code>.
120      */
121     public String format(Object value) {
122         return format(value, (String)null, (Locale)null);
123     }
124 
125     /***
126      * <p>Format an object into a <code>String</code> using
127      * the specified pattern.</p>
128      *
129      * @param value The value validation is being performed on.
130      * @param pattern The pattern used to format the value.
131      * @return The value formatted as a <code>String</code>.
132      */
133     public String format(Object value, String pattern) {
134         return format(value, pattern, (Locale)null);
135     }
136 
137     /***
138      * <p>Format an object into a <code>String</code> using
139      * the specified Locale.</p>
140      *
141      * @param value The value validation is being performed on.
142      * @param locale The locale to use for the Format.
143      * @return The value formatted as a <code>String</code>.
144      */
145     public String format(Object value, Locale locale) {
146         return format(value, (String)null, locale);
147     }
148 
149     /***
150      * <p>Format an object using the specified pattern and/or 
151      *    <code>Locale</code>. 
152      *
153      * @param value The value validation is being performed on.
154      * @param pattern The pattern used to format the value.
155      * @param locale The locale to use for the Format.
156      * @return The value formatted as a <code>String</code>.
157      */
158     public String format(Object value, String pattern, Locale locale) {
159         Format formatter = getFormat(pattern, locale);
160         return format(value, formatter);
161     }
162 
163     /***
164      * <p>Format a value with the specified <code>Format</code>.</p>
165      * 
166      * @param value The value to be formatted.
167      * @param formatter The Format to use.
168      * @return The formatted value.
169      */
170     protected String format(Object value, Format formatter) {
171         return formatter.format(value);
172     }
173 
174     /***
175      * <p>Parse the value with the specified <code>Format</code>.</p>
176      * 
177      * @param value The value to be parsed.
178      * @param formatter The Format to parse the value with.
179      * @return The parsed value if valid or <code>null</code> if invalid.
180      */
181     protected Object parse(String value, Format formatter) {
182 
183         ParsePosition pos = new ParsePosition(0);
184         Object parsedValue = formatter.parseObject(value, pos);
185         if (pos.getErrorIndex() > -1) {
186             return null;
187         }
188 
189         if (isStrict() && pos.getIndex() < value.length()) {
190             return null;
191         }
192 
193         if (parsedValue != null) {
194             parsedValue = processParsedValue(parsedValue, formatter);
195         }
196 
197         return parsedValue;
198 
199     }
200 
201     /***
202      * <p>Process the parsed value, performing any further validation 
203      *    and type conversion required.</p>
204      * 
205      * @param value The parsed object created.
206      * @param formatter The Format used to parse the value with.
207      * @return The parsed value converted to the appropriate type
208      *         if valid or <code>null</code> if invalid.
209      */
210     protected abstract Object processParsedValue(Object value, Format formatter);
211 
212     /***
213      * <p>Returns a <code>Format</code> for the specified <i>pattern</i>
214      *    and/or <code>Locale</code>.</p>
215      * 
216      * @param pattern The pattern used to validate the value against or
217      *        <code>null</code> to use the default for the <code>Locale</code>.
218      * @param locale The locale to use for the currency format, system default if null.
219      * @return The <code>NumberFormat</code> to created.
220      */
221     protected abstract Format getFormat(String pattern, Locale locale);
222 
223 }