Skip to content

Commit 2e9586d

Browse files
author
John Keyes
committed
- updates for Url, File, Number, Date, and Enum
git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/cli/trunk@191208 13f79535-47bb-0310-9956-ffa450edef68
1 parent 4336902 commit 2e9586d

1 file changed

Lines changed: 130 additions & 1 deletion

File tree

‎xdocs/manual/validators.xml‎

Lines changed: 130 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@
4444

4545
<subsection name="ClassValidator">
4646
<p>
47-
The <code>ClassValidator</code> can validate a value using three criteria:
47+
The <code>ClassValidator</code> validates a value using three criteria:
4848
</p>
4949
<ol>
5050
<li>the value adheres to the Java Language Specification rules</li>
@@ -57,16 +57,145 @@ ClassValidator validator = new ClassValidator();
5757
validator.setLoadable(true);
5858
// 3.
5959
validator.setLoadable(true);</source>
60+
<p>
61+
TODO: add section about values being replaced with class instances
62+
</p>
6063
</subsection>
64+
6165
<subsection name="DateValidator">
66+
<p>
67+
The <code>DateValidator</code> validates values against a
68+
<code>java.text.DateFormat</code>. There are three helper methods
69+
that create built-in validators.
70+
</p>
71+
<ol>
72+
<li><code>getDateInstance</code> returns a validator for the default
73+
date format for the default locale.
74+
</li>
75+
<li><code>getTimeInstance</code> returns a validator for the default
76+
time format for the default locale.
77+
</li>
78+
<li><code>getDateTimeInstance</code> returns a validator for the default
79+
date and time format for the default locale.
80+
</li>
81+
</ol>
82+
<p>
83+
A <code>DateValidator</code> can also be created by passing your
84+
a custom <code>DateFormat</code> into the constructor.
85+
</p>
86+
<source>DateFormat myFormat = DateFormat.getDateInstance( DateFormat.LONG, Locale.UK );
87+
DateValidator myValidator = new DateValidator( myFormat );</source>
88+
<p>
89+
In addition to basic format checking you can also check if the date/time specified
90+
is before/after a specific date/time. The lower bound is set using the
91+
<code>setMinimum( java.util.Date )</code>, and the upper bound is set using
92+
the <code>setMaximum( java.util.Date )</code>.
93+
</p>
94+
<p>
95+
TODO: add section about values being replaced with date instances
96+
</p>
6297
</subsection>
98+
6399
<subsection name="EnumValidator">
100+
<p>
101+
The <code>EnumValidator</code> validates values against a list of
102+
allowed string values. The values that are allowed are specified in
103+
a <code>java.util.Set</code> and passed in to the constructor.
104+
</p>
105+
<source>Set enumSet = new TreeSet();
106+
enumSet.add("red");
107+
enumSet.add("green");
108+
enumSet.add("blue");
109+
110+
EnumValidator validator = new EnumValidator( enumSet );</source>
64111
</subsection>
112+
65113
<subsection name="FileValidator">
114+
<p>
115+
The <code>FileValidator</code> validates that values represent
116+
existing files. You can also specify a combination of the
117+
following additional criteria:
118+
</p>
119+
<ol>
120+
<li>value is a file</li>
121+
<li>value is a directory</li>
122+
<li>the file is writable</li>
123+
<li>the file is readable</li>
124+
<li>the file is hidden</li>
125+
</ol>
126+
<p>
127+
Each of the criteria listed here are specified using the appropriate
128+
setter.
129+
</p>
130+
<p>
131+
There are three helper methods to create validators:
132+
</p>
133+
<ol>
134+
<li><code>getExistingInstance</code> returns a validator that ensures
135+
a value represents an existing file.
136+
</li>
137+
<li><code>getExistingFileInstance</code> returns a validator that ensures
138+
a value represents an existing file that is not a directory.
139+
</li>
140+
<li><code>getExistingDirectoryInstance</code> returns a validator that ensures
141+
a value represents an existing file this is a directory.
142+
</li>
143+
</ol>
144+
<source>// validate that the value represents a file that exists
145+
FileValidator validator = FileValidator.getExistingInstance();
146+
147+
// ensure it's not a hidden file
148+
validator.setHidden( false );
149+
150+
// ensure it's a writable file
151+
validator.setWritable( true );</source>
152+
66153
</subsection>
154+
67155
<subsection name="NumberValidator">
156+
<p>
157+
The <code>NumberValidator</code> validates that values adhere to
158+
certain rules like the following:
159+
</p>
160+
<ol>
161+
<li><code>getCurrencyInstance</code> returns a validator for the default
162+
currency format for the default locale.
163+
</li>
164+
<li><code>getPercentInstance</code> returns a validator for the default
165+
percent format for the default locale.
166+
</li>
167+
<li><code>getIntegerInstance</code> returns a validator for the default
168+
integer format for the default locale.
169+
</li>
170+
<li><code>getNumberInstance</code> returns a validator for the default
171+
number format for the default locale.
172+
</li>
173+
</ol>
174+
<p>
175+
A <code>NumberValidator</code> can also be created by passing your
176+
a custom <code>NumberFormat</code> into the constructor.
177+
</p>
178+
<source>NumberFormat myFormat = NumberFormat.getCurrencyInstance( Locale.UK );
179+
NumberValidator myValidator = new NumberValidator( myFormat );</source>
180+
<p>
181+
In addition to basic format checking you can also check if the number specified
182+
is less than or greater than a specific number. The lower bound is set using
183+
the <code>setMinimum( Number )</code>, and the upper bound is set using
184+
the <code>setMaximum( Number )</code>.
185+
</p>
68186
</subsection>
187+
69188
<subsection name="UrlValidator">
189+
<p>
190+
A <code>UrlValidator</code> validates that values are URLs and if you
191+
choose it will also validate the protocol is of the type you have
192+
specified.
193+
</p>
194+
<source>UrlValidator validator = new UrlValidator();
195+
196+
// only accept https URLs
197+
validator.setProtocol("https");</source>
198+
70199
</subsection>
71200

72201
</section>

0 commit comments

Comments
 (0)