001 package data;
002
003 import data.events.VetoException;
004
005 /**
006 * A Stock that counts for each CatalogItem in the associated Catalog how many objects of that type are
007 * actually available.
008 *
009 * <p>In contrast to {@link StoringStock StoringStocks}, the StockItems for the same key have no differences
010 * when using CountingStocks. Therefore, only two pieces of information are needed: the key and the number of
011 * items for that key.</p>
012 *
013 * <p>CountingStocks are by far the more common type of Stock.</p>
014 *
015 * @author Steffen Zschaler
016 * @version 2.0 18/08/1999
017 * @since v2.0
018 */
019 public interface CountingStock extends Stock {
020
021 /**
022 * Add a number of items of a given key to the Stock.
023 *
024 * <p>As with any Stock the added items will not at once be visible to users of other DataBaskets.</p>
025 *
026 * <p>In general the method behaves as though it would call {@link Stock#add} <code>nCount</code> times.
027 * Especially, the same exceptions might occur and the same constraints hold.</p>
028 *
029 * @override Always
030 *
031 * @param sKey the key for which to add a number of items.
032 * @param nCount how many items are to be added?
033 * @param db the DataBasket relative to which the adding is performed.
034 *
035 * @exception IllegalArgumentException if <code>nCount <= 0</code>.
036 * @exception CatalogConflictException if the key cannot be found in the Catalog.
037 */
038 public void add(String sKey, int nCount, DataBasket db);
039
040 /**
041 * Remove a number of items of a given key from the Stock.
042 *
043 * <p>In general the method behaves as though it would call
044 * {@link Stock#remove(java.lang.String, data.DataBasket)} <code>nCount</code> times. Especially, the same
045 * exceptions might occur and the same constraints hold.</p>
046 *
047 * @override Always
048 *
049 * @param sKey the key for which to remove a number of items.
050 * @param nCount how many items are to be removed?
051 * @param db the DataBasket relative to which the removal is performed.
052 *
053 * @exception VetoException if a listener vetos the removal.
054 * @exception NotEnoughElementsException if there are not enough elements to fulfill the request. If this
055 * exception is thrown no items will have been removed.
056 * @exception IllegalArgumentException if <code>nCount <= 0</code>
057 */
058 public void remove(String sKey, int nCount, DataBasket db) throws VetoException;
059 }