From 46a9bc1c4ae2ecd472dfe8c8bb7e676ddc6372bd Mon Sep 17 00:00:00 2001 From: Henri Sara Date: Tue, 26 Apr 2011 08:49:52 +0000 Subject: [PATCH] #4659 Container javadoc improvements based on review. svn changeset:18444/svn branch:6.6 --- src/com/vaadin/data/Container.java | 51 ++++++++++++++++++------------ 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/src/com/vaadin/data/Container.java b/src/com/vaadin/data/Container.java index 84cf866f06..4c2d969c83 100644 --- a/src/com/vaadin/data/Container.java +++ b/src/com/vaadin/data/Container.java @@ -86,8 +86,8 @@ public interface Container extends Serializable { public Item getItem(Object itemId); /** - * Gets the ID's of all Properties stored in the Container. The ID's are - * returned as a unmodifiable collection. + * Gets the ID's of all Properties stored in the Container. The ID's cannot + * be modified through the returned collection. * * @return unmodifiable collection of Property IDs */ @@ -95,7 +95,8 @@ public interface Container extends Serializable { /** * Gets the ID's of all visible (after filtering and sorting) Items stored - * in the Container. The ID's are returned as a unmodifiable collection. + * in the Container. The ID's cannot be modified through the returned + * collection. * * If the container is {@link Ordered}, the collection returned by this * method should follow that order. If the container is {@link Sortable}, @@ -279,9 +280,14 @@ public interface Container extends Serializable { * *

* If the container is filtered or sorted, the traversal applies to the - * filtered and sorted view. The addItemAfter() methods may add - * items that will be filtered out after addition or moved to another - * position based on sorting. + * filtered and sorted view. + *

+ *

+ * The addItemAfter() methods should apply filters to the added + * item after inserting it, possibly hiding it immediately. If the container + * is being sorted, they may add items at the correct sorted position + * instead of the given position. See also {@link Filterable} and + * {@link Sortable} for more information. *

*/ public interface Ordered extends Container { @@ -343,7 +349,7 @@ public interface Container extends Serializable { public boolean isLastId(Object itemId); /** - * Adds new item after the given item. + * Adds a new item after the given item. *

* Adding an item after null item adds the item as first item of the * ordered container. @@ -363,7 +369,7 @@ public interface Container extends Serializable { throws UnsupportedOperationException; /** - * Adds new item after the given item. + * Adds a new item after the given item. *

* Adding an item after null item adds the item as first item of the * ordered container. @@ -402,6 +408,10 @@ public interface Container extends Serializable { * the implementing class. However, the recommended approach is sorting the * roots and the sets of children of each item separately. *

+ *

+ * Depending on the container type, sorting a container may permanently + * change the internal order of items in the container. + *

*/ public interface Sortable extends Ordered { @@ -410,7 +420,8 @@ public interface Container extends Serializable { * * Sorts the container items. * - * Container sorting can completely replace the previous order. + * Sorting a container can irreversibly change the order of its items or + * only change the order temporarily, depending on the container. * * @param propertyId * Array of container property IDs, whose values are used to @@ -473,16 +484,16 @@ public interface Container extends Serializable { public Object getIdByIndex(int index); /** - * Adds new item at given index. + * Adds a new item at given index (in the filtered view). *

* The indices of the item currently in the given position and all the * following items are incremented. *

*

- * If the container is sorted, the item may be inserted in its correct - * sorted location instead of the given position. If the container is - * filtered, the item may be filtered out after being added after the - * visible item identified by the index. See {@link Indexed}, + * This method should apply filters to the added item after inserting + * it, possibly hiding it immediately. If the container is being sorted, + * the item may be added at the correct sorted position instead of the + * given position. See {@link Indexed}, {@link Ordered}, * {@link Filterable} and {@link Sortable} for more information. *

* @@ -496,17 +507,17 @@ public interface Container extends Serializable { public Object addItemAt(int index) throws UnsupportedOperationException; /** - * Adds new item at given index. + * Adds a new item at given index (in the filtered view). *

* The indexes of the item currently in the given position and all the * following items are incremented. *

*

- * If the container is sorted, the item may be inserted in its correct - * sorted location instead of the given position. If the container is - * filtered, the item may be filtered out after being added after the - * visible item identified by the index. See {@link Indexed}, - * {@link Filterable} and {@link Sortable} for more information. + * This method should apply filters to the added item after inserting + * it, possibly hiding it immediately. If the container is being sorted, + * the item may be added at the correct sorted position instead of the + * given position. See {@link Indexed}, {@link Filterable} and + * {@link Sortable} for more information. *

* * @param index -- 2.39.5