From 1d6b5a7594e8db3d86449fa8e8726d5a383293af Mon Sep 17 00:00:00 2001
From: Johannes Dahlström <johannesd@vaadin.com>
Date: Mon, 5 Sep 2016 19:40:31 +0300
Subject: Improve listing and data source Javadocs a bit

Change-Id: Ie3821df9bcb13af5f3955776a11d33fd2c16020e
---
 server/src/main/java/com/vaadin/data/Listing.java  |  5 ++--
 .../java/com/vaadin/server/data/DataSource.java    | 35 +++++++++++++---------
 .../com/vaadin/server/data/ListDataSource.java     | 10 ++++---
 3 files changed, 30 insertions(+), 20 deletions(-)

(limited to 'server')

diff --git a/server/src/main/java/com/vaadin/data/Listing.java b/server/src/main/java/com/vaadin/data/Listing.java
index 8d35a231de..aa410e9dc7 100644
--- a/server/src/main/java/com/vaadin/data/Listing.java
+++ b/server/src/main/java/com/vaadin/data/Listing.java
@@ -26,6 +26,7 @@ import com.vaadin.shared.data.selection.SelectionModel;
  * A generic interface for components that show a list of data.
  *
  * @author Vaadin Ltd.
+ * 
  * @param <T>
  *            the item data type
  * @param <SELECTIONMODEL>
@@ -62,7 +63,7 @@ public interface Listing<T, SELECTIONMODEL extends SelectionModel<T>>
      * Sets the collection of data items of this listing.
      *
      * @param items
-     *            the data items to display
+     *            the data items to display, not null
      *
      */
     default void setItems(Collection<T> items) {
@@ -75,7 +76,7 @@ public interface Listing<T, SELECTIONMODEL extends SelectionModel<T>>
      * @param items
      *            the data items to display
      */
-    default void setItems(T... items) {
+    default void setItems(@SuppressWarnings("unchecked") T... items) {
         setDataSource(DataSource.create(items));
     }
 
diff --git a/server/src/main/java/com/vaadin/server/data/DataSource.java b/server/src/main/java/com/vaadin/server/data/DataSource.java
index ea9c24acbb..a6147bbade 100644
--- a/server/src/main/java/com/vaadin/server/data/DataSource.java
+++ b/server/src/main/java/com/vaadin/server/data/DataSource.java
@@ -25,12 +25,15 @@ import java.util.stream.Stream;
  * Minimal DataSource API for communication between the DataProvider and a back
  * end service.
  *
- * @since
+ * @author Vaadin Ltd.
+ * 
  * @param <T>
  *            data type
  *
  * @see ListDataSource
  * @see BackEndDataSource
+ *
+ * @since
  */
 public interface DataSource<T>
         extends Function<Query, Stream<T>>, Serializable {
@@ -56,26 +59,30 @@ public interface DataSource<T>
      * This method creates a new {@link ListDataSource} from a given Collection.
      * The ListDataSource creates a protective List copy of all the contents in
      * the Collection.
-     *
-     * @param data
-     *            collection of data
-     * @return in-memory data source
+     * 
+     * @param <T>
+     *            the data item type
+     * @param items
+     *            the collection of data, not null
+     * @return a new list data source
      */
-    public static <T> ListDataSource<T> create(Collection<T> data) {
-        return new ListDataSource<>(data);
+    public static <T> ListDataSource<T> create(Collection<T> items) {
+        return new ListDataSource<>(items);
     }
 
     /**
      * This method creates a new {@link ListDataSource} from given objects.The
      * ListDataSource creates a protective List copy of all the contents in the
      * array.
-     *
-     * @param data
-     *            data objects
-     * @return in-memory data source
+     * 
+     * @param <T>
+     *            the data item type
+     * @param items
+     *            the data items
+     * @return a new list data source
      */
     @SafeVarargs
-    public static <T> ListDataSource<T> create(T... data) {
-        return new ListDataSource<>(Arrays.asList(data));
+    public static <T> ListDataSource<T> create(T... items) {
+        return new ListDataSource<>(Arrays.asList(items));
     }
-}
\ No newline at end of file
+}
diff --git a/server/src/main/java/com/vaadin/server/data/ListDataSource.java b/server/src/main/java/com/vaadin/server/data/ListDataSource.java
index 93add67ad4..f3ecc771ec 100644
--- a/server/src/main/java/com/vaadin/server/data/ListDataSource.java
+++ b/server/src/main/java/com/vaadin/server/data/ListDataSource.java
@@ -19,6 +19,7 @@ import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Comparator;
 import java.util.List;
+import java.util.Objects;
 import java.util.function.Function;
 import java.util.stream.Stream;
 
@@ -38,11 +39,12 @@ public class ListDataSource<T> implements DataSource<T> {
      * Constructs a new ListDataSource. This method makes a protective copy of
      * the contents of the Collection.
      *
-     * @param collection
-     *            initial data
+     * @param items
+     *            the initial data, not null
      */
-    public ListDataSource(Collection<T> collection) {
-        final List<T> backend = new ArrayList<>(collection);
+    public ListDataSource(Collection<T> items) {
+        Objects.requireNonNull(items, "items cannot be null");
+        final List<T> backend = new ArrayList<>(items);
         request = query -> backend.stream();
         size = backend.size();
     }
-- 
cgit v1.2.3