package data;

import data.events.VetoException;

/**
  * A Stock that counts for each CatalogItem in the associated Catalog how many objects of that type are
  * actually available.
  *
  * <p>In contrast to {@link StoringStock StoringStocks}, the StockItems for the same key have no differences
  * when using CountingStocks. Therefore, only two pieces of information are needed: the key and the number of
  * items for that key.</p>
  *
  * <p>CountingStocks are by far the more common type of Stock.</p>
  *
  * @author Steffen Zschaler
  * @version 2.0 18/08/1999
  * @since v2.0
  */
public interface CountingStock extends Stock {

  /**
    * Add a number of items of a given key to the Stock.
    *
    * <p>As with any Stock the added items will not at once be visible to users of other DataBaskets.</p>
    *
    * <p>In general the method behaves as though it would call {@link Stock#add} <code>nCount</code> times.
    * Especially, the same exceptions might occur and the same constraints hold.</p>
    *
    * @override Always
    *
    * @param sKey the key for which to add a number of items.
    * @param nCount how many items are to be added?
    * @param db the DataBasket relative to which the adding is performed.
    *
    * @exception IllegalArgumentException if <code>nCount <= 0</code>.
    * @exception CatalogConflictException if the key cannot be found in the Catalog.
    */
  public void add (String sKey, int nCount, DataBasket db);

  /**
    * Remove a number of items of a given key from the Stock.
    *
    * <p>In general the method behaves as though it would call
    * {@link Stock#remove(java.lang.String, data.DataBasket)} <code>nCount</code> times. Especially, the same
    * exceptions might occur and the same constraints hold.</p>
    *
    * @override Always
    *
    * @param sKey the key for which to remove a number of items.
    * @param nCount how many items are to be removed?
    * @param db the DataBasket relative to which the removal is performed.
    *
    * @exception VetoException if a listener vetos the removal.
    * @exception NotEnoughElementsException if there are not enough elements to fulfill the request. If this
    * exception is thrown no items will have been removed.
    * @exception IllegalArgumentException if <code>nCount <= 0</code>
    */
  public void remove(String sKey, int nCount, DataBasket db)
    throws VetoException;
}