commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nia...@apache.org
Subject svn commit: r484904 - in /jakarta/commons/proper/validator/trunk: src/share/org/apache/commons/validator/routines/RegexValidator.java src/share/org/apache/commons/validator/routines/package.html xdocs/changes.xml
Date Sat, 09 Dec 2006 03:29:48 GMT
Author: niallp
Date: Fri Dec  8 19:29:47 2006
New Revision: 484904

URL: http://svn.apache.org/viewvc?view=rev&rev=484904
Log:
Update release notes, routines documentation and few JavaDoc corrections

Modified:
    jakarta/commons/proper/validator/trunk/src/share/org/apache/commons/validator/routines/RegexValidator.java
    jakarta/commons/proper/validator/trunk/src/share/org/apache/commons/validator/routines/package.html
    jakarta/commons/proper/validator/trunk/xdocs/changes.xml

Modified: jakarta/commons/proper/validator/trunk/src/share/org/apache/commons/validator/routines/RegexValidator.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/validator/trunk/src/share/org/apache/commons/validator/routines/RegexValidator.java?view=diff&rev=484904&r1=484903&r2=484904
==============================================================================
--- jakarta/commons/proper/validator/trunk/src/share/org/apache/commons/validator/routines/RegexValidator.java
(original)
+++ jakarta/commons/proper/validator/trunk/src/share/org/apache/commons/validator/routines/RegexValidator.java
Fri Dec  8 19:29:47 2006
@@ -21,12 +21,12 @@
 import java.util.regex.Matcher;
 
 /**
- * Regular Expression validator (using JDK 1.4+ regex support).
+ * <b>Regular Expression</b> validation (using JDK 1.4+ regex support).
  * <p>
  * This validator provides convenient regular expression validation
  * in one of two ways:
  *
- * <h4>1. One Off validation using the static methods<h4>
+ * <h4>1. One Off validation using the static methods</h4>
  * <ul>
  *   <li>Validate <code>true</code> or <code>false</code>:</li>
  *   <ul>
@@ -45,11 +45,11 @@
  *   </ul>
  * </ul>
  *
- * <h4>2. Re-using cached instances validating against one or more regular expression<h4>
+ * <h4>2. Re-using cached instances validating against one or more regular expression</h4>
  * Construct the validator either for a single regular expression or a set (array) of 
  * regular expressions. By default validation is <i>case sensitive</i> but constructors
  * are provided to allow  <i>case in-sensitive</i> validation. For example to
create
- * a validator which does <i><i>case in-sensitive</i> validation for a
set of regular
+ * a validator which does <i>case in-sensitive</i> validation for a set of regular
  * expressions:
  * <pre>
  *         String[] regexs = new String[] {...};

Modified: jakarta/commons/proper/validator/trunk/src/share/org/apache/commons/validator/routines/package.html
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/validator/trunk/src/share/org/apache/commons/validator/routines/package.html?view=diff&rev=484904&r1=484903&r2=484904
==============================================================================
--- jakarta/commons/proper/validator/trunk/src/share/org/apache/commons/validator/routines/package.html
(original)
+++ jakarta/commons/proper/validator/trunk/src/share/org/apache/commons/validator/routines/package.html
Fri Dec  8 19:29:47 2006
@@ -41,6 +41,12 @@
     <li>3.5 <a href="#numeric.currency">Currency Validation</a></li>
     <li>3.6 <a href="#numeric.percent">Percent Validation</a></li>
     </ul></li>
+<li>2. <a href="#other">Other Validators</a>
+    <ul>
+    <li>4.1 <a href="#other.overview">Overview</a></li>
+    <li>4.2 <a href="#other.regex">Regular Expression validation</a></li>
+    <li>4.3 <a href="#other.checkdigit">Check Digit Validation/Calculation</a></li>
+    </ul></li>
 </ul>
 
 <a name="overview"></a>
@@ -399,6 +405,176 @@
    also support percent validation. However, since they don't allow fractions
    they will only work with percentages greater than 100%.
 </p>
+
+<a name="other"></a>
+<h1>4. Other Validators</h1>
+
+<a name="other.overview"></a>
+<h3>4.1 Overview</h3>
+<p>
+   This section lists other available validators.
+</p>
+<ul>
+   <li><a href="#other.regex">Regular Expressions</a> - validates
+       using Java 1.4+ regular expression support</li>
+   <li><a href="#other.checkdigit">Check Digit</a> - validates/calculates
+       check digits (i.e. EAN/UPC, credit card, ISBN).</li>
+</ul>
+
+<a name="other.regex"></a>
+<h3>4.2 Regular Expression Validation</h3>
+<p>
+   Regular expression validation can be done either by using the <i>static</i>
+   methods provied by <a href="RegexValidator.html">RegexValidator</a> or
+   by creating a new instance, which caches and re-uses compiled Patterns.
+</p>
+<ul>
+   <li><b>Method Flavours</b> - three <i>flavours</i> of validation
metods are provided:</li>
+    <ul>
+        <li><code>isValid()</code> methods return true/false to indicate
+            whether validation was successful.</li>
+        <li><code>validate()</code> methods return a <code>String</code>
+            value of the matched <i>groups</i> aggregated together or
+            <code>null</code> if invalid.</li>
+        <li><code>match()</code> methods return a <code>String</code>
array
+            of the matched <i>groups</i> or <code>null</code> if
invalid.</li>
+    </ul>
+   <li><b>Case Sensitivity</b> - matching can be done in either a <i>case
+       sensitive</i> or <i>case in-sensitive</i> way.</li>
+   <li><b>Multiple Expressions</b> - instances of the
+       <a href="RegexValidator.html">RegexValidator</a>
+       can be created to either match against a single regular expression
+       or set (String array) of regular expressions.</li>
+</ul>
+<p>
+   Below is an example of using one of the static methods to validate,
+   matching in a <i>case insensitive</i> manner and returning a String
+   of the matched groups (which doesn't include the hyphen).
+</p>
+<pre>
+      // set up the parameters
+      boolean caseSensitive   = false;
+      String regex            = "^([A-Z]*)(?:\\-)([A-Z]*)$";
+
+      // validate - result should be a String of value "abcdef"
+      String result = RegexValidator.validate("abc-def", regex, caseSensitive);
+
+</pre>
+
+<p>The following static methods are provided for regular expression validation:
+</p>
+<ul>
+    <li><code>isValid(<i>value</i>, <i>regex</i>)</code></li>
+    <li><code>isValid(<i>value</i>, <i>regex</i>, <i>caseSensitive</i>)</code></li>
+    <li><code>validate(<i>value</i>, <i>regex</i>)</code></li>
+    <li><code>validate(<i>value</i>, <i>regex</i>, <i>caseSensitive</i>)</code></li>
+    <li><code>match(<i>value</i>, <i>regex</i>)</code></li>
+    <li><code>match(<i>value</i>, <i>regex</i>, <i>caseSensitive</i>)</code></li>
+</ul>
+<p>
+   Below is an example of creating an instance of
+   <a href="RegexValidator.html">RegexValidator</a> matching in a <i>case
insensitive</i>
+   manner against a set of regular expressions:
+</p>
+<pre>
+      // set up the parameters
+      boolean caseSensitive = false;
+      String regex1   = "^([A-Z]*)(?:\\-)([A-Z]*)*$"
+      String regex2   = "^([A-Z]*)$";
+      String[] regexs = new String[] {regex1, regex1};
+
+      // Create the validator
+      RegexValidator validator = new RegexValidator(regexs, caseSensitive);
+
+      // Validate true/false
+      boolean valid = validator.isValid("abc-def");
+
+      // Validate and return a String
+      String result = validator.validate("abc-def");
+
+      // Validate and return a String[]
+      String[] groups = validator.match("abc-def");
+
+</pre>
+<p>See the
+   <a href="RegexValidator.html">RegexValidator</a> javadoc for a full list
+   of the available constructors.
+</p>
+
+<a name="other.checkdigit"></a>
+<h3>4.3 Check Digit validation/calculation</h3>
+<p>
+   <a href="checkdigit/CheckDigit.html">CheckDigit</a> defines a new
+   type for the calculation and validation of check digits with the 
+   following methods:
+</p>
+<ul>
+    <li><code>isValid(<i>code</i>)</code> - validates the check
digit of a code,
+        returning <code>true</code> or <code>false</code>.</li>
+    <li><code>calculate(<i>code</i>)</code> - calulates the
check digit for a code
+        returning the check digit character.</li>
+</ul>
+<p>
+   The following implementations are provided:
+</p>
+<ul>
+    <li><a href="checkdigit/ModulusCheckDigit.html">ModulusCheckDigit</a>
+        - <b>abstract</b> class for custom <b>modulus</b> check digit
+        implementations.</li>
+    <li><a href="checkdigit/LuhnCheckDigit.html">LuhnCheckDigit</a>
+        for <b>Luhn</b> check digit calculation - used by <b>credit cards</b>.</li>
+    <li><a href="checkdigit/EAN13CheckDigit.html">EAN13CheckDigit</a>
+        for <b>EAN-13</b>, <b>UPC</b>, <b>ISBN-13</b>
check digit calculation.</li>
+    <li><a href="checkdigit/ISBNCheckDigit.html">ISBNCheckDigit</a>
+        for <b>ISBN-10</b> and <b>ISBN-13</b> check digit calculation.</li>
+    <li><a href="checkdigit/ISBN10CheckDigit.html">ISBN10CheckDigit</a>
+        for <b>ISBN-10</b> check digit calculation.</li>
+</ul>
+<p>
+   The following examples show validating the check digit of a code:
+</p>
+<pre>
+
+      // Luhn check digit validation
+      boolean valid = LuhnCheckDigit.INSTANCE.isValid(code);
+
+      // EAN / UPC / ISBN-13 check digit validation
+      boolean valid = EAN13CheckDigit.INSTANCE.isValid(code);
+
+      // ISBN-10 check digit validation
+      boolean valid = ISBNCheckDigit.ISBN10.isValid(code);
+      boolean valid = ISBN10CheckDigit.INSTANCE.isValid(code);
+
+      // ISBN-13 check digit validation
+      boolean valid = ISBNCheckDigit.ISBN13.isValid(code);
+
+      // ISBN-10 or ISBN-13 check digit validation
+      boolean valid = ISBNCheckDigit.ISBN.isValid(code);
+
+</pre>
+<p>
+   The following examples show calulating the check digit of a code:
+</p>
+<pre>
+
+      // Luhn check digit validation
+      char checkdigit = LuhnCheckDigit.INSTANCE.calculate(code);
+
+      // EAN / UPC / ISBN-13 check digit validation
+      char checkdigit = EAN13CheckDigit.INSTANCE.calculate(code);
+
+      // ISBN-10 check digit validation
+      char checkdigit = ISBNCheckDigit.ISBN10.isValid(code);
+      char checkdigit = ISBN10CheckDigit.INSTANCE.calculate(code);
+
+      // ISBN-13 check digit validation
+      char checkdigit = ISBNCheckDigit.ISBN13.calculate(code);
+
+      // ISBN-10 or ISBN-13 check digit validation
+      char checkdigit = ISBNCheckDigit.ISBN.calculate(code);
+
+</pre>
+
 
 </body>
 </html>

Modified: jakarta/commons/proper/validator/trunk/xdocs/changes.xml
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/validator/trunk/xdocs/changes.xml?view=diff&rev=484904&r1=484903&r2=484904
==============================================================================
--- jakarta/commons/proper/validator/trunk/xdocs/changes.xml (original)
+++ jakarta/commons/proper/validator/trunk/xdocs/changes.xml Fri Dec  8 19:29:47 2006
@@ -40,6 +40,15 @@
   <body>
 
     <release version="1.4-SNAPSHOT" date="in SVN" description="In progress">
+      <action dev="niallp" type="add" issue="VALIDATOR-214">
+          New Regular Expression validator using JDK 1.4's Regex - see
+          <a href="apidocs/org/apache/commons/validator/routines/RegexValidator.html">RegexValidator</a>.
+      </action>
+      <action dev="niallp" type="add" issue="VALIDATOR-213">
+          Factor out Check Digit logic into separate implementations. A
+          new <a href="apidocs/org/apache/commons/validator/routines/checkdigit/CheckDigit.html">CheckDigit</a>
type has been added with a number
+          of <a href="apidocs/org/apache/commons/validator/routines/checkdigit/package-summary.html">implementations</a>.
+      </action>
       <action dev="niallp" type="update" issue="VALIDATOR-211">
           Upgrade to Digester 1.8
       </action>



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message