com.vaadin.data
Interface Container

All Superinterfaces:

Serializable

All Known Subinterfaces:

Collapsible, Container.Filterable, Container.Hierarchical, Container.Indexed, Container.Ordered, Container.SimpleFilterable, Container.Sortable

All Known Implementing Classes:

AbstractBeanContainer, AbstractContainer, AbstractInMemoryContainer, AbstractSelect, BeanContainer, BeanItemContainer, ComboBox, ContainerHierarchicalWrapper, ContainerOrderedWrapper, FilesystemContainer, HierarchicalContainer, HierarchicalContainerOrderedWrapper, IndexedContainer, ListSelect, NativeSelect, OptionGroup, QueryContainer, Select, SQLContainer, Table, Tree, TreeTable, TwinColSelect

public interface Container
extends Serializable

A specialized set of identified Items. Basically the Container is a set of Items, but it imposes certain constraints on its contents. These constraints state the following:

• All Items in the Container must have the same number of Properties.
• All Items in the Container must have the same Property ID's (see Item.getItemPropertyIds()).
• All Properties in the Items corresponding to the same Property ID must have the same data type.
• All Items within a container are uniquely identified by their non-null IDs.

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 null values.

Note that though uniquely identified, the Items in a Container are not necessarily ordered or indexed.

Containers can derive Item ID's from the item properties or use other, container specific or user specified identifiers.

If a container is filtered or sorted, most of the the methods of the container interface and its subinterfaces (container size, 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).

The Container interface is split to several subinterfaces so that a class can implement only the ones it needs.

Since:

3.0

Version:

7.0.0.alpha3

Author:

Vaadin Ltd

Nested Class Summary

static interface	Container.Editor Interface implemented by the editor classes supporting editing the Container.
static interface	Container.Filter Filter interface for container filtering.
static interface	Container.Filterable Interface that is implemented by containers which allow reducing their visible contents based on a set of filters.
static interface	Container.Hierarchical Interface for Container classes whose Items can be arranged hierarchically.
static interface	Container.Indexed Interface for Container classes whose Items can be accessed by their position in the container.
static interface	Container.ItemSetChangeEvent An Event object specifying the Container whose Item set has changed (items added, removed or reordered).
static interface	Container.ItemSetChangeListener Container Item set change listener interface.
static interface	Container.ItemSetChangeNotifier The interface for adding and removing ItemSetChangeEvent listeners.
static interface	Container.Ordered Interface for Container classes whose Items can be traversed in order.
static interface	Container.PropertySetChangeEvent An Event object specifying the Container whose Property set has changed.
static interface	Container.PropertySetChangeListener The listener interface for receiving PropertySetChangeEvent objects.
static interface	Container.PropertySetChangeNotifier The interface for adding and removing PropertySetChangeEvent listeners.
static interface	Container.SimpleFilterable Interface that is implemented by containers which allow reducing their visible contents based on a set of filters.
static interface	Container.Sortable Interface for Container classes whose Items can be sorted.
static interface	Container.Viewer Interface implemented by viewer classes capable of using a Container as a data source.

Method Summary

boolean	addContainerProperty(Object propertyId, Class<?> type, Object defaultValue) Adds a new Property to all Items in the Container.
Object	addItem() Creates a new Item into the Container, and assign it an automatic ID.
Item	addItem(Object itemId) Creates a new Item with the given ID in the Container.
boolean	containsId(Object itemId) Tests if the Container contains the specified Item.
Property<?>	getContainerProperty(Object itemId, Object propertyId) Gets the Property identified by the given itemId and propertyId from the Container.
Collection<?>	getContainerPropertyIds() Gets the ID's of all Properties stored in the Container.
Item	getItem(Object itemId) Gets the Item with the given Item ID from the Container.
Collection<?>	getItemIds() Gets the ID's of all visible (after filtering and sorting) Items stored in the Container.
Class<?>	getType(Object propertyId) Gets the data type of all Properties identified by the given Property ID.
boolean	removeAllItems() Removes all Items from the Container.
boolean	removeContainerProperty(Object propertyId) Removes a Property specified by the given Property ID from the Container.
boolean	removeItem(Object itemId) Removes the Item identified by ItemId from the Container.
int	size() Gets the number of visible Items in the Container.

Method Detail

getItem

Item getItem(Object itemId)

Gets the Item with the given Item ID from the Container. If the Container does not contain the requested Item, null is returned. Containers should not return Items that are filtered out.

Parameters:

itemId - ID of the Item to retrieve

Returns:

the Item with the given ID or null if the Item is not found in the Container

getContainerPropertyIds

Collection<?> getContainerPropertyIds()

Gets the ID's of all Properties stored in the Container. The ID's cannot be modified through the returned collection.

Returns:

unmodifiable collection of Property IDs

getItemIds

Collection<?> getItemIds()

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. If the container is Container.Ordered, the collection returned by this method should follow that order. If the container is Container.Sortable, the items should be in the sorted order. Calling this method for large lazy containers can be an expensive operation and should be avoided when practical.

Returns:

unmodifiable collection of Item IDs

getContainerProperty

Property<?> getContainerProperty(Object itemId,
                                 Object propertyId)

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, null is returned.

Parameters:

itemId - ID of the visible Item which contains the Property

propertyId - ID of the Property to retrieve

Returns:

Property with the given ID or null

getType

Class<?> getType(Object propertyId)

Gets the data type of all Properties identified by the given Property ID.

Parameters:

propertyId - ID identifying the Properties

Returns:

data type of the Properties

size

int size()

Gets the number of visible Items in the Container. Filtering can hide items so that they will not be visible through the container API.

Returns:

number of Items in the Container

containsId

boolean containsId(Object itemId)

Tests if the Container contains the specified Item. 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.

Parameters:

itemId - ID the of Item to be tested

Returns:

boolean indicating if the Container holds the specified Item

addItem

Item addItem(Object itemId)
             throws UnsupportedOperationException

Creates a new Item with the given ID in the Container.

The new Item is returned, and it is ready to have its Properties modified. Returns null if the operation fails or the Container already contains a Item with the given ID.

This functionality is optional.

Parameters:

itemId - ID of the Item to be created

Returns:

Created new Item, or null in case of a failure

Throws:

UnsupportedOperationException - if adding an item with an explicit item ID is not supported by the container

addItem

Object addItem()
               throws UnsupportedOperationException

Creates a new Item into the Container, and assign it an automatic ID.

The new ID is returned, or null if the operation fails. After a successful call you can use the getItemmethod to fetch the Item.

This functionality is optional.

Returns:

ID of the newly created Item, or null in case of a failure

Throws:

UnsupportedOperationException - if adding an item without an explicit item ID is not supported by the container

removeItem

boolean removeItem(Object itemId)
                   throws UnsupportedOperationException

Removes the Item identified by ItemId from the Container.

Containers that support filtering should also allow removing an item that is currently filtered out.

This functionality is optional.

Parameters:

itemId - ID of the Item to remove

Returns:

true if the operation succeeded, false if not

Throws:

UnsupportedOperationException - if the container does not support removing individual items

addContainerProperty

boolean addContainerProperty(Object propertyId,
                             Class<?> type,
                             Object defaultValue)
                             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. This functionality is optional.

Parameters:

propertyId - ID of the Property

type - Data type of the new Property

defaultValue - The value all created Properties are initialized to

Returns:

true if the operation succeeded, false if not

Throws:

UnsupportedOperationException - if the container does not support explicitly adding container properties

removeContainerProperty

boolean removeContainerProperty(Object propertyId)
                                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. This functionality is optional.

Parameters:

propertyId - ID of the Property to remove

Returns:

true if the operation succeeded, false if not

Throws:

UnsupportedOperationException - if the container does not support removing container properties

removeAllItems

boolean removeAllItems()
                       throws UnsupportedOperationException

Removes all Items from the Container.

Note that Property ID and type information is preserved. This functionality is optional.

Returns:

true if the operation succeeded, false if not

Throws:

UnsupportedOperationException - if the container does not support removing all items