LANG-1372: Add ToStringSummary annotation (closes #281)

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

@@ -84,6 +84,10 @@ import org.apache.commons.lang3.Validate;
  * result.
  * </p>
  * <p>
+ * It is also possible to use the {@link ToStringSummary} annotation to output the summary information instead of the
+ * detailed information of a field.
+ * </p>
+ * <p>
  * The exact format of the <code>toString</code> is determined by the {@link ToStringStyle} passed into the constructor.
  * </p>
  *
@@ -119,6 +123,7 @@ public class ReflectionToStringBuilder extends ToStringBuilder {
      *             if the Object is <code>null</code>
      *
      * @see ToStringExclude
+     * @see ToStringSummary
      */
     public static String toString(final Object object) {
         return toString(object, null, false, false, null);
@@ -153,6 +158,7 @@ public class ReflectionToStringBuilder extends ToStringBuilder {
      *             if the Object or <code>ToStringStyle</code> is <code>null</code>
      *
      * @see ToStringExclude
+     * @see ToStringSummary
      */
     public static String toString(final Object object, final ToStringStyle style) {
         return toString(object, style, false, false, null);
@@ -193,6 +199,7 @@ public class ReflectionToStringBuilder extends ToStringBuilder {
      *             if the Object is <code>null</code>
      *
      * @see ToStringExclude
+     * @see ToStringSummary
      */
     public static String toString(final Object object, final ToStringStyle style, final boolean outputTransients) {
         return toString(object, style, outputTransients, false, null);
@@ -240,6 +247,7 @@ public class ReflectionToStringBuilder extends ToStringBuilder {
      *             if the Object is <code>null</code>
      *
      * @see ToStringExclude
+     * @see ToStringSummary
      * @since 2.1
      */
     public static String toString(final Object object, final ToStringStyle style, final boolean outputTransients, final boolean outputStatics) {
@@ -293,6 +301,7 @@ public class ReflectionToStringBuilder extends ToStringBuilder {
      *             if the Object is <code>null</code>
      *
      * @see ToStringExclude
+     * @see ToStringSummary
      * @since 2.1
      */
     public static <T> String toString(
@@ -351,6 +360,7 @@ public class ReflectionToStringBuilder extends ToStringBuilder {
      *             if the Object is <code>null</code>
      *
      * @see ToStringExclude
+     * @see ToStringSummary
      * @since 3.6
      */
     public static <T> String toString(
@@ -639,7 +649,7 @@ public class ReflectionToStringBuilder extends ToStringBuilder {
                     // for primitive types.
                     final Object fieldValue = this.getValue(field);
                     if (!excludeNullValues || fieldValue != null) {
-                        this.append(fieldName, fieldValue);
+                        this.append(fieldName, fieldValue, !field.isAnnotationPresent(ToStringSummary.class));
                     }
                 } catch (final IllegalAccessException ex) {
                     //this can't happen. Would get a Security exception

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

@@ -0,0 +1,40 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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.
+ */
+
+package org.apache.commons.lang3.builder;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Use this annotation on the fields to get the summary instead of the detailed
+ * information when using {@link ReflectionToStringBuilder}.
+ *
+ * <p>
+ * Notice that not all {@link ToStringStyle} implementations support the
+ * appendSummary method.
+ * </p>
+ *
+ * @since 3.8
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.FIELD)
+public @interface ToStringSummary {
+
+}

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

@@ -0,0 +1,36 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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.
+ */
+package org.apache.commons.lang3.builder;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+public class ReflectionToStringBuilderSummaryTest {
+
+    @SuppressWarnings("unused")
+    private String stringField = "string";
+
+    @ToStringSummary
+    private String summaryString = "summary";
+
+    @Test
+    public void testSummary() {
+        Assert.assertEquals("[stringField=string,summaryString=<String>]",
+                new ReflectionToStringBuilder(this, ToStringStyle.NO_CLASS_NAME_STYLE).build());
+    }
+
+}