Author: oheger
Date: Fri May 10 19:13:13 2013
New Revision: 1481148
URL: http://svn.apache.org/r1481148
Log:
Improved Javadocs related to thread-safety.
Modified:
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/BaseHierarchicalConfiguration.java
Modified:
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/BaseHierarchicalConfiguration.java
URL:
http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/BaseHierarchicalConfiguration.java?rev=1481148&r1=1481147&r2=1481148&view=diff
==============================================================================
---
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/BaseHierarchicalConfiguration.java
(original)
+++
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/BaseHierarchicalConfiguration.java
Fri May 10 19:13:13 2013
@@ -117,9 +117,24 @@ import org.apache.commons.configuration.
* that was created from this configuration has been changed. The value
property
* of the event object contains the original event object as it was sent by the
* subnode configuration.</dd></dl></p>
- * <p><em>Note:</em>Configuration objects of this type can be read concurrently
- * by multiple threads. However if one of these threads modifies the object,
- * synchronization has to be performed manually.</p>
+ * <p>
+ * Whether a {@code BaseHierarchicalConfiguration} object is thread-safe or not
+ * depends on the {@link Synchronizer} it is associated with. (Per default, a
+ * dummy {@code Synchronizer} is used which is not thread-safe!) The methods
+ * for querying or updating configuration data invoke this {@code Synchronizer}
+ * accordingly. There is one exception to this rule: The {@link #getRootNode()}
+ * method is not guarded using the {@code Synchronizer}. This is due to the
+ * fact that the caller can do anything with this root node, so it is not
+ * clear which kind of synchronization should be performed. So when accessing
+ * the configuration's root node directly, the client application is
responsible
+ * for proper synchronization. This is achieved by calling the methods
+ * {@link #lock(LockMode)}, and {@link #unlock(LockMode)} with a proper
+ * {@link LockMode} argument. In any case, it is recommended to not access the
+ * root node directly, but to use corresponding methods for querying or
+ * updating configuration data instead. Direct manipulations of a
+ * configuration's node structure circumvent many internal mechanisms and thus
+ * can cause undesired effects.
+ * </p>
*
* @version $Id$
*/
