Improve JavaDocs for DataSources and DataChangeHandler

This patch also splits DataChangeHandler away from the DataSource
interface, making it easier for IDEs to find.

Change-Id: I6030dec81870e290abd87bf91c834bc01a870f77

6 files changed, 97 insertions, 52 deletions

diff --git a/server/src/com/vaadin/server/communication/data/typed/AbstractDataSource.java b/server/src/com/vaadin/server/communication/data/typed/AbstractDataSource.java
index 98f68ed536..6e45b9647a 100644
--- a/server/src/com/vaadin/server/communication/data/typed/AbstractDataSource.java
+++ b/server/src/com/vaadin/server/communication/data/typed/AbstractDataSource.java
@@ -40,24 +40,56 @@ public abstract class AbstractDataSource<T> implements DataSource<T> {
         handlers.remove(handler);
     }
 
+    /**
+     * Informs all handlers of a generic change in the data. This usually
+     * triggers a full cache invalidation and refresh of all data, which is
+     * usually an expensive operation. Should be called when none of the other
+     * methods help.
+     * 
+     * @see #fireDataAppend(Object)
+     * @see #fireDataRemove(Object)
+     * @see #fireDataUpdate(Object)
+     */
     protected void fireDataChange() {
         for (DataChangeHandler<T> handler : handlers) {
             handler.onDataChange();
         }
     }
 
-    protected void fireDataAdd(T data) {
+    /**
+     * Informs all handlers of an added data object in the back end. This method
+     * should only be called when the newly added data object is the last object
+     * in the back end. Other additions can be handled with
+     * {@link #fireDataChange()}.
+     * 
+     * @param data
+     *            added data object
+     */
+    protected void fireDataAppend(T data) {
         for (DataChangeHandler<T> handler : handlers) {
-            handler.onDataAdd(data);
+            handler.onDataAppend(data);
         }
     }
 
+    /**
+     * Informs all handlers of a data object that was removed from the back end.
+     * 
+     * @param data
+     *            removed data object
+     */
     protected void fireDataRemove(T data) {
         for (DataChangeHandler<T> handler : handlers) {
             handler.onDataRemove(data);
         }
     }
 
+    /**
+     * Informs all handlers of an existing data object that was updated in the
+     * back end.
+     * 
+     * @param data
+     *            updated data object
+     */
     protected void fireDataUpdate(T data) {
         for (DataChangeHandler<T> handler : handlers) {
             handler.onDataUpdate(data);
diff --git a/server/src/com/vaadin/server/communication/data/typed/CollectionDataSource.java b/server/src/com/vaadin/server/communication/data/typed/CollectionDataSource.java
index 4a8d14f29e..1815c3e152 100644
--- a/server/src/com/vaadin/server/communication/data/typed/CollectionDataSource.java
+++ b/server/src/com/vaadin/server/communication/data/typed/CollectionDataSource.java
@@ -45,7 +45,7 @@ public class CollectionDataSource<T> extends AbstractDataSource<T> {
             fireDataUpdate(data);
         } else {
             backend.add(data);
-            fireDataAdd(data);
+            fireDataAppend(data);
         }
     }
 
diff --git a/server/src/com/vaadin/server/communication/data/typed/DataChangeHandler.java b/server/src/com/vaadin/server/communication/data/typed/DataChangeHandler.java
new file mode 100644
index 0000000000..d2cf574c4a
--- /dev/null
+++ b/server/src/com/vaadin/server/communication/data/typed/DataChangeHandler.java
@@ -0,0 +1,61 @@
+/*
+ * Copyright 2000-2014 Vaadin Ltd.
+ * 
+ * Licensed 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 com.vaadin.server.communication.data.typed;
+
+import java.io.Serializable;
+
+/**
+ * Interface for a {@link DataSource} to inform of various changes in the back
+ * end.
+ * 
+ * @param <T>
+ *            data type
+ */
+public interface DataChangeHandler<T> extends Serializable {
+
+    /**
+     * This method is called when a generic change in the DataSource. All cached
+     * data should be considered invalid.
+     */
+    void onDataChange();
+
+    /**
+     * This method is called when a data object has been added as the last
+     * object in the back end.
+     * 
+     * @param data
+     *            new data object
+     */
+    void onDataAppend(T data);
+
+    /**
+     * This method is called when a data object has been removed from the back
+     * end.
+     * 
+     * @param data
+     *            removed data object
+     */
+    void onDataRemove(T data);
+
+    /**
+     * This method is called when an existing data object has been updated in
+     * the back end.
+     * 
+     * @param data
+     *            updated data object
+     */
+    void onDataUpdate(T data);
+}
\ No newline at end of file
diff --git a/server/src/com/vaadin/server/communication/data/typed/DataProvider.java b/server/src/com/vaadin/server/communication/data/typed/DataProvider.java
index 320c1b60b7..8f5dd61725 100644
--- a/server/src/com/vaadin/server/communication/data/typed/DataProvider.java
+++ b/server/src/com/vaadin/server/communication/data/typed/DataProvider.java
@@ -23,7 +23,6 @@ import java.util.Set;
 
 import com.vaadin.server.AbstractExtension;
 import com.vaadin.server.ClientConnector;
-import com.vaadin.server.communication.data.typed.DataSource.DataChangeHandler;
 import com.vaadin.shared.data.DataProviderClientRpc;
 import com.vaadin.shared.data.DataProviderConstants;
 import com.vaadin.shared.data.DataRequestRpc;
diff --git a/server/src/com/vaadin/server/communication/data/typed/DataSource.java b/server/src/com/vaadin/server/communication/data/typed/DataSource.java
index 69eccb8686..01904fca3c 100644
--- a/server/src/com/vaadin/server/communication/data/typed/DataSource.java
+++ b/server/src/com/vaadin/server/communication/data/typed/DataSource.java
@@ -61,50 +61,4 @@ public interface DataSource<T> extends Iterable<T>, Serializable {
      */
     void removeDataChangeHandler(DataChangeHandler<T> handler);
 
-    /**
-     * Interface for DataSources to inform of various changes in the back end to
-     * anyone interested.
-     * 
-     * @param <T>
-     *            data type
-     */
-    interface DataChangeHandler<T> extends Serializable {
-
-        /**
-         * This method is called when a generic change in the DataSource. All
-         * cached data should be considered invalid.
-         * <p>
-         * <strong>Note: </strong> This method usually does an expensive full
-         * refresh of everything. Even though it makes everything up to date,
-         * you should only use this when really needed.
-         */
-        void onDataChange();
-
-        /**
-         * This method is called when a data object has been added as the last
-         * object in the back end.
-         * 
-         * @param data
-         *            new data object
-         */
-        void onDataAdd(T data);
-
-        /**
-         * This method is called when a data object has been removed from the
-         * back end.
-         * 
-         * @param data
-         *            removed data object
-         */
-        void onDataRemove(T data);
-
-        /**
-         * This method is called when a data object has been updated in the back
-         * end.
-         * 
-         * @param data
-         *            updated data object
-         */
-        void onDataUpdate(T data);
-    }
 }
diff --git a/server/src/com/vaadin/server/communication/data/typed/SimpleDataProvider.java b/server/src/com/vaadin/server/communication/data/typed/SimpleDataProvider.java
index 2d40730530..fbfb438d85 100644
--- a/server/src/com/vaadin/server/communication/data/typed/SimpleDataProvider.java
+++ b/server/src/com/vaadin/server/communication/data/typed/SimpleDataProvider.java
@@ -19,7 +19,6 @@ import java.util.Collections;
 import java.util.HashSet;
 import java.util.Set;
 
-import com.vaadin.server.communication.data.typed.DataSource.DataChangeHandler;
 import com.vaadin.shared.data.DataProviderClientRpc;
 import com.vaadin.shared.data.DataRequestRpc;
 
@@ -172,7 +171,7 @@ public class SimpleDataProvider<T> extends DataProvider<T> {
             }
 
             @Override
-            public void onDataAdd(T data) {
+            public void onDataAppend(T data) {
                 add(data);
             }