Mailing-List: contact commits-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@commons.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1200177 -
 /commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/ReflectionToStringBuilder.java
Date: Thu, 10 Nov 2011 06:14:34 -0000
To: commits@commons.apache.org
From: ggregory@apache.org
Message-Id: <20111110061434.1EAAD2388A5E@eris.apache.org>

Author: ggregory
Date: Thu Nov 10 06:14:33 2011
New Revision: 1200177

URL: http://svn.apache.org/viewvc?rev=1200177&view=rev
Log:
[LANG-762] Handle or document ReflectionToStringBuilder and ToStringBuilder for collections that are not thread safe. Better Javadocs. See Phil's comments in the Jira.

Modified:
    commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/ReflectionToStringBuilder.java

Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/ReflectionToStringBuilder.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/ReflectionToStringBuilder.java?rev=1200177&r1=1200176&r2=1200177&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/ReflectionToStringBuilder.java (original)
+++ commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/builder/ReflectionToStringBuilder.java Thu Nov 10 06:14:33 2011
@@ -32,34 +32,33 @@ import org.apache.commons.lang3.ClassUti
  * <p>
  * Assists in implementing {@link Object#toString()} methods using reflection.
  * </p>
- *
  * <p>
  * This class uses reflection to determine the fields to append. Because these fields are usually private, the class
  * uses {@link java.lang.reflect.AccessibleObject#setAccessible(java.lang.reflect.AccessibleObject[], boolean)} to
  * change the visibility of the fields. This will fail under a security manager, unless the appropriate permissions are
  * set up correctly.
  * </p>
- *
+ * <p>
+ * Using reflection to access (private) fields circumvents any synchronization protection guarding access to these
+ * fields. If a toString method cannot safely read a field, you should exclude it from the toString method, or use
+ * synchronization consistent with the class' lock management around the invocation of the method. Take special care to
+ * exclude non-thread-safe collection classes, because these classes may throw ConcurrentModificationException if
+ * modified while the toString method is executing.
+ * </p>
  * <p>
  * A typical invocation for this method would look like:
  * </p>
- *
  * <pre>
  * public String toString() {
- *   return ReflectionToStringBuilder.toString(this);
- * }</pre>
- *
- *
- *
+ *     return ReflectionToStringBuilder.toString(this);
+ * }
+ * </pre>
  * <p>
  * You can also use the builder to debug 3rd party objects:
  * </p>
- *
  * <pre>
- * System.out.println("An object: " + ReflectionToStringBuilder.toString(anObject));</pre>
- *
- *
- *
+ * System.out.println(&quot;An object: &quot; + ReflectionToStringBuilder.toString(anObject));
+ * </pre>
  * <p>
  * A subclass can control field output by overriding the methods:
  * <ul>
@@ -68,26 +67,21 @@ import org.apache.commons.lang3.ClassUti
  * </ul>
  * </p>
  * <p>
- * For example, this method does <i>not</i> include the <code>password</code> field in the returned
- * <code>String</code>:
+ * For example, this method does <i>not</i> include the <code>password</code> field in the returned <code>String</code>:
  * </p>
- *
  * <pre>
  * public String toString() {
  *     return (new ReflectionToStringBuilder(this) {
  *         protected boolean accept(Field f) {
- *             return super.accept(f) && !f.getName().equals("password");
+ *             return super.accept(f) &amp;&amp; !f.getName().equals(&quot;password&quot;);
  *         }
  *     }).toString();
- * }</pre>
- *
- *
- *
+ * }
+ * </pre>
  * <p>
- * The exact format of the <code>toString</code> is determined by the {@link ToStringStyle} passed into the
- * constructor.
+ * The exact format of the <code>toString</code> is determined by the {@link ToStringStyle} passed into the constructor.
  * </p>
- *
+ * 
  * @since 2.0
  * @version $Id$
  */