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    }