From: Henri Sara <hesara@vaadin.com>
Date: Thu, 22 Dec 2011 09:08:26 +0000 (+0200)
Subject: Add javadoc to Property.Transactional and TransactionalPropertyWrapper.
X-Git-Tag: 7.0.0.alpha1~28
X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=bf94e8c41705d1ff5e71f8a757e7a1789bf40aa0;p=vaadin-framework.git

Add javadoc to Property.Transactional and TransactionalPropertyWrapper.
---

diff --git a/src/com/vaadin/data/Property.java b/src/com/vaadin/data/Property.java
index f25030f996..9fab642381 100644
--- a/src/com/vaadin/data/Property.java
+++ b/src/com/vaadin/data/Property.java
@@ -105,6 +105,11 @@ public interface Property<T> extends Serializable {
      * A Property that is capable of handle a transaction that can end in commit
      * or rollback.
      * 
+     * Note that this does not refer to e.g. database transactions but rather
+     * two-phase commit that allows resetting old field values on a form etc. if
+     * the commit of one of the properties fails after others have already been
+     * committed. If
+     * 
      * @param <T>
      *            The type of the property
      * @author Vaadin Ltd
diff --git a/src/com/vaadin/data/util/TransactionalPropertyWrapper.java b/src/com/vaadin/data/util/TransactionalPropertyWrapper.java
index 8e475758bf..de44dbe544 100644
--- a/src/com/vaadin/data/util/TransactionalPropertyWrapper.java
+++ b/src/com/vaadin/data/util/TransactionalPropertyWrapper.java
@@ -7,6 +7,29 @@ import com.vaadin.data.Property;
 import com.vaadin.data.Property.ValueChangeEvent;
 import com.vaadin.data.Property.ValueChangeNotifier;
 
+/**
+ * Wrapper class that helps implement two-phase commit for a non-transactional
+ * property.
+ * 
+ * When accessing the property through the wrapper, getting and setting the
+ * property value take place immediately. However, the wrapper keeps track of
+ * the old value of the property so that it can be set for the property in case
+ * of a roll-back. This can result in the underlying property value changing
+ * multiple times (first based on modifications made by the application, then
+ * back upon roll-back).
+ * 
+ * Value change events on the {@link TransactionalPropertyWrapper} are only
+ * fired at the end of a successful transaction, whereas listeners attached to
+ * the underlying property may receive multiple value change events.
+ * 
+ * @see com.vaadin.data.Property.Transactional
+ * 
+ * @author Vaadin Ltd
+ * @version @version@
+ * @since 7.0
+ * 
+ * @param <T>
+ */
 public class TransactionalPropertyWrapper<T> extends AbstractProperty<T>
         implements ValueChangeNotifier, Property.Transactional<T> {