123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296 |
- /*
- * 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 See {@code HierarchicalDataProvider} and its implementations.
- */
- @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);
- }
- }
|