- updated javadoc

- added protocol constructor
- added default constructor


git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/cli/trunk@267451 13f79535-47bb-0310-9956-ffa450edef68

Author: John Keyes

src/java/org/apache/commons/cli2/validation/UrlValidator.java

@@ -1,5 +1,5 @@
-/**
- * Copyright 2003-2004 The Apache Software Foundation
+/*
+ * Copyright 2003-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.
@@ -21,12 +21,54 @@
 import java.util.ListIterator;
 
 /**
- * A Validator instance that accepts urls
+ * The <code>UrlValidator</code> validates the string argument
+ * values are URLs.  If the value is a URL, the string value in
+ * the {@link java.util.List} of values is replaced with the
+ * {@link java.net.URL} instance.
+ *
+ * URLs can also be validated based on their scheme by using 
+ * the {@link #setProtocol setProtocol} method, or by using the specified
+ * {@link UrlValidator(java.lang.String) constructor}.
+ *
+ * The following example shows how to limit the valid values
+ * for the site argument to 'https' URLs.
+ *
+ * <pre>
+ * ...
+ * ArgumentBuilder builder = new ArgumentBuilder();
+ * Argument site = 
+ *     builder.withName("site");
+ *            .withValidator(new URLValidator("https"));
+ * </pre>
+ * 
+ * @author Rob Oxspring
+ * @author John Keyes
  */
 public class UrlValidator implements Validator {
 
+    /** allowed protocol */
     private String protocol = null;
 
+    /**
+     * Creates a UrlValidator.
+     */
+    public UrlValidator() {
+    }
+
+    /**
+     * Creates a UrlValidator for the specified protocol.
+     */
+    public UrlValidator(final String protocol) {
+        setProtocol(protocol);
+    }
+
+    /**
+     * Validate the list of values against the list of permitted values.
+     * If a value is valid, replace the string in the <code>values</code>
+     * {@link java.util.List} with the {@link java.net.URL}.
+     * 
+     * @see org.apache.commons.cli2.validation.Validator#validate(java.util.List)
+     */
     public void validate(final List values) throws InvalidArgumentException {
         for (final ListIterator i = values.listIterator(); i.hasNext();) {
             final String name = (String)i.next();
@@ -47,16 +89,21 @@ public void validate(final List values) throws InvalidArgumentException {
     }
 
     /**
-     * @return the protocol that must be used by a valid url
+     * Returns the protocol that must be used by a valid URL.
+     *
+     * @return the protocol that must be used by a valid URL.
      */
     public String getProtocol() {
         return protocol;
     }
 
     /**
-     * @param protocol the protocol that a valid url must use
+     * Specifies the protocol that a URL must have to be valid.
+     *
+     * @param protocol the protocol that a URL must have to be valid.
      */
     public void setProtocol(String protocol) {
         this.protocol = protocol;
     }
+
 }