/*
* Copyright 2000-2016 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.v7.data;
import java.io.Serializable;
import java.util.Collection;
import java.util.List;
import com.vaadin.data.provider.AbstractBackEndDataProvider;
import com.vaadin.data.provider.DataProvider;
import com.vaadin.data.provider.ListDataProvider;
import com.vaadin.data.provider.Query;
import com.vaadin.server.SerializableComparator;
import com.vaadin.v7.data.util.filter.SimpleStringFilter;
import com.vaadin.v7.data.util.filter.UnsupportedFilterException;
/**
* <p>
* A specialized set of identified Items. Basically the Container is a set of
* {@link Item}s, but it imposes certain constraints on its contents. These
* constraints state the following:
* </p>
*
* <ul>
* <li>All Items in the Container must have the same number of Properties.
* <li>All Items in the Container must have the same Property ID's (see
* {@link Item#getItemPropertyIds()}).
* <li>All Properties in the Items corresponding to the same Property ID must
* have the same data type.
* <li>All Items within a container are uniquely identified by their non-null
* IDs.
* </ul>
*
* <p>
* The Container can be visualized as a representation of a relational database
* table. Each Item in the Container represents a row in the table, and all
* cells in a column (identified by a Property ID) have the same data type. Note
* that as with the cells in a database table, no Property in a Container may be
* empty, though they may contain <code>null</code> values.
* </p>
*
* <p>
* Note that though uniquely identified, the Items in a Container are not
* necessarily {@link Container.Ordered ordered} or {@link Container.Indexed
* indexed}.
* </p>
*
* <p>
* Containers can derive Item ID's from the item properties or use other,
* container specific or user specified identifiers.
* </p>
*
* <p>
* If a container is {@link Filterable filtered} or {@link Sortable sorted},
* most of the the methods of the container interface and its subinterfaces
* (container size, {@link #containsId(Object)}, iteration and indices etc.)
* relate to the filtered and sorted view, not to the full container contents.
* See individual method javadoc for exceptions to this (adding and removing
* items).
* </p>
*
* <p>
* <img src=doc-files/Container_full.gif>
* </p>
*
* <p>
* The Container interface is split to several subinterfaces so that a class can
* implement only the ones it needs.
* </p>
*
* @author Vaadin Ltd
* @since 3.0
*
* @deprecated As of 8.0, replaced by {@link DataProvider}
*/
@Deprecated
public interface Container extends Serializable {
/**
* Gets the {@link Item} with the given Item ID from the Container. If the
* Container does not contain the requested Item, <code>null</code> is
* returned.
* <p>
* Containers should not return Items that are filtered out.
*
* @param itemId
* ID of the {@link Item} to retrieve
* @return the {@link Item} with the given ID or <code>null</code> if the
* Item is not found in the Container
*/
public Item getItem(Object itemId);
/**
* 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
*/
public Collection<?> getContainerPropertyIds();
/**
* Gets the ID's of all visible (after filtering and sorting) Items stored
* in the Container. The ID's cannot be modified through the returned
* collection.
* <p>
* If the container is {@link Ordered}, the collection returned by this
* method should follow that order. If the container is {@link Sortable},
* the items should be in the sorted order.
* <p>
* Calling this method for large lazy containers can be an expensive
* operation and should be avoided when practical.
*
* @return unmodifiable collection of Item IDs
*/
public Collection<?> getItemIds();
/**
* Gets the Property identified by the given itemId and propertyId from the
* Container. If the Container does not contain the item or it is filtered
* out, or the Container does not have the Property, <code>null</code> is
* returned.
*
* @param itemId
* ID of the visible Item which contains the Property
* @param propertyId
* ID of the Property to retrieve
* @return Property with the given ID or <code>null</code>
*/
public Property getContainerProperty(Object itemId, Object propertyId);
/**
* Gets the data type of all Properties identified by the given Property ID.
*
* @param propertyId
* ID identifying the Properties
* @return data type of the Properties
*/
public Class<?> getType(Object propertyId);
/**
* Gets the number of visible Items in the Container.
* <p>
* Filtering can hide items so that they will not be visible through the
* container API.
*
* @return number of Items in the Container
*/
public int size();
/**
* Tests if the Container contains the specified Item.
* <p>
* Filtering can hide items so that they will not be visible through the
* container API, and this method should respect visibility of items (i.e.
* only indicate visible items as being in the container) if feasible for
* the container.
*
* @param itemId
* ID the of Item to be tested
* @return boolean indicating if the Container holds the specified Item
*/
public boolean containsId(Object itemId);
/**
* Creates a new Item with the given ID in the Container.
*
* <p>
* The new Item is returned, and it is ready to have its Properties
* modified. Returns <code>null</code> if the operation fails or the
* Container already contains a Item with the given ID.
* </p>
*
* <p>
* This functionality is optional.
* </p>
*
* @param itemId
* ID of the Item to be created
* @return Created new Item, or <code>null</code> in case of a failure
* @throws UnsupportedOperationException
* if adding an item with an explicit item ID is not supported
* by the container
*/
public Item addItem(Object itemId) throws UnsupportedOperationException;
/**
* Creates a new Item into the Container, and assign it an automatic ID.
*
* <p>
* The new ID is returned, or <code>null</code> if the operation fails.
* After a successful call you can use the {@link #getItem(Object ItemId)
* <code>getItem</code>}method to fetch the Item.
* </p>
*
* <p>
* This functionality is optional.
* </p>
*
* @return ID of the newly created Item, or <code>null</code> in case of a
* failure
* @throws UnsupportedOperationException
* if adding an item without an explicit item ID is not
* supported by the container
*/
public Object addItem() throws UnsupportedOperationException;
/**
* Removes the Item identified by <code>ItemId</code> from the Container.
*
* <p>
* Containers that support filtering should also allow removing an item that
* is currently filtered out.
* </p>
*
* <p>
* This functionality is optional.
* </p>
*
* @param itemId
* ID of the Item to remove
* @return <code>true</code> if the operation succeeded, <code>false</code>
* if not
* @throws UnsupportedOperationException
* if the container does not support removing individual items
*/
public boolean removeItem(Object itemId)
throws UnsupportedOperationException;
/**
* Adds a new Property to all Items in the Container. The Property ID, data
* type and default value of the new Property are given as parameters.
* <p>
* This functionality is optional.
*
* @param propertyId
* ID of the Property
* @param type
* Data type of the new Property
* @param defaultValue
* The value all created Properties are initialized to
* @return <code>true</code> if the operation succeeded, <code>false</code>
* if not
* @throws UnsupportedOperationException
* if the container does not support explicitly adding container
* properties
*/
public boolean addContainerProperty(Object propertyId, Class<?> type,
Object defaultValue) throws UnsupportedOperationException;
/**
* Removes a Property specified by the given Property ID from the Container.
* Note that the Property will be removed from all Items in the Container.
* <p>
* This functionality is optional.
*
* @param propertyId
* ID of the Property to remove
* @return <code>true</code> if the operation succeeded, <code>false</code>
* if not
* @throws UnsupportedOperationException
* if the container does not support removing container
* properties
*/
public boolean removeContainerProperty(Object propertyId)
throws UnsupportedOperationException;
/**
* Removes all Items from the Container.
*
* <p>
* Note that Property ID and type information is preserved. This
* functionality is optional.
* </p>
*
* @return <code>true</code> if the operation succeeded, <code>false</code>
* if not
* @throws UnsupportedOperationException
* if the container does not support removing all items
*/
public boolean removeAllItems() throws UnsupportedOperationException;
/**
* Interface for Container classes whose {@link Item}s can be traversed in
* order.
*
* <p>
* If the container is filtered or sorted, the traversal applies to the
* filtered and sorted view.
* </p>
* <p>
* The <code>addItemAfter()</code> 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.
* </p>
*/
@Deprecated
public interface Ordered extends Container {
/**
* Gets the ID of the Item following the Item that corresponds to
* <code>itemId</code>. If the given Item is the last or not found in
* the Container, <code>null</code> is returned.
*
* @param itemId
* ID of a visible Item in the Container
* @return ID of the next visible Item or <code>null</code>
*/
public Object nextItemId(Object itemId);
/**
* Gets the ID of the Item preceding the Item that corresponds to
* <code>itemId</code>. If the given Item is the first or not found in
* the Container, <code>null</code> is returned.
*
* @param itemId
* ID of a visible Item in the Container
* @return ID of the previous visible Item or <code>null</code>
*/
public Object prevItemId(Object itemId);
/**
* Gets the ID of the first Item in the Container.
*
* @return ID of the first visible Item in the Container
*/
public Object firstItemId();
/**
* Gets the ID of the last Item in the Container..
*
* @return ID of the last visible Item in the Container
*/
public Object lastItemId();
/**
* Tests if the Item corresponding to the given Item ID is the first
* Item in the Container.
*
* @param itemId
* ID of an Item in the Container
* @return <code>true</code> if the Item is first visible item in the
* Container, <code>false</code> if not
*/
public boolean isFirstId(Object itemId);
/**
* Tests if the Item corresponding to the given Item ID is the last Item
* in the Container.
*
* @return <code>true</code> if the Item is last visible item in the
* Container, <code>false</code> if not
*/
public boolean isLastId(Object itemId);
/**
* Adds a new item after the given item.
* <p>
* Adding an item after null item adds the item as first item of the
* ordered container.
* </p>
*
* @see Ordered Ordered: adding items in filtered or sorted containers
*
* @param previousItemId
* Id of the visible item in ordered container after which to
* insert the new item.
* @return item id the the created new item or null if the operation
* fails.
* @throws UnsupportedOperationException
* if the operation is not supported by the container
*/
public Object addItemAfter(Object previousItemId)
throws UnsupportedOperationException;
/**
* Adds a new item after the given item.
* <p>
* Adding an item after null item adds the item as first item of the
* ordered container.
* </p>
*
* @see Ordered Ordered: adding items in filtered or sorted containers
*
* @param previousItemId
* Id of the visible item in ordered container after which to
* insert the new item.
* @param newItemId
* Id of the new item to be added.
* @return new item or null if the operation fails.
* @throws UnsupportedOperationException
* if the operation is not supported by the container
*/
public Item addItemAfter(Object previousItemId, Object newItemId)
throws UnsupportedOperationException;
}
/**
* Interface for Container classes whose {@link Item}s can be sorted.
* <p>
* When an {@link Ordered} or {@link Indexed} container is sorted, all
* relevant operations of these interfaces should only use the filtered and
* sorted contents and the filtered indices to the container. Indices or
* item identifiers in the public API refer to the visible view unless
* otherwise stated. However, the <code>addItem*()</code> methods may add
* items that will be filtered out after addition or moved to another
* position based on sorting.
* </p>
* <p>
* How sorting is performed when a {@link Hierarchical} container implements
* {@link Sortable} is implementation specific and should be documented in
* the implementing class. However, the recommended approach is sorting the
* roots and the sets of children of each item separately.
* </p>
* <p>
* Depending on the container type, sorting a container may permanently
* change the internal order of items in the container.
* </p>
*
* @deprecated As of 8.0, sorting is integrated into {@link DataProvider} and {@link Query#getSortOrders()}.
* For in-memory case, you can use also {@link ListDataProvider#setSortComparator(SerializableComparator)}.
* For back-end DataProviders, see {@link AbstractBackEndDataProvider#setSortOrders(List)}.
*/
@Deprecated
public interface Sortable extends Ordered {
/**
* Sorts the container items.
* <p>
* 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
* sort the items in container as primary, secondary, ...
* sorting criterion. All of the item IDs must be in the
* collection returned by
* {@link #getSortableContainerPropertyIds()}
* @param ascending
* Array of sorting order flags corresponding to each
* property ID used in sorting. If this array is shorter than
* propertyId array, ascending order is assumed for items
* where the order is not specified. Use <code>true</code> to
* sort in ascending order, <code>false</code> to use
* descending order.
*/
void sort(Object[] propertyId, boolean[] ascending);
/**
* Gets the container property IDs which can be used to sort the items.
*
* @return the IDs of the properties that can be used for sorting the
* container
*/
Collection<?> getSortableContainerPropertyIds();
}
/**
* Interface for Container classes whose {@link Item}s can be accessed by
* their position in the container.
* <p>
* If the container is filtered or sorted, all indices refer to the filtered
* and sorted view. However, the <code>addItemAt()</code> methods may add
* items that will be filtered out after addition or moved to another
* position based on sorting.
* </p>
*/
@Deprecated
public interface Indexed extends Ordered {
/**
* Gets the index of the Item corresponding to the itemId. The following
* is <code>true</code> for the returned index: 0 <= index < size(), or
* index = -1 if there is no visible item with that id in the container.
*
* @param itemId
* ID of an Item in the Container
* @return index of the Item, or -1 if (the filtered and sorted view of)
* the Container does not include the Item
*/
public int indexOfId(Object itemId);
/**
* Get the item id for the item at the position given by
* <code>index</code>.
* <p>
*
* @param index
* the index of the requested item id
* @return the item id of the item at the given index
* @throws IndexOutOfBoundsException
* if <code>index</code> is outside the range of the
* container. (i.e.
* <code>index < 0 || container.size()-1 < index</code>
* )
*/
public Object getIdByIndex(int index);
/**
* Get <code>numberOfItems</code> consecutive item ids from the
* container, starting with the item id at <code>startIndex</code>.
* <p>
* Implementations should return at most <code>numberOfItems</code> item
* ids, but can contain less if the container has less items than
* required to fulfill the request. The returned list must hence contain
* all of the item ids from the range:
* <p>
* <code>startIndex</code> to
* <code>max(startIndex + (numberOfItems-1), container.size()-1)</code>.
* <p>
* For quick migration to new API see:
* {@link ContainerHelpers#getItemIdsUsingGetIdByIndex(int, int, Indexed)}
*
* @param startIndex
* the index for the first item which id to include
* @param numberOfItems
* the number of consecutive item ids to get from the given
* start index, must be >= 0
* @return List containing the requested item ids or empty list if
* <code>numberOfItems</code> == 0; not null
*
* @throws IllegalArgumentException
* if <code>numberOfItems</code> is < 0
* @throws IndexOutOfBoundsException
* if <code>startIndex</code> is outside the range of the
* container. (i.e.
* <code>startIndex < 0 || container.size()-1 < startIndex</code>
* )
*
* @since 7.0
*/
public List<?> getItemIds(int startIndex, int numberOfItems);
/**
* Adds a new item at given index (in the filtered view).
* <p>
* The indices of the item currently in the given position and all the
* following items are incremented.
* </p>
* <p>
* 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.
* </p>
*
* @param index
* Index (in the filtered and sorted view) to add the new
* item.
* @return item id of the created item or null if the operation fails.
* @throws UnsupportedOperationException
* if the operation is not supported by the container
*/
public Object addItemAt(int index) throws UnsupportedOperationException;
/**
* Adds a new item at given index (in the filtered view).
* <p>
* The indexes of the item currently in the given position and all the
* following items are incremented.
* </p>
* <p>
* 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.
* </p>
*
* @param index
* Index (in the filtered and sorted view) at which to add
* the new item.
* @param newItemId
* Id of the new item to be added.
* @return new {@link Item} or null if the operation fails.
* @throws UnsupportedOperationException
* if the operation is not supported by the container
*/
public Item addItemAt(int index, Object newItemId)
throws UnsupportedOperationException;
/**
* An <code>Event</code> object specifying information about the added
* items.
*
* @since 7.4
*/
@Deprecated
public interface ItemAddEvent extends ItemSetChangeEvent {
/**
* Gets the item id of the first added item.
*
* @return item id of the first added item
*/
public Object getFirstItemId();
/**
* Gets the index of the first added item.
*
* @return index of the first added item
*/
public int getFirstIndex();
/**
* Gets the number of the added items.
*
* @return the number of added items.
*/
public int getAddedItemsCount();
}
/**
* An <code>Event</code> object specifying information about the removed
* items.
*
* @since 7.4
*/
@Deprecated
public interface ItemRemoveEvent extends ItemSetChangeEvent {
/**
* Gets the item id of the first removed item.
*
* @return item id of the first removed item
*/
public Object getFirstItemId();
/**
* Gets the index of the first removed item.
*
* @return index of the first removed item
*/
public int getFirstIndex();
/**
* Gets the number of the removed items.
*
* @return the number of removed items
*/
public int getRemovedItemsCount();
}
}
/**
* <p>
* Interface for <code>Container</code> classes whose Items can be arranged
* hierarchically. This means that the Items in the container belong in a
* tree-like structure, with the following quirks:
* </p>
*
* <ul>
* <li>The Item structure may have more than one root elements
* <li>The Items in the hierarchy can be declared explicitly to be able or
* unable to have children.
* </ul>
*
* @deprecated As of 8.0, no replacement available yet. A new hierarchical data API is planned in an upcoming
* version of Vaadin Framework 8.
*/
@Deprecated
public interface Hierarchical extends Container {
/**
* Gets the IDs of all Items that are children of the specified Item.
* The returned collection is unmodifiable.
*
* @param itemId
* ID of the Item whose children the caller is interested in
* @return An unmodifiable {@link java.util.Collection collection}
* containing the IDs of all other Items that are children in
* the container hierarchy; {@code null} if item does not have
* any children.
*/
public Collection<?> getChildren(Object itemId);
/**
* Gets the ID of the parent Item of the specified Item.
*
* @param itemId
* ID of the Item whose parent the caller wishes to find out.
* @return the ID of the parent Item. Will be <code>null</code> if the
* specified Item is a root element.
*/
public Object getParent(Object itemId);
/**
* Gets the IDs of all Items in the container that don't have a parent.
* Such items are called <code>root</code> Items. The returned
* collection is unmodifiable.
*
* @return An unmodifiable {@link java.util.Collection collection}
* containing IDs of all root elements of the container
*/
public Collection<?> rootItemIds();
/**
* <p>
* Sets the parent of an Item. The new parent item must exist and be
* able to have children. (
* <code>{@link #areChildrenAllowed(Object)} == true</code> ). It is
* also possible to detach a node from the hierarchy (and thus make it
* root) by setting the parent <code>null</code>.
* </p>
*
* <p>
* This operation is optional.
* </p>
*
* @param itemId
* ID of the item to be set as the child of the Item
* identified with <code>newParentId</code>
* @param newParentId
* ID of the Item that's to be the new parent of the Item
* identified with <code>itemId</code>
* @return <code>true</code> if the operation succeeded,
* <code>false</code> if not
*/
public boolean setParent(Object itemId, Object newParentId)
throws UnsupportedOperationException;
/**
* Tests if the Item with given ID can have children.
*
* @param itemId
* ID of the Item in the container whose child capability is
* to be tested
* @return <code>true</code> if the specified Item exists in the
* Container and it can have children, <code>false</code> if
* it's not found from the container or it can't have children.
*/
public boolean areChildrenAllowed(Object itemId);
/**
* <p>
* Sets the given Item's capability to have children. If the Item
* identified with <code>itemId</code> already has children and
* <code>{@link #areChildrenAllowed(Object)}</code> is false this method
* fails and <code>false</code> is returned.
* </p>
* <p>
* The children must be first explicitly removed with
* {@link #setParent(Object itemId, Object newParentId)}or
* {@link Container#removeItem(Object itemId)}.
* </p>
*
* <p>
* This operation is optional. If it is not implemented, the method
* always returns <code>false</code>.
* </p>
*
* @param itemId
* ID of the Item in the container whose child capability is
* to be set
* @param areChildrenAllowed
* boolean value specifying if the Item can have children or
* not
* @return <code>true</code> if the operation succeeded,
* <code>false</code> if not
*/
public boolean setChildrenAllowed(Object itemId,
boolean areChildrenAllowed)
throws UnsupportedOperationException;
/**
* Tests if the Item specified with <code>itemId</code> is a root Item.
* The hierarchical container can have more than one root and must have
* at least one unless it is empty. The
* {@link #getParent(Object itemId)} method always returns
* <code>null</code> for root Items.
*
* @param itemId
* ID of the Item whose root status is to be tested
* @return <code>true</code> if the specified Item is a root,
* <code>false</code> if not
*/
public boolean isRoot(Object itemId);
/**
* <p>
* Tests if the Item specified with <code>itemId</code> has child Items
* or if it is a leaf. The {@link #getChildren(Object itemId)} method
* always returns <code>null</code> for leaf Items.
* </p>
*
* <p>
* Note that being a leaf does not imply whether or not an Item is
* allowed to have children.
* </p>
*
* @param itemId
* ID of the Item to be tested
* @return <code>true</code> if the specified Item has children,
* <code>false</code> if not (is a leaf)
*/
public boolean hasChildren(Object itemId);
/**
* <p>
* Removes the Item identified by <code>ItemId</code> from the
* Container.
* </p>
*
* <p>
* Note that this does not remove any children the item might have.
* </p>
*
* @param itemId
* ID of the Item to remove
* @return <code>true</code> if the operation succeeded,
* <code>false</code> if not
*/
@Override
public boolean removeItem(Object itemId)
throws UnsupportedOperationException;
}
/**
* Interface that is implemented by containers which allow reducing their
* visible contents based on a set of filters. This interface has been
* renamed from {@link Filterable}, and implementing the new
* {@link Filterable} instead of or in addition to {@link SimpleFilterable}
* is recommended. This interface might be removed in future Vaadin
* versions.
* <p>
* When a set of filters are set, only items that match all the filters are
* included in the visible contents of the container. Still new items that
* do not match filters can be added to the container. Multiple filters can
* be added and the container remembers the state of the filters. When
* multiple filters are added, all filters must match for an item to be
* visible in the container.
* </p>
* <p>
* When an {@link Ordered} or {@link Indexed} container is filtered, all
* operations of these interfaces should only use the filtered contents and
* the filtered indices to the container.
* </p>
* <p>
* How filtering is performed when a {@link Hierarchical} container
* implements {@link SimpleFilterable} is implementation specific and should
* be documented in the implementing class.
* </p>
* <p>
* Adding items (if supported) to a filtered {@link Ordered} or
* {@link Indexed} container should insert them immediately after the
* indicated visible item. The unfiltered position of items added at index
* 0, at index {@link Container#size()} or at an undefined position is up to
* the implementation.
* </p>
* <p>
* The functionality of SimpleFilterable can be implemented using the
* {@link Filterable} API and {@link SimpleStringFilter}.
* </p>
*
* @since 5.0 (renamed from Filterable to SimpleFilterable in 6.6)
*/
@Deprecated
public interface SimpleFilterable extends Container, Serializable {
/**
* Add a filter for given property.
* <p>
* The API {@link Filterable#addContainerFilter(Filter)} is recommended
* instead of this method. A {@link SimpleStringFilter} can be used with
* the new API to implement the old string filtering functionality.
* <p>
* The filter accepts items for which toString() of the value of the
* given property contains or starts with given filterString. Other
* items are not visible in the container when filtered.
* <p>
* If a container has multiple filters, only items accepted by all
* filters are visible.
*
* @param propertyId
* Property for which the filter is applied to.
* @param filterString
* String that must match the value of the property
* @param ignoreCase
* Determine if the casing can be ignored when comparing
* strings.
* @param onlyMatchPrefix
* Only match prefixes; no other matches are included.
*/
public void addContainerFilter(Object propertyId, String filterString,
boolean ignoreCase, boolean onlyMatchPrefix);
/**
* Remove all filters from all properties.
*/
public void removeAllContainerFilters();
/**
* Remove all filters from the given property.
*
* @param propertyId
* for which to remove filters
*/
public void removeContainerFilters(Object propertyId);
}
/**
* Filter interface for container filtering.
* <p>
* If a filter does not support in-memory filtering,
* {@link #passesFilter(Item)} should throw
* {@link UnsupportedOperationException}.
* <p>
* Lazy containers must be able to map filters to their internal
* representation (e.g. SQL or JPA 2.0 Criteria).
* <p>
* An {@link UnsupportedFilterException} can be thrown by the container if a
* particular filter is not supported by the container.
* <p>
* An {@link Filter} should implement {@link #equals(Object)} and
* {@link #hashCode()} correctly to avoid duplicate filter registrations
* etc.
*
* @see Filterable
*
* @since 6.6
*
* @deprecated As of 8.0, the whole filtering feature is integrated into {@link DataProvider}.
* For in-memory case ({@link ListDataProvider}), use predicates as filters. For back-end DataProviders,
* filters are specific to the implementation.
*/
@Deprecated
public interface Filter extends Serializable {
/**
* Check if an item passes the filter (in-memory filtering).
*
* @param itemId
* identifier of the item being filtered; may be null when
* the item is being added to the container
* @param item
* the item being filtered
* @return true if the item is accepted by this filter
* @throws UnsupportedOperationException
* if the filter cannot be used for in-memory filtering
*/
public boolean passesFilter(Object itemId, Item item)
throws UnsupportedOperationException;
/**
* Check if a change in the value of a property can affect the filtering
* result. May always return true, at the cost of performance.
*
* If the filter cannot determine whether it may depend on the property
* or not, should return true.
*
* @param propertyId
* @return true if the filtering result may/does change based on changes
* to the property identified by propertyId
*/
public boolean appliesToProperty(Object propertyId);
}
/**
* Interface that is implemented by containers which allow reducing their
* visible contents based on a set of filters.
* <p>
* When a set of filters are set, only items that match all the filters are
* included in the visible contents of the container. Still new items that
* do not match filters can be added to the container. Multiple filters can
* be added and the container remembers the state of the filters. When
* multiple filters are added, all filters must match for an item to be
* visible in the container.
* </p>
* <p>
* When an {@link Ordered} or {@link Indexed} container is filtered, all
* operations of these interfaces should only use the filtered and sorted
* contents and the filtered indices to the container. Indices or item
* identifiers in the public API refer to the visible view unless otherwise
* stated. However, the <code>addItem*()</code> methods may add items that
* will be filtered out after addition or moved to another position based on
* sorting.
* </p>
* <p>
* How filtering is performed when a {@link Hierarchical} container
* implements {@link Filterable} is implementation specific and should be
* documented in the implementing class.
* </p>
* <p>
* Adding items (if supported) to a filtered {@link Ordered} or
* {@link Indexed} container should insert them immediately after the
* indicated visible item. However, the unfiltered position of items added
* at index 0, at index {@link Container#size()} or at an undefined position
* is up to the implementation.
* </p>
*
* <p>
* This API replaces the old Filterable interface, renamed to
* {@link SimpleFilterable} in Vaadin 6.6.
* </p>
*
* @since 6.6
*/
@Deprecated
public interface Filterable extends Container, Serializable {
/**
* Adds a filter for the container.
* <p>
* If a container has multiple filters, only items accepted by all
* filters are visible.
*
* @throws UnsupportedFilterException
* if the filter is not supported by the container
*/
public void addContainerFilter(Filter filter)
throws UnsupportedFilterException;
/**
* Removes a filter from the container.
* <p>
* This requires that the equals() method considers the filters as
* equivalent (same instance or properly implemented equals() method).
*/
public void removeContainerFilter(Filter filter);
/**
* Remove all active filters from the container.
*/
public void removeAllContainerFilters();
/**
* Returns the filters which have been applied to the container
*
* @return A collection of filters which have been applied to the
* container. An empty collection if no filters have been
* applied.
* @since 7.1
*/
public Collection<Filter> getContainerFilters();
}
/**
* Interface implemented by viewer classes capable of using a Container as a
* data source.
*/
@Deprecated
public interface Viewer extends Serializable {
/**
* Sets the Container that serves as the data source of the viewer.
*
* @param newDataSource
* The new data source Item
*/
public void setContainerDataSource(Container newDataSource);
/**
* Gets the Container serving as the data source of the viewer.
*
* @return data source Container
*/
public Container getContainerDataSource();
}
/**
* <p>
* Interface implemented by the editor classes supporting editing the
* Container. Implementing this interface means that the Container serving
* as the data source of the editor can be modified through it.
* </p>
* <p>
* Note that not implementing the <code>Container.Editor</code> interface
* does not restrict the class from editing the Container contents
* internally.
* </p>
*/
@Deprecated
public interface Editor extends Container.Viewer, Serializable {
}
/* Contents change event */
/**
* An <code>Event</code> object specifying the Container whose Item set has
* changed (items added, removed or reordered).
*
* A simple property value change is not an item set change.
*/
@Deprecated
public interface ItemSetChangeEvent extends Serializable {
/**
* Gets the Property where the event occurred.
*
* @return source of the event
*/
public Container getContainer();
}
/**
* Container Item set change listener interface.
* <p>
* An item set change refers to addition, removal or reordering of items in
* the container. A simple property value change is not an item set change.
*/
@Deprecated
public interface ItemSetChangeListener extends Serializable {
/**
* Lets the listener know a Containers visible (filtered and/or sorted,
* if applicable) Item set has changed.
*
* @param event
* change event text
*/
public void containerItemSetChange(Container.ItemSetChangeEvent event);
}
/**
* The interface for adding and removing <code>ItemSetChangeEvent</code>
* listeners. By implementing this interface a class explicitly announces
* that it will generate a <code>ItemSetChangeEvent</code> when its contents
* are modified.
* <p>
* An item set change refers to addition, removal or reordering of items in
* the container. A simple property value change is not an item set change.
*
* <p>
* Note: The general Java convention is not to explicitly declare that a
* class generates events, but to directly define the
* <code>addListener</code> and <code>removeListener</code> methods. That
* way the caller of these methods has no real way of finding out if the
* class really will send the events, or if it just defines the methods to
* be able to implement an interface.
* </p>
*/
@Deprecated
public interface ItemSetChangeNotifier extends Serializable {
/**
* Adds an Item set change listener for the object.
*
* @param listener
* listener to be added
*/
public void addItemSetChangeListener(
Container.ItemSetChangeListener listener);
/**
* @deprecated As of 7.0, replaced by
* {@link #addItemSetChangeListener(ItemSetChangeListener)}
**/
@Deprecated
public void addListener(Container.ItemSetChangeListener listener);
/**
* Removes the Item set change listener from the object.
*
* @param listener
* listener to be removed
*/
public void removeItemSetChangeListener(
Container.ItemSetChangeListener listener);
/**
* @deprecated As of 7.0, replaced by
* {@link #removeItemSetChangeListener(ItemSetChangeListener)}
**/
@Deprecated
public void removeListener(Container.ItemSetChangeListener listener);
}
/* Property set change event */
/**
* An <code>Event</code> object specifying the Container whose Property set
* has changed.
* <p>
* A property set change means the addition, removal or other structural
* changes to the properties of a container. Changes concerning the set of
* items in the container and their property values are not property set
* changes.
*/
@Deprecated
public interface PropertySetChangeEvent extends Serializable {
/**
* Retrieves the Container whose contents have been modified.
*
* @return Source Container of the event.
*/
public Container getContainer();
}
/**
* The listener interface for receiving <code>PropertySetChangeEvent</code>
* objects.
* <p>
* A property set change means the addition, removal or other structural
* change of the properties (supported property IDs) of a container. Changes
* concerning the set of items in the container and their property values
* are not property set changes.
*/
@Deprecated
public interface PropertySetChangeListener extends Serializable {
/**
* Notifies this listener that the set of property IDs supported by the
* Container has changed.
*
* @param event
* Change event.
*/
public void containerPropertySetChange(
Container.PropertySetChangeEvent event);
}
/**
* <p>
* The interface for adding and removing <code>PropertySetChangeEvent</code>
* listeners. By implementing this interface a class explicitly announces
* that it will generate a <code>PropertySetChangeEvent</code> when the set
* of property IDs supported by the container is modified.
* </p>
*
* <p>
* A property set change means the addition, removal or other structural
* changes to the properties of a container. Changes concerning the set of
* items in the container and their property values are not property set
* changes.
* </p>
*
* <p>
* Note that the general Java convention is not to explicitly declare that a
* class generates events, but to directly define the
* <code>addListener</code> and <code>removeListener</code> methods. That
* way the caller of these methods has no real way of finding out if the
* class really will send the events, or if it just defines the methods to
* be able to implement an interface.
* </p>
*/
@Deprecated
public interface PropertySetChangeNotifier extends Serializable {
/**
* Registers a new Property set change listener for this Container.
*
* @param listener
* The new Listener to be registered
*/
public void addPropertySetChangeListener(
Container.PropertySetChangeListener listener);
/**
* @deprecated As of 7.0, replaced by
* {@link #addPropertySetChangeListener(PropertySetChangeListener)}
**/
@Deprecated
public void addListener(Container.PropertySetChangeListener listener);
/**
* Removes a previously registered Property set change listener.
*
* @param listener
* Listener to be removed
*/
public void removePropertySetChangeListener(
Container.PropertySetChangeListener listener);
/**
* @deprecated As of 7.0, replaced by
* {@link #removePropertySetChangeListener(PropertySetChangeListener)}
**/
@Deprecated
public void removeListener(
Container.PropertySetChangeListener listener);
}
}