* * 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: *
* *
* 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 * neccessarily {@link Container.Ordered ordered}or * {@link Container.Indexed indexed}. *
* *
*
*
* The Container interface is split to several subinterfaces so that a class can * implement only the ones it needs. *
* * @author IT Mill Ltd * @version * @VERSION@ * @since 3.0 */ public interface Container { /** * Gets the Item with the given Item ID from the Container. If the Container * does not contain the requested Item,null is returned.
*
* @param itemId
* ID of the Item to retrieve
* @return the Item with the given ID or null 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 are
* returned as a unmodifiable collection.
*
* @return unmodifiable collection of Property IDs
*/
public Collection getContainerPropertyIds();
/**
* Gets the ID's of all Items stored in the Container. The ID's are returned
* as a unmodifiable collection.
*
* @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 Property,
* null is returned.
*
* @param itemId
* ID of the Item which contains the Property
* @param propertyId
* ID of the Property to retrieve
* @return Property with the given ID or null
*/
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 Items in the Container.
*
* @return number of Items in the Container
*/
public int size();
/**
* Tests if the Container contains the specified Item
*
* @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 into 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. *
* * @param itemId * ID of the Item to be created * @return Created new Item, ornull in case of a failure
*/
public Item addItem(Object itemId) 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
* {@link #getItem(Object ItemId) getItem}method to fetch the
* Item.
*
* This functionality is optional. *
* * @return ID of the newly created Item, ornull in case of a
* failure
*/
public Object addItem() throws UnsupportedOperationException;
/**
* Removes the Item identified by ItemId from the Container.
* This functionality is optional.
*
* @param itemId
* ID of the Item to remove
* @return true if the operation succeeded,
* false if not
*/
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.
*
* 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 true if the operation succeeded,
* false if not
*/
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.
*
* This functionality is optional.
*
* @param propertyId
* ID of the Property to remove
* @return true if the operation succeeded,
* false if not
*/
public boolean removeContainerProperty(Object propertyId)
throws UnsupportedOperationException;
/**
* Removes all Items from the Container.
*
* * Note that Property ID and type information is preserved. This * functionality is optional. *
* * @returntrue if the operation succeeded,
* false if not
*/
public boolean removeAllItems() throws UnsupportedOperationException;
/**
* Interface for Container classes whose Items can be traversed in order.
*/
public interface Ordered extends Container {
/**
* Gets the ID of the Item following the Item that corresponds to
* itemId. If the given Item is the last or not found in
* the Container, null is returned.
*
* @param itemId
* ID of an Item in the Container
* @return ID of the next Item or null
*/
public Object nextItemId(Object itemId);
/**
* Gets the ID of the Item preceding the Item that corresponds to
* itemId. If the given Item is the first or not found
* in the Container, null is returned.
*
* @param itemId
* ID of an Item in the Container
* @return ID of the previous Item or null
*/
public Object prevItemId(Object itemId);
/**
* Gets the ID of the first Item in the Container.
*
* @return ID of the first Item in the Container
*/
public Object firstItemId();
/**
* Gets the ID of the last Item in the Container..
*
* @return ID of the last 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 true if the Item is first in the Container,
* false 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 true if the Item is last in the Container,
* false if not
*/
public boolean isLastId(Object itemId);
/**
* Adds new item after the given item.
* * Adding an item after null item adds the item as first item of the * ordered container. *
* * @param previousItemId * Id of the previous item in ordered container. * @return Returns item id the the created new item or null if the * operation fails. */ public Object addItemAfter(Object previousItemId) throws UnsupportedOperationException; /** * Adds new item after the given item. ** Adding an item after null item adds the item as first item of the * ordered container. *
* * @param previousItemId * Id of the previous item in ordered container. * @param newItemId * Id of the new item to be added. * @return Returns new item or null if the operation fails. */ public Item addItemAfter(Object previousItemId, Object newItemId) throws UnsupportedOperationException; } /** Interface for Container classes whose Items can be sorted. */ public interface Sortable extends Ordered { /** * Sort method. * * Sorts the container items. * * @param propertyId * Array of container property IDs, which 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 *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
* true to sort in ascending order,
* false to use descending order.
*/
void sort(Object[] propertyId, boolean[] ascending);
/**
* Gets the container property IDs, which can be used to sort the item.
*
* @return The sortable field ids.
*/
Collection getSortableContainerPropertyIds();
}
/** Interface for Container classes whose Items can be indexed. */
public interface Indexed extends Ordered {
/**
* Gets the index of the Item corresponding to the itemId. The following
* is true for the returned index: 0 <= index < size().
*
* @param itemId
* ID of an Item in the Container
* @return index of the Item, or -1 if the Container does not include
* the Item
*/
public int indexOfId(Object itemId);
/**
* Gets the ID of an Item by an index number.
*
* @param index
* Index of the requested id in the Container
* @return ID of the Item in the given index
*/
public Object getIdByIndex(int index);
/**
* Adds new item at given index.
* * The indexes of the item currently in the given position and all the * following items are incremented. *
* * @param index * Index to add the new item. * @return Returns item id the the created new item or null if the * operation fails. */ public Object addItemAt(int index) throws UnsupportedOperationException; /** * Adds new item at given index. ** The indexes of the item currently in the given position and all the * following items are incremented. *
* * @param index * Index to add the new item. * @param newItemId * Id of the new item to be added. * @return Returns new item or null if the operation fails. */ public Item addItemAt(int index, Object newItemId) throws UnsupportedOperationException; } /** *
* Interface for Container 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:
*
null 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 root 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();
/**
*
* Sets the parent of an Item. The new parent item must exist and be
* able to have children. (
* canHaveChildren(newParentId) == true). It is also
* possible to detach a node from the hierarchy (and thus make it root)
* by setting the parent null.
*
* This operation is optional. *
* * @param itemId * ID of the item to be set as the child of the Item * identified withnewParentId
* @param newParentId
* ID of the Item that's to be the new parent of the Item
* identified with itemId
* @return true if the operation succeeded,
* false if not
*/
public boolean setParent(Object itemId, Object newParentId)
throws UnsupportedOperationException;
/**
* Tests if the Item with given ID can have any children. If the
* Container also implements the Managed interface, the
* items created with newItem can have children by
* default.
*
* @param itemId
* ID of the Item in the container whose child capability
* is to be tested
* @return true if the specified Item exists in the
* Container and it can have children, false if
* it's not found from the container or it can't have children.
*/
public boolean areChildrenAllowed(Object itemId);
/**
*
* Sets the given Item's capability to have children. If the Item
* identified with itemId already has children and
* areChildrenAllowed is false this method fails and
* false is returned.
*
* The children must be first explicitly removed with * {@link #setParent(Object itemId, Object newParentId)}or * {@link com.itmill.toolkit.data.Container#removeItem(Object itemId)}. *
* *
* This operation is optional. If it is not implemented, the method
* always returns false.
*
true if the operation succeeded,
* false if not
*/
public boolean setChildrenAllowed(Object itemId,
boolean areChildrenAllowed)
throws UnsupportedOperationException;
/**
* Tests if the Item specified with itemId 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
* null for root Items.
*
* @param itemId
* ID of the Item whose root status is to be tested
* @return true if the specified Item is a root,
* false if not
*/
public boolean isRoot(Object itemId);
/**
*
* Tests if the Item specified with itemId has any child
* Items, that is, is it a leaf Item. The
* {@link #getChildren(Object itemId)}method always returns
* null for leaf Items.
*
* Note that being a leaf does not imply whether or not an Item is * allowed to have children. *
. * * @param itemId * ID of the Item whose leaf status is to be tested * @returntrue if the specified Item is a leaf,
* false if not
*/
public boolean hasChildren(Object itemId);
}
/**
* Interface is implemented by containers that allow reducing their
* visiblecontents with set of filters.
*
* When a set of filters are set, only items that match 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.
*
* @since 5.0
*/
public interface Filterable extends Container {
/**
* Add a filter for given property.
*
* Only items where given property for which toString() contains or
* starts with given filterString are visible in the container.
*
* @param propertyId
* Property for which the filter is applied to.
* @param filterString
* String that must match contents 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 given property. */
public void removeContainerFilters(Object propertyId);
}
/**
* Interface implemented by viewer classes capable of using a Container as a
* data source.
*/
public interface Viewer {
/**
* 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();
}
/**
* * 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. *
*
* Note that not implementing the Container.Editor interface
* does not restrict the class from editing the Container contents
* internally.
*
Event object specifying the Container whose Item set
* has changed. Note that these events are triggered only through succesful
* calls to the newItem and removeAllItems
* methods in the Container.Managed interface.
*/
public interface ItemSetChangeEvent {
/**
* Gets the Property where the event occurred.
*
* @return source of the event
*/
public Container getContainer();
}
/** Container Item set change listener interface. */
public interface ItemSetChangeListener {
/**
* Lets the listener know a Containers Item set has changed.
*
* @param event
* change event text
*/
public void containerItemSetChange(Container.ItemSetChangeEvent event);
}
/**
* The interface for adding and removing ItemSetChangeEvent
* listeners. By implementing this interface a class explicitly announces
* that it will generate a ItemSetChangeEvent when its
* contents are modified.
*
* Note: The general Java convention is not to explicitly declare that a
* class generates events, but to directly define the
* addListener and removeListener 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.
*
Event object specifying the Container whose Property
* set has changed.
*
* Note: These events are triggered only through succesful calls to the
* addProperty and removeProperty methods in
* the Container.Managed interface.
*
PropertySetChangeEvent
* objects.
*/
public interface PropertySetChangeListener {
/**
* Notifies this listener that the Containers contents has changed.
*
* @param event
* Change event.
*/
public void containerPropertySetChange(
Container.PropertySetChangeEvent event);
}
/**
*
* The interface for adding and removing PropertySetChangeEvent
* listeners. By implementing this interface a class explicitly announces
* that it will generate a PropertySetChangeEvent when its
* contents are modified.
*
* Note that the general Java convention is not to explicitly declare that a
* class generates events, but to directly define the
* addListener and removeListener 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.
*