Javadoc changes for release

Author: augustd

src/main/java/org/owasp/fileio/Encoder.java

@@ -81,6 +81,7 @@ public Encoder() {
 
     /**
      * Instantiates a new DefaultEncoder with the default codecs
+     * @param codecs A List of Codecs to use
      */
     public Encoder(List<Codec> codecs) {
 	this.codecs = codecs;

src/main/java/org/owasp/fileio/FileValidator.java

@@ -50,6 +50,7 @@ public StringValidationRule(String typeName, Encoder encoder, String whitelistPa
     }
 
     /**
+     * @param pattern A String which will be compiled into a regular expression pattern to add to the whitelist
      * @throws IllegalArgumentException if pattern is null
      */
     public void addWhitelistPattern(String pattern) {
@@ -64,6 +65,7 @@ public void addWhitelistPattern(String pattern) {
     }
 
     /**
+     * @param p A regular expression pattern to add to the whitelist
      * @throws IllegalArgumentException if p is null
      */
     public void addWhitelistPattern(Pattern p) {
@@ -74,6 +76,8 @@ public void addWhitelistPattern(Pattern p) {
     }
 
     /**
+     * @param pattern A String which will be compiled into a regular expression pattern to add to the blacklist
+
      * @throws IllegalArgumentException if pattern is null
      */
     public void addBlacklistPattern(String pattern) {
@@ -88,6 +92,7 @@ public void addBlacklistPattern(String pattern) {
     }
 
     /**
+     * @param p A regular expression pattern to add to the blacklist
      * @throws IllegalArgumentException if p is null
      */
     public void addBlacklistPattern(Pattern p) {
@@ -119,7 +124,7 @@ public void setValidateInputAndCanonical(boolean flag) {
      *
      * @param context The context to include in exception messages
      * @param input the input to check
-     * @param orig A origional input to include in exception messages. This is not included if it is the same as input.
+     * @param orig A original input to include in exception messages. This is not included if it is the same as input.
      * @return input upon a successful check
      * @throws ValidationException if the check fails.
      */
@@ -151,7 +156,7 @@ private String checkWhitelist(String context, String input) throws ValidationExc
      *
      * @param context The context to include in exception messages
      * @param input the input to check
-     * @param orig A origional input to include in exception messages. This is not included if it is the same as input.
+     * @param orig A original input to include in exception messages. This is not included if it is the same as input.
      * @return input upon a successful check
      * @throws ValidationException if the check fails.
      */

src/main/java/org/owasp/fileio/StringValidationRule.java

@@ -43,7 +43,7 @@ public Codec() {
     /**
      * Encode a String so that it can be safely used in a specific context.
      *
-     * @param immune
+     * @param immune An array of characters that will not be encoded.
      * @param input the String to encode
      * @return the encoded String
      */
@@ -59,7 +59,7 @@ public String encode(char[] immune, String input) {
     /**
      * Default implementation that should be overridden in specific codecs.
      *
-     * @param immune
+     * @param immune An array of characters that will not be encoded.
      * @param c the Character to encode
      * @return the encoded Character
      */
@@ -123,9 +123,9 @@ public static String toHex(char c) {
     /**
      * Utility to search a char[] for a specific char.
      *
-     * @param c
-     * @param array
-     * @return
+     * @param c The character to search for
+     * @param array The array of characters to search
+     * @return true if the array contains the character to search for
      */
     public static boolean containsCharacter(char c, char[] array) {
 	for (char ch : array) {

src/main/java/org/owasp/fileio/codecs/Codec.java

@@ -38,8 +38,9 @@ public HTMLEntityCodec() {
      *
      * Encodes a Character for safe use in an HTML entity field.
      *
-     * @param immune
+     * @param immune An array of characters that will not be encoded. 
      */
+    @Override
     public String encodeCharacter(char[] immune, Character c) {
 
 	// check for immune characters
@@ -74,8 +75,9 @@ public String encodeCharacter(char[] immune, Character c) {
      *
      * Returns the decoded version of the character starting at index, or null if no decoding is possible.
      *
-     * Formats all are legal both with and without semi-colon, upper/lower case: &#dddd; &#xhhhh; &name;
+     * Formats all are legal both with and without semi-colon, upper/lower case: &#dddd; &#xhhhh; &name;
      */
+    @Override
     public Character decodeCharacter(PushbackString input) {
 	input.mark();
 	Character first = input.next();

src/main/java/org/owasp/fileio/codecs/HTMLEntityCodec.java

@@ -28,7 +28,7 @@
  *
  * <b>NOTE:</b><br>
  * <ul>
- * <li>{@link Map.remove(Object)} is not supported.</li>
+ * <li>java.util.Map.remove(java.lang.Object) is not supported.</li>
  * <li>
  * If deletion support is added the max key length will need work or removal.
  * </li>
@@ -405,6 +405,7 @@ public HashTrie() {
      * @param key The key to lookup
      * @return Entry with the longest matching key.
      */
+    @Override
     public Map.Entry<CharSequence, T> getLongestMatch(CharSequence key) {
 	if (root == null || key == null) {
 	    return null;
@@ -419,6 +420,7 @@ public Map.Entry<CharSequence, T> getLongestMatch(CharSequence key) {
      * @return Entry with the longest matching key.
      * @throws IOException if keyIn.read() or keyIn.unread() does.
      */
+    @Override
     public Map.Entry<CharSequence, T> getLongestMatch(PushbackReader keyIn) throws IOException {
 	if (root == null || keyIn == null) {
 	    return null;
@@ -431,6 +433,7 @@ public Map.Entry<CharSequence, T> getLongestMatch(PushbackReader keyIn) throws I
      *
      * @return max key length.
      */
+    @Override
     public int getMaxKeyLength() {
 	return maxKeyLen;
     }
@@ -445,6 +448,7 @@ public int getMaxKeyLength() {
     /**
      * Clear all entries.
      */
+    @Override
     public void clear() {
 	root = null;
 	maxKeyLen = -1;
@@ -454,13 +458,15 @@ public void clear() {
     /**
      * {@inheritDoc}
      */
+    @Override
     public boolean containsKey(Object key) {
 	return (get(key) != null);
     }
 
     /**
      * {@inheritDoc}
      */
+    @Override
     public boolean containsValue(Object value) {
 	if (root == null) {
 	    return false;
@@ -472,9 +478,10 @@ public boolean containsValue(Object value) {
      * Add mapping.
      *
      * @param key The mapping's key.
-     * @value value The mapping's value
+     * @param value value The mapping's value
      * @throws NullPointerException if key or value is null.
      */
+    @Override
     public T put(CharSequence key, T value) throws NullPointerException {
 	int len;
 	T old;
@@ -486,7 +493,7 @@ public T put(CharSequence key, T value) throws NullPointerException {
 	    throw new NullPointerException("Null values are not handled");
 	}
 	if (root == null) {
-	    root = new Node<T>();
+	    root = new Node<>();
 	}
 	if ((old = root.put(key, 0, value)) != null) {
 	    return old;
@@ -506,13 +513,15 @@ public T put(CharSequence key, T value) throws NullPointerException {
      * @return previous value
      * @throws UnsupportedOperationException always.
      */
+    @Override
     public T remove(Object key) throws UnsupportedOperationException {
 	throw new UnsupportedOperationException();
     }
 
     /**
      * {@inheritDoc}
      */
+    @Override
     public void putAll(Map<? extends CharSequence, ? extends T> map) {
 	for (Map.Entry<? extends CharSequence, ? extends T> entry : map.entrySet()) {
 	    put(entry.getKey(), entry.getValue());
@@ -522,8 +531,9 @@ public void putAll(Map<? extends CharSequence, ? extends T> map) {
     /**
      * {@inheritDoc}
      */
+    @Override
     public Set<CharSequence> keySet() {
-	Set<CharSequence> keys = new HashSet<CharSequence>(size);
+	Set<CharSequence> keys = new HashSet<>(size);
 
 	if (root == null) {
 	    return keys;
@@ -534,8 +544,9 @@ public Set<CharSequence> keySet() {
     /**
      * {@inheritDoc}
      */
+    @Override
     public Collection<T> values() {
-	ArrayList<T> values = new ArrayList<T>(size());
+	ArrayList<T> values = new ArrayList<>(size());
 
 	if (root == null) {
 	    return values;
@@ -546,8 +557,9 @@ public Collection<T> values() {
     /**
      * {@inheritDoc}
      */
+    @Override
     public Set<Map.Entry<CharSequence, T>> entrySet() {
-	Set<Map.Entry<CharSequence, T>> entries = new HashSet<Map.Entry<CharSequence, T>>(size());
+	Set<Map.Entry<CharSequence, T>> entries = new HashSet<>(size());
 
 	if (root == null) {
 	    return entries;
@@ -561,6 +573,7 @@ public Set<Map.Entry<CharSequence, T>> entrySet() {
      * @param key The key to look up.
      * @return The value for key or null if the key is not found.
      */
+    @Override
     public T get(Object key) {
 	if (root == null || key == null) {
 	    return null;
@@ -576,6 +589,7 @@ public T get(Object key) {
      *
      * @return the number or entries.
      */
+    @Override
     public int size() {
 	return size;
     }
@@ -633,6 +647,7 @@ public String toString() {
     /**
      * {@inheritDoc}
      */
+    @Override
     public boolean isEmpty() {
 	return (size() == 0);
     }

src/main/java/org/owasp/fileio/codecs/HashTrie.java

@@ -24,16 +24,16 @@ public class PushbackString {
     private int mark = 0;
 
     /**
-     *
-     * @param input
+     * Constructs a new instance of PushbackString
+     * @param input the String to decode
      */
     public PushbackString(String input) {
 	this.input = input;
     }
 
     /**
      *
-     * @param c
+     * @param c The character to set as the pushback
      */
     public void pushback(Character c) {
 	pushback = c;
@@ -50,7 +50,7 @@ public int index() {
 
     /**
      *
-     * @return
+     * @return true if there are more characters to process
      */
     public boolean hasNext() {
 	if (pushback != null) {
@@ -70,7 +70,7 @@ public boolean hasNext() {
 
     /**
      *
-     * @return
+     * @return the next character
      */
     public Character next() {
 	if (pushback != null) {
@@ -92,7 +92,7 @@ public Character next() {
 
     /**
      *
-     * @return
+     * @return the next hex digit in the input, or null if the next character is not hex
      */
     public Character nextHex() {
 	Character c = next();
@@ -107,7 +107,7 @@ public Character nextHex() {
 
     /**
      *
-     * @return
+     * @return the next octal digit in the input, or null if the next character is not octal
      */
     public Character nextOctal() {
 	Character c = next();
@@ -123,8 +123,8 @@ public Character nextOctal() {
     /**
      * Returns true if the parameter character is a hexidecimal digit 0 through 9, a through f, or A through F.
      *
-     * @param c
-     * @return
+     * @param c The Character to test
+     * @return true if the input character is a hex digit (0-F)
      */
     public static boolean isHexDigit(Character c) {
 	if (c == null) {
@@ -137,8 +137,8 @@ public static boolean isHexDigit(Character c) {
     /**
      * Returns true if the parameter character is an octal digit 0 through 7.
      *
-     * @param c
-     * @return
+     * @param c The Character to test
+     * @return true if the input character is an octal digit (0-7)
      */
     public static boolean isOctalDigit(Character c) {
 	if (c == null) {
@@ -151,7 +151,7 @@ public static boolean isOctalDigit(Character c) {
     /**
      * Return the next character without affecting the current index.
      *
-     * @return
+     * @return the next Character in the input
      */
     public Character peek() {
 	if (pushback != null) {
@@ -172,8 +172,8 @@ public Character peek() {
     /**
      * Test to see if the next character is a particular value without affecting the current index.
      *
-     * @param c
-     * @return
+     * @param c The character to test for
+     * @return true if the next character matches the input character
      */
     public boolean peek(char c) {
 	if (pushback != null && pushback.charValue() == c) {
@@ -209,7 +209,7 @@ public void reset() {
 
     /**
      *
-     * @return
+     * @return the remainder of the input String, prepended with any pushback, if necessary
      */
     protected String remainder() {
 	String output = input.substring(index);

src/main/java/org/owasp/fileio/codecs/PushbackString.java

@@ -18,7 +18,7 @@
 /**
  * This class provides a number of utility functions.
  *
- * @author August Detlefsen <augustd at codemagi dot com>
+ * @author August Detlefsen [augustd at codemagi dot com]
  */
 public class Utils {