Merge branch 'LANG-1031-cleanup'

Some cleanups following the integration of LANG-1031 (PR #77 from github)

src/main/java/org/apache/commons/lang3/builder/EqualsBuilder.java

@@ -77,6 +77,9 @@
  *   return EqualsBuilder.reflectionEquals(this, obj);
  * }
  * </pre>
+ * 
+ * <p>The {@link EqualsExclude} annotation can be used to exclude fields from being
+ * used by the <code>reflectionEquals</code> methods.</p>
  *
  * @since 1.0
  * @version $Id$
@@ -245,6 +248,8 @@ public EqualsBuilder() {
      * @param rhs  the other object
      * @param excludeFields  Collection of String field names to exclude from testing
      * @return <code>true</code> if the two Objects have tested equals.
+     * 
+     * @see EqualsExclude
      */
     public static boolean reflectionEquals(final Object lhs, final Object rhs, final Collection<String> excludeFields) {
         return reflectionEquals(lhs, rhs, ReflectionToStringBuilder.toNoNullStringArray(excludeFields));
@@ -269,6 +274,8 @@ public static boolean reflectionEquals(final Object lhs, final Object rhs, final
      * @param rhs  the other object
      * @param excludeFields  array of field names to exclude from testing
      * @return <code>true</code> if the two Objects have tested equals.
+     * 
+     * @see EqualsExclude
      */
     public static boolean reflectionEquals(final Object lhs, final Object rhs, final String... excludeFields) {
         return reflectionEquals(lhs, rhs, false, null, excludeFields);
@@ -294,6 +301,8 @@ public static boolean reflectionEquals(final Object lhs, final Object rhs, final
      * @param rhs  the other object
      * @param testTransients  whether to include transient fields
      * @return <code>true</code> if the two Objects have tested equals.
+     * 
+     * @see EqualsExclude
      */
     public static boolean reflectionEquals(final Object lhs, final Object rhs, final boolean testTransients) {
         return reflectionEquals(lhs, rhs, testTransients, null);
@@ -324,6 +333,8 @@ public static boolean reflectionEquals(final Object lhs, final Object rhs, final
      *  may be <code>null</code>
      * @param excludeFields  array of field names to exclude from testing
      * @return <code>true</code> if the two Objects have tested equals.
+     * 
+     * @see EqualsExclude
      * @since 2.0
      */
     public static boolean reflectionEquals(final Object lhs, final Object rhs, final boolean testTransients, final Class<?> reflectUpToClass,

src/main/java/org/apache/commons/lang3/builder/EqualsExclude.java

@@ -19,13 +19,15 @@
 
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Use this annotation to builds a equals excluding the annotated field.
+ * Use this annotation to exclude a field from being being used by
+ * the various <code>reflectionEquals</code> methods defined on
+ * {@link EqualsBuilder}.
  */
-@Retention(RUNTIME)
+@Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.FIELD)
 public @interface EqualsExclude {
 

src/main/java/org/apache/commons/lang3/builder/HashCodeBuilder.java

@@ -94,6 +94,9 @@
  *   return HashCodeBuilder.reflectionHashCode(this);
  * }
  * </pre>
+ * 
+ * <p>The {@link HashCodeExclude} annotation can be used to exclude fields from being
+ * used by the <code>reflectionHashCode</code> methods.</p>
  *
  * @since 1.0
  * @version $Id$
@@ -246,6 +249,8 @@ private static void reflectionAppend(final Object object, final Class<?> clazz,
      *             if the Object is <code>null</code>
      * @throws IllegalArgumentException
      *             if the number is zero or even
+     *
+     * @see HashCodeExclude
      */
     public static int reflectionHashCode(final int initialNonZeroOddNumber, final int multiplierNonZeroOddNumber, final Object object) {
         return reflectionHashCode(initialNonZeroOddNumber, multiplierNonZeroOddNumber, object, false, null);
@@ -290,6 +295,8 @@ public static int reflectionHashCode(final int initialNonZeroOddNumber, final in
      *             if the Object is <code>null</code>
      * @throws IllegalArgumentException
      *             if the number is zero or even
+     *
+     * @see HashCodeExclude
      */
     public static int reflectionHashCode(final int initialNonZeroOddNumber, final int multiplierNonZeroOddNumber, final Object object,
             final boolean testTransients) {
@@ -342,6 +349,8 @@ public static int reflectionHashCode(final int initialNonZeroOddNumber, final in
      *             if the Object is <code>null</code>
      * @throws IllegalArgumentException
      *             if the number is zero or even
+     *
+     * @see HashCodeExclude
      * @since 2.0
      */
     public static <T> int reflectionHashCode(final int initialNonZeroOddNumber, final int multiplierNonZeroOddNumber, final T object,
@@ -392,6 +401,8 @@ public static <T> int reflectionHashCode(final int initialNonZeroOddNumber, fina
      * @return int hash code
      * @throws IllegalArgumentException
      *             if the object is <code>null</code>
+     *
+     * @see HashCodeExclude
      */
     public static int reflectionHashCode(final Object object, final boolean testTransients) {
         return reflectionHashCode(DEFAULT_INITIAL_VALUE, DEFAULT_MULTIPLIER_VALUE, object, 
@@ -430,6 +441,8 @@ public static int reflectionHashCode(final Object object, final boolean testTran
      * @return int hash code
      * @throws IllegalArgumentException
      *             if the object is <code>null</code>
+     *
+     * @see HashCodeExclude
      */
     public static int reflectionHashCode(final Object object, final Collection<String> excludeFields) {
         return reflectionHashCode(object, ReflectionToStringBuilder.toNoNullStringArray(excludeFields));
@@ -469,6 +482,8 @@ public static int reflectionHashCode(final Object object, final Collection<Strin
      * @return int hash code
      * @throws IllegalArgumentException
      *             if the object is <code>null</code>
+     *
+     * @see HashCodeExclude
      */
     public static int reflectionHashCode(final Object object, final String... excludeFields) {
         return reflectionHashCode(DEFAULT_INITIAL_VALUE, DEFAULT_MULTIPLIER_VALUE, object, false, 

src/main/java/org/apache/commons/lang3/builder/HashCodeExclude.java

@@ -19,13 +19,15 @@
 
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Use this annotation to builds a hash code excluding the annotated field.
+ * Use this annotation to exclude a field from being being used by
+ * the various <code>reflectionHashcode</code> methods defined on
+ * {@link HashCodeBuilder}.
  */
-@Retention(RUNTIME)
+@Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.FIELD)
 public @interface HashCodeExclude {
 

src/main/java/org/apache/commons/lang3/builder/ReflectionToStringBuilder.java

@@ -79,6 +79,10 @@
  * }
  * </pre>
  * <p>
+ * Alternatively the {@link ToStringExclude} annotation can be used to exclude fields from being incorporated in the 
+ * result.
+ * </p>
+ * <p>
  * The exact format of the <code>toString</code> is determined by the {@link ToStringStyle} passed into the constructor.
  * </p>
  *
@@ -113,6 +117,8 @@ public class ReflectionToStringBuilder extends ToStringBuilder {
      * @return the String result
      * @throws IllegalArgumentException
      *             if the Object is <code>null</code>
+     *
+     * @see ToStringExclude
      */
     public static String toString(final Object object) {
         return toString(object, null, false, false, null);
@@ -145,6 +151,8 @@ public static String toString(final Object object) {
      * @return the String result
      * @throws IllegalArgumentException
      *             if the Object or <code>ToStringStyle</code> is <code>null</code>
+     *
+     * @see ToStringExclude
      */
     public static String toString(final Object object, final ToStringStyle style) {
         return toString(object, style, false, false, null);
@@ -183,6 +191,8 @@ public static String toString(final Object object, final ToStringStyle style) {
      * @return the String result
      * @throws IllegalArgumentException
      *             if the Object is <code>null</code>
+     *
+     * @see ToStringExclude
      */
     public static String toString(final Object object, final ToStringStyle style, final boolean outputTransients) {
         return toString(object, style, outputTransients, false, null);
@@ -228,6 +238,8 @@ public static String toString(final Object object, final ToStringStyle style, fi
      * @return the String result
      * @throws IllegalArgumentException
      *             if the Object is <code>null</code>
+     * 
+     * @see ToStringExclude
      * @since 2.1
      */
     public static String toString(final Object object, final ToStringStyle style, final boolean outputTransients, final boolean outputStatics) {
@@ -279,6 +291,8 @@ public static String toString(final Object object, final ToStringStyle style, fi
      * @return the String result
      * @throws IllegalArgumentException
      *             if the Object is <code>null</code>
+     * 
+     * @see ToStringExclude
      * @since 2.1
      */
     public static <T> String toString(

src/main/java/org/apache/commons/lang3/builder/ToStringExclude.java

@@ -20,12 +20,13 @@
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
-import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import java.lang.annotation.RetentionPolicy;
 
 /**
- * Use this annotation to builds a String excluding the annotated field.
+ * Use this annotation to exclude a field from being being used by
+ * the {@link ReflectionToStringBuilder}.
  */
-@Retention(RUNTIME)
+@Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.FIELD)
 public @interface ToStringExclude {
 

src/test/java/org/apache/commons/lang3/builder/ReflectionToStringBuilderExcludeWithAnnotationTest.java

@@ -17,8 +17,10 @@
 
 package org.apache.commons.lang3.builder;
 
-import org.apache.commons.lang3.ArrayUtils;
+import static org.hamcrest.Matchers.containsString;
-import org.junit.Assert;
+import static org.hamcrest.Matchers.not;
+import static org.junit.Assert.assertThat;
+
 import org.junit.Test;
 
 /**
@@ -29,34 +31,28 @@ public class ReflectionToStringBuilderExcludeWithAnnotationTest {
 
     class TestFixture {
         @ToStringExclude
-        private final String secretField = SECRET_VALUE;
+        private final String excludedField = EXCLUDED_FIELD_VALUE;
 
         @SuppressWarnings("unused")
-        private final String showField = NOT_SECRET_VALUE;
+        private final String includedField = INCLUDED_FIELD_VALUE;
     }
 
-    private static final String NOT_SECRET_FIELD = "showField";
+    private static final String INCLUDED_FIELD_NAME = "includedField";
 
-    private static final String NOT_SECRET_VALUE = "Hello World!";
+    private static final String INCLUDED_FIELD_VALUE = "Hello World!";
 
-    private static final String SECRET_FIELD = "secretField";
+    private static final String EXCLUDED_FIELD_NAME = "excludedField";
 
-    private static final String SECRET_VALUE = "secret value";
+    private static final String EXCLUDED_FIELD_VALUE = "excluded field value";
 
     @Test
     public void test_toStringExclude() {
         final String toString = ReflectionToStringBuilder.toString(new TestFixture());
-        this.validateSecretFieldAbsent(toString);
+
+        assertThat(toString, not(containsString(EXCLUDED_FIELD_NAME)));
+        assertThat(toString, not(containsString(EXCLUDED_FIELD_VALUE)));
+        assertThat(toString, containsString(INCLUDED_FIELD_NAME));
+        assertThat(toString, containsString(INCLUDED_FIELD_VALUE));
     }
 
-    private void validateNonSecretField(final String toString) {
-        Assert.assertTrue(toString.indexOf(NOT_SECRET_FIELD) > ArrayUtils.INDEX_NOT_FOUND);
-        Assert.assertTrue(toString.indexOf(NOT_SECRET_VALUE) > ArrayUtils.INDEX_NOT_FOUND);
-    }
-
-    private void validateSecretFieldAbsent(final String toString) {
-        Assert.assertEquals(ArrayUtils.INDEX_NOT_FOUND, toString.indexOf(SECRET_FIELD));
-        Assert.assertEquals(ArrayUtils.INDEX_NOT_FOUND, toString.indexOf(SECRET_VALUE));
-        this.validateNonSecretField(toString);
-    }
 }