Not used for Avalon CLI git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/cli/branches/avalon-implementation@529026 13f79535-47bb-0310-9956-ffa450edef68
Project: http://git-wip-us.apache.org/repos/asf/commons-cli/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-cli/commit/4dd97214 Tree: http://git-wip-us.apache.org/repos/asf/commons-cli/tree/4dd97214 Diff: http://git-wip-us.apache.org/repos/asf/commons-cli/diff/4dd97214 Branch: refs/heads/avalon-implementation Commit: 4dd97214009c207404e870ccd02eb7083096ff21 Parents: ce816db Author: Sebastian Bazley <[email protected]> Authored: Sun Apr 15 17:25:27 2007 +0000 Committer: Sebastian Bazley <[email protected]> Committed: Sun Apr 15 17:25:27 2007 +0000 ---------------------------------------------------------------------- xdocs/manual/builders.xml | 45 ----- xdocs/manual/commandlines.xml | 50 ----- xdocs/manual/index.xml | 192 ------------------- xdocs/manual/options.xml | 377 ------------------------------------- xdocs/manual/utilities.xml | 38 ---- xdocs/manual/validators.xml | 203 -------------------- 6 files changed, 905 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-cli/blob/4dd97214/xdocs/manual/builders.xml ---------------------------------------------------------------------- diff --git a/xdocs/manual/builders.xml b/xdocs/manual/builders.xml deleted file mode 100644 index 1adf0f9..0000000 --- a/xdocs/manual/builders.xml +++ /dev/null @@ -1,45 +0,0 @@ -<?xml version="1.0"?> -<!-- - Copyright 2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<document> - - <properties> - <author email="[email protected]">commons-dev</author> - <title>CLI2 - Builders</title> - </properties> - - <body> - <section name="Builders"> - <p>TODO describe builders and resaons for their use</p> - <subsection name="GroupBuilder"> - </subsection> - <subsection name="ArgumentBuilder"> - </subsection> - <subsection name="DefaultOptionBuilder"> - </subsection> - <subsection name="CommandBuilder"> - </subsection> - <subsection name="SwitchBuilder"> - </subsection> - <subsection name="PatternBuilder"> - </subsection> - <subsection name="Other Options"> - <p>TODO PropertyOption</p> - <p>TODO SourceDestArgument</p> - </subsection> - </section> - </body> -</document> http://git-wip-us.apache.org/repos/asf/commons-cli/blob/4dd97214/xdocs/manual/commandlines.xml ---------------------------------------------------------------------- diff --git a/xdocs/manual/commandlines.xml b/xdocs/manual/commandlines.xml deleted file mode 100644 index 5c53ed6..0000000 --- a/xdocs/manual/commandlines.xml +++ /dev/null @@ -1,50 +0,0 @@ -<?xml version="1.0"?> -<!-- - Copyright 2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<document> - - <properties> - <author email="[email protected]">commons-dev</author> - <title>CLI2 - CommandLines</title> - </properties> - - <body> - <section name="CommandLines"> - <img src="../images/commandlines.jpg"/> - <subsection name="Parser"> - </subsection> - <subsection name="CommandLine"> - </subsection> - <subsection name="WriteableCommandLine"> - </subsection> - <subsection name="DefaultingCommandLine"> - </subsection> - <subsection name="PropertiesCommandLine"> - </subsection> - <subsection name="Command"> - </subsection> - <subsection name="Switch"> - </subsection> - <subsection name="PropertyOption"> - </subsection> - <subsection name="SourceDestArgument"> - </subsection> - </section> - <section name="Future Work"> - <p>TODO commons-configuration</p> - </section> - </body> -</document> http://git-wip-us.apache.org/repos/asf/commons-cli/blob/4dd97214/xdocs/manual/index.xml ---------------------------------------------------------------------- diff --git a/xdocs/manual/index.xml b/xdocs/manual/index.xml deleted file mode 100644 index 9f42e49..0000000 --- a/xdocs/manual/index.xml +++ /dev/null @@ -1,192 +0,0 @@ -<?xml version="1.0"?> -<!-- - Copyright 2004-2005 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<document> - - <properties> - <author email="[email protected]">commons-dev</author> - <title>CLI2 - Overview</title> - </properties> - - <body> - <section name="Overview"> - <p> - CLI Breaks down command line processing into three distinct phases, the - first of which is to create a model of the command line you wish to process. The - second phase is arguably the most important as it involves processing the - command line arguments of the application according to the model created. - Finally the parsed command line is available to be queried by the - application proper. The phases are discussed in more detail below. - </p> - <subsection name="Modelling the interface"> - <p> - In CLI2 a command line is modelled as a Group composed of many Options. - There are a number different Option implementations available to be - used including DefaultOption, Switch and Command which may all have an - Argument and/or a Group of child options associated with them. An - example of where this parental relationship could be used is where you - need to allow for the following scenario where one option - only makes sense within the context of another: - </p> - <p><code>myapp --output path/to/file --xml</code></p> - <p> - Typically this command line would be modelled as a DefaultOption - (<code>--output</code>) with an Argument (to capture - <code>path/to/file</code>) and a Group of children consisting of a - DefaultOption (<code>--xml</code>) since the format only applies if the - output is specified - </p> - <p> - The various Option implementations provided need careful configuration - and constructors take a complex set of arguments. To ease the construction - of these options *Builder classes (e.g. DefaultOptionBuilder, GroupBuilder - and ArgumentBuilder) have been supplied following the - <a href="http://c2.com/cgi/wiki?BuilderPattern";>Builder Pattern</a> - which essentially involves using the DefaultOptionBuilder class to create - instances of DefaultOption using descriptive method calls instead of - anonymous arguments to a constructor. The following example demonstrates how - the command line shown above could be modelled in code: - </p> - <source> -DefaultOptionBuilder oBuilder = new DefaultOptionBuilder(); -ArgumentBuilder aBuilder = new ArgumentBuilder(); -GroupBuilder gBuilder = new GroupBuilder(); - -DefaultOption xmlOption = - oBuilder - .withLongName("xml") - .withDescription("Output using xml format") - .create(); - -Argument pathArgument = - aBuilder - .withName("path") - .withMinimum(1) - .withMaximum(1) - .create(); - -Group outputChildren = - gBuilder - .withOption(xmlOption) - .create(); - -Option outputOption = - oBuilder - .withLongName("output") - .withDescription("Outputs to a file") - .withArgument(pathArgument) - .withChildren(outputChildren) - .create(); - </source> - <p> - The <a href="options.html">Options</a> and - <a href="builders.html">Builders</a> sections of the manual discuss these - features in greater detail. - </p> - <p> - Once all the options have been composed into a Group modelling the complete - option model then we are ready to parse a command line. - </p> - </subsection> - <subsection name="Parsing the command line"> - <p> - The Parser class can be used to parse an array of arguments against the - option model into a CommandLine. The parsing is driven by the - <code>parse(String[])</code> method which delegates to the option model to do - the actual parsing, with each Option implementation providing its own parsing - logic. The <code>parseAndHelp(String[])</code> method attempts to simplify - the use of the former method by automatically handling any <code>--help</code> - options and displaying error messages where appropriate. - </p> - <p> - The HelpFormatter class is designed to allow the option model to be described - to the user in a manner typical of command line applications. The - HelpFormatter is designed with flexibility in mind so it should be possible to - control exactly which structures are described to the user and what level of - detail to use. The HelpFormatter is discussed in detail in the - <a href="utilities.html#HelpFormatter">Utilities</a> section of the manual. - </p> - <p> - Any errors that occur while parsing result in an OptionException being thrown - which attempt to provide a meaningful message describing the problem to the - user. Parser's <code>parseAndHelp(String[])</code> method catches any - OptionException and uses the HelpFormatter to display to the user: - </p> - <source> -// configure the options -Group options = ...; - -// configure a HelpFormatter -HelpFormatter hf = new HelpFormatter(); - -// configure a parser -Parser p = new Parser(); -p.setGroup(options); -p.setHelpFormatter(hf); -p.setHelpTrigger("--help"); -CommandLine cl = p.parseAndHelp(new String[]{}); - -// abort application if no CommandLine was parsed -if(cl==null) { - System.exit(-1); -} - </source> - - <p> - Assuming that OptionExceptions have been averted then the next step is to have - the application query the resulting CommandLine instance. - </p> - </subsection> - <subsection name="Querying the result"> - <p> - The CommandLine interface provides lots of ways to look up information either - by Option instance or by a String representing any of the forms valid on the - command line. For example if an option is configured with multiple names - (e.g. <code>-?</code>, <code>-h</code>, <code>--help</code>) then any of the - those strings can be used to look up the value irrespective of which form - appeared on the command line. - </p> - <p> - The <code>hasOption()</code> family of methods can be used to simply test for - the presence of options, while the <code>getValues()</code> family of methods - can be used to retrieve the values associated with Arguments. The status of - any Switch options can be detected through the use of <code>getSwitch()</code> - methods which will return a Boolean if set or null otherwise: - </p> - <source> -// if we have --output option -if(cl.hasOption("--output")) { - // grab the path - String path = (String)cl.getValue("--output"); - // grab the format - boolean xml = cl.hasOption("--xml"); - // configure the application's output - configureOutput(path,xml); -} - </source> - <p> - To enable complex CommandLine configurations alternative implementations are - provided that can wrap a Properties or Preferences instance as a CommandLine. - These can then be combined with the DefaultingCommandLine and the parsed - CommandLine to provide a variety of different defaulting and overriding - scenarios. The CommandLine interface and implementations are discussed - further in the <a href="commandlines.html">CommandLines</a> section of the - manual. - </p> - </subsection> - </section> - </body> -</document> http://git-wip-us.apache.org/repos/asf/commons-cli/blob/4dd97214/xdocs/manual/options.xml ---------------------------------------------------------------------- diff --git a/xdocs/manual/options.xml b/xdocs/manual/options.xml deleted file mode 100644 index 4fc10b2..0000000 --- a/xdocs/manual/options.xml +++ /dev/null @@ -1,377 +0,0 @@ -<?xml version="1.0"?> -<!-- - Copyright 2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<document> - - <properties> - <author email="[email protected]">commons-dev</author> - <title>CLI2 - Options</title> - </properties> - - <body> - <section name="Options"> - <img src="../images/options.jpg"/> - <subsection name="Option"> - <p> - In CLI2 every element of the command line interface is modelled as an - Option instance, and has the following readonly properties that are - inherited by all other Option implementations: - </p> - <table> - <tr> - <th>Property</th><th>Type</th><th>Description</th> - </tr> - <tr> - <td>id</td> - <td>int</td> - <td> - Some people find it useful to give each option a unique identifer - so that they can use the options within a java <code>switch</code> - statement. This value is entirely optional and it is up to the - user to ensure any uniqueness. - </td> - </tr> - <tr> - <td>preferredName</td> - <td>String</td> - <td> - Every option has a preferred name that can be used for the minimal - <code>toString()</code> implementation. Options can usually have - many additional names too. - </td> - </tr> - <tr> - <td>required</td> - <td>boolean</td> - <td> - True here indicates that the command line is invalid if this - option doesn't appear on it. - </td> - </tr> - </table> - </subsection> - - <subsection name="Group"> - <source>-a|-b|-c|-d|-e</source> - <p> - Groups are possible the least intuitive form of Option since they - actually represent a collection of other options. Most member Options - can appear on a command line in any order with the exception of - Arguments; they must appear in the given order as there is no other - way to identify one from another. An additional restriction of the - standard Group implementation is that only the final argument can have - variable size (differing minimum and maximum). - </p> - <p> - Groups inherit all the properties of Options. - </p> - <table> - <tr> - <th>Property</th><th>Type</th><th>Description</th> - </tr> - <tr> - <td>minimum</td> - <td>int</td> - <td> - The minimum number of member options that must be present on the - command line for this group to be valid. Typically this will - either be 0 where the group is optional or 1 to indicate at least - one of them is needed. This value does not count anonymous - options. - </td> - </tr> - <tr> - <td>maximum</td> - <td>int</td> - <td> - The maximum number of options from this Group that can appear in a - command line. This would typically be used if you wanted to - create an exclusive group where a maximum of 1 member is allowed - to appear. This value does not count anonymous options. - </td> - </tr> - </table> - </subsection> - - <subsection name="Argument"> - <source><arg1> [<arg2> ...]</source> - <p> - Arguments are used to pass in values from the command line, for - example to pass in a list of files to be operated on. Arguments can - appear in two different situations within an option model, the most - frequently used situation is where the value found should be associated - with a Parent option; in this situation the value is expected to - immediately follow the Parent in the command line. The second - scenario where Arguments are used is when they are added to a Group - directly rather than being composed with a Parent first. These - 'anonymous' arguments have nothing that identifies them on the - command line other than the order in which they appear. - </p> - <p> - Multiple values may be parsed by a single argument and the minimum - and maximum attributes can used to control their validity, - additionally a Validator may be used to identify whether individual - values are valid. In some situations it can be useful to parse the - supplied string into multiple values and so the initialSeparator and - subsequentSeparator attributes can be used; assuming an - initialSeparator of '=' and a subsequentSeparator of ',', the - string '--file=a,b,c' would be split into a parent option '--file', - and the values 'a', 'b' and 'c'. - </p> - <p> - Arguments inherit all the properties of Options. - </p> - <table> - <tr> - <th>Property</th><th>Type</th><th>Description</th> - </tr> - <tr> - <td>minimum</td> - <td>int</td> - <td> - The minimum number of values that must be present for the - Argument to be valid. The default of 0 implies that the argument - is optional. - </td> - </tr> - <tr> - <td>maximum</td> - <td>int</td> - <td> - The maximum number of values that can appear in a valid command - line. A value less than minimum is not allowed. - </td> - </tr> - <tr> - <td>consumeRemaining</td> - <td>String</td> - <td> - A string that can be used to avoid parsing of the remaining - values as options. Typically '--' is used and allows file names - to be used as values even though they look like options. - </td> - </tr> - <tr> - <td>initialSeparator</td> - <td>char</td> - <td> - A character used to indicate the end of the parent option and the - beginning of the values. - </td> - </tr> - <tr> - <td>subsequentSeparator</td> - <td>char</td> - <td> - A character used to indicate the boundry between two values in a - single string. - </td> - </tr> - <tr> - <td>defaultValue</td> - <td>Object</td> - <td> - A value to be used when no other is supplied. - </td> - </tr> - </table> - </subsection> - - <subsection name="Parent"> - <source>--parent <arg> --child1|--child2</source> - <p> - Parent options allow an argument to be tied to some othe option, - additionally a group of child options can also be added to the parent. - The argument and child options are only valid in the presence of the - parent option, must appear on the command line with the child options - following the argument. - </p> - <p> - Parents are not usable in themselves but DefaultOption, Switch and - Command all inherit the parent features. Parents inherit the - properties of Options. - </p> - <table> - <tr> - <th>Property</th><th>Type</th><th>Description</th> - </tr> - <tr> - <td>argument</td> - <td>Argument</td> - <td> - The Argument to delegate value processing to. This property is - optional. - </td> - </tr> - <tr> - <td>children</td> - <td>Group</td> - <td> - The Group to delegate child processing to. This property is - optional. - </td> - </tr> - </table> - </subsection> - - - - <subsection name="DefaultOption"> - <source>--file (-f)</source> - <p> - The default option allows an option to exist with both long and short - aliases. Ordinarily the short aliases would be a single character - long and allow a series of options <code>-x -v -f</code> to be - concatenated into a single element <code>-xvf</code> on the command - line. This bursting of concatenated options can be turned off if - necessary and the single character restriction can be ignored where - bursting is not required. - </p> - <p> - DefaultOptions inherit all the properties of Options and Parents. - </p> - <table> - <tr> - <th>Property</th><th>Type</th><th>Description</th> - </tr> - <tr> - <td>shortName</td> - <td>String</td> - <td> - The short name of the option. At least one short or long name is - required. - </td> - </tr> - <tr> - <td>longName</td> - <td>String</td> - <td> - The long name of the option. At least one short or long name is - required. - </td> - </tr> - <tr> - <td>burstEnabled</td> - <td>boolean</td> - <td> - Whether to allow this option to be concatenated with others. - </td> - </tr> - </table> - </subsection> - - - <subsection name="Command"> - <source>update (up,upd)</source> - <p> - Commands are basically an option without an identifying prefix and - are usually found in applications that implement a suite of tools - within a single application. Any of a number of aliases can appear - on the command line with idenentical meaning. - </p> - <p> - Commands inherit all the properties of Options and Parents. - </p> - </subsection> - - <subsection name="Switch"> - <source>+display|-display</source> - <p> - Switches allow the user to turn a feature on or off. This becomes - useful when the value would otherwise be taken from a different - source and could change, for example the default value could be - configurable by the user. A default switch value can be supplied in - case no other source exists and the application writer has a - preference. - </p> - <p> - Switches inherit all the properties of Options and Parents. - </p> - <table> - <tr> - <th>Property</th><th>Type</th><th>Description</th> - </tr> - <tr> - <td>defaultSwitch</td> - <td>Boolean</td> - <td> - The value to be used if the option has not been configured. If - not set the value <code>null</code> is used. - </td> - </tr> - </table> - </subsection> - - <subsection name="PropertyOption"> - <source>-Dproperty=value</source> - <p> - Property options allow arbitrary name value pairs to be passed in by - the user. This style of option is often used to emulate the java - <code>-D</code> option. - </p> - <p> - PropertyOptions inherit the properties of Options. - </p> - <table> - <tr> - <th>Property</th><th>Type</th><th>Description</th> - </tr> - <tr> - <td>optionString</td> - <td>String</td> - <td> - The prefix for this option, defaults to <code>-D</code>. - </td> - </tr> - </table> - </subsection> - - <subsection name="SourceDestArgument"> - - - - <source><src1> [<src2> ...] <dest></source> - <p> - Groups have the restriction that only the final argument can have - variable size. Using the SourceDestArgument this rule can appear - to be relaxed by shifting the variable size argument to an earlier - position. A SourceDestArgument is implemented by composing two other - options together. This option would typically be used when modelling - commands like the unix cp command, - </p> - <table> - <tr> - <th>Property</th><th>Type</th><th>Description</th> - </tr> - <tr> - <td>source</td> - <td>Argument</td> - <td> - The variable size first argument. - </td> - </tr> - <tr> - <td>dest</td> - <td>Argument</td> - <td> - The fixed size last argument. - </td> - </tr> - </table> - </subsection> - </section> - </body> -</document> http://git-wip-us.apache.org/repos/asf/commons-cli/blob/4dd97214/xdocs/manual/utilities.xml ---------------------------------------------------------------------- diff --git a/xdocs/manual/utilities.xml b/xdocs/manual/utilities.xml deleted file mode 100644 index 72746ba..0000000 --- a/xdocs/manual/utilities.xml +++ /dev/null @@ -1,38 +0,0 @@ -<?xml version="1.0"?> -<!-- - Copyright 2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<document> - - <properties> - <author email="[email protected]">commons-dev</author> - <title>CLI2 - Utilities</title> - </properties> - - <body> - <section name="Utilities"> - <img src="../images/utilities.jpg"/> - <subsection name="HelpFormatter"> - </subsection> - <subsection name="Comparators"> - </subsection> - </section> - <section name="Future Work"> - <p>TODO xml2cli</p> - <p>TODO cli2ant</p> - <p>TODO cli2html</p> - </section> - </body> -</document> http://git-wip-us.apache.org/repos/asf/commons-cli/blob/4dd97214/xdocs/manual/validators.xml ---------------------------------------------------------------------- diff --git a/xdocs/manual/validators.xml b/xdocs/manual/validators.xml deleted file mode 100644 index 6d0a15f..0000000 --- a/xdocs/manual/validators.xml +++ /dev/null @@ -1,203 +0,0 @@ -<?xml version="1.0"?> -<!-- - Copyright 2004 The Apache Software Foundation - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<document> - - <properties> - <author email="[email protected]">commons-dev</author> - <title>CLI2 - Validators</title> - </properties> - - <body> - <section name="Validators"> - <p> - CLI2 provides a mechanism to validate argument values. The <code>Validator</code> - interface must be implemented to create an argument validator. This interface has - a single method <code>validate(java.util.List values) throws InvalidArgumentException</code>. - </p> - <p> - CLI2 has some standard validators included. They validate the following: - </p> - <ul> - <li>Java class</li> - <li>date</li> - <li>enumeration</li> - <li>file path</li> - <li>number</li> - <li>URL</li> - </ul> - - <img src="../images/validators.jpg"/> - - <subsection name="ClassValidator"> - <p> - The <code>ClassValidator</code> validates a value using three criteria: - </p> - <ol> - <li>the value adheres to the Java Language Specification rules</li> - <li>the class specified by the name is loadable</li> - <li>the class specified by the name can be instantiated</li> - </ol> - <source>// 1. -ClassValidator validator = new ClassValidator(); -// 2. -validator.setLoadable(true); -// 3. -validator.setLoadable(true);</source> - <p> - TODO: add section about values being replaced with class instances - </p> - </subsection> - - <subsection name="DateValidator"> - <p> - The <code>DateValidator</code> validates values against a - <code>java.text.DateFormat</code>. There are three helper methods - that create built-in validators. - </p> - <ol> - <li><code>getDateInstance</code> returns a validator for the default - date format for the default locale. - </li> - <li><code>getTimeInstance</code> returns a validator for the default - time format for the default locale. - </li> - <li><code>getDateTimeInstance</code> returns a validator for the default - date and time format for the default locale. - </li> - </ol> - <p> - A <code>DateValidator</code> can also be created by passing your - a custom <code>DateFormat</code> into the constructor. - </p> - <source>DateFormat myFormat = DateFormat.getDateInstance( DateFormat.LONG, Locale.UK ); -DateValidator myValidator = new DateValidator( myFormat );</source> - <p> - In addition to basic format checking you can also check if the date/time specified - is before/after a specific date/time. The lower bound is set using the - <code>setMinimum( java.util.Date )</code>, and the upper bound is set using - the <code>setMaximum( java.util.Date )</code>. - </p> - <p> - TODO: add section about values being replaced with date instances - </p> - </subsection> - - <subsection name="EnumValidator"> - <p> - The <code>EnumValidator</code> validates values against a list of - allowed string values. The values that are allowed are specified in - a <code>java.util.Set</code> and passed in to the constructor. - </p> - <source>Set enumSet = new TreeSet(); -enumSet.add("red"); -enumSet.add("green"); -enumSet.add("blue"); - -EnumValidator validator = new EnumValidator( enumSet );</source> - </subsection> - - <subsection name="FileValidator"> - <p> - The <code>FileValidator</code> validates that values represent - existing files. You can also specify a combination of the - following additional criteria: - </p> - <ol> - <li>value is a file</li> - <li>value is a directory</li> - <li>the file is writable</li> - <li>the file is readable</li> - <li>the file is hidden</li> - </ol> - <p> - Each of the criteria listed here are specified using the appropriate - setter. - </p> - <p> - There are three helper methods to create validators: - </p> - <ol> - <li><code>getExistingInstance</code> returns a validator that ensures - a value represents an existing file. - </li> - <li><code>getExistingFileInstance</code> returns a validator that ensures - a value represents an existing file that is not a directory. - </li> - <li><code>getExistingDirectoryInstance</code> returns a validator that ensures - a value represents an existing file this is a directory. - </li> - </ol> - <source>// validate that the value represents a file that exists -FileValidator validator = FileValidator.getExistingInstance(); - -// ensure it's not a hidden file -validator.setHidden( false ); - -// ensure it's a writable file -validator.setWritable( true );</source> - - </subsection> - - <subsection name="NumberValidator"> - <p> - The <code>NumberValidator</code> validates that values adhere to - certain rules like the following: - </p> - <ol> - <li><code>getCurrencyInstance</code> returns a validator for the default - currency format for the default locale. - </li> - <li><code>getPercentInstance</code> returns a validator for the default - percent format for the default locale. - </li> - <li><code>getIntegerInstance</code> returns a validator for the default - integer format for the default locale. - </li> - <li><code>getNumberInstance</code> returns a validator for the default - number format for the default locale. - </li> - </ol> - <p> - A <code>NumberValidator</code> can also be created by passing your - a custom <code>NumberFormat</code> into the constructor. - </p> - <source>NumberFormat myFormat = NumberFormat.getCurrencyInstance( Locale.UK ); -NumberValidator myValidator = new NumberValidator( myFormat );</source> - <p> - In addition to basic format checking you can also check if the number specified - is less than or greater than a specific number. The lower bound is set using - the <code>setMinimum( Number )</code>, and the upper bound is set using - the <code>setMaximum( Number )</code>. - </p> - </subsection> - - <subsection name="UrlValidator"> - <p> - A <code>UrlValidator</code> validates that values are URLs and if you - choose it will also validate the protocol is of the type you have - specified. - </p> - <source>UrlValidator validator = new UrlValidator(); - -// only accept https URLs -validator.setProtocol("https");</source> - - </subsection> - - </section> - </body> -</document>
