data
Interface Stock<T extends StockItem,CT extends CatalogItem>

All Superinterfaces:

Cloneable, Comparable<Object>, DataBasketEntryDestination, DataBasketEntrySource, Nameable, Serializable, StockItem

All Known Subinterfaces:

CountingStock<T,CT>, ListenableStock<T,CT>, MoneyBag, StoringStock<T,CT>

All Known Implementing Classes:

AbstractStockFilter, CountingStockFilter, CountingStockImpl, MoneyBagFilter, MoneyBagImpl, StockImpl, StoringStockFilter, StoringStockImpl

public interface Stock<T extends StockItem,CT extends CatalogItem>
extends StockItem, DataBasketEntrySource, DataBasketEntryDestination

A Stock.

Stocks are lists that refer to a Catalog and denote for each CatalogItem how many objects of this type are actually available. There are two basically different types of Stocks:

1. CountingStock
   Stocks that store only the number of objects available for each CatalogItem.
   This type of Stock will be used whenever the information given by the CatalogItem sufficiently describes the object.
   In general this type of Stock should be sufficient.
2. StoringStock
   Stocks that store a list of actual StockItems for each CatalogItem.
   This type of Stock is usually used to store additional information with the StockItems. E.g. to store the 'Stock' of lent books in a library you would create StockItems that can store the name of the borrower and the date of borrowing.
   This type of Stock is also needed when implementing nested Stocks.

To suit both types of Stock, StockItems are introduced. A StockItem refers to a CatalogItem but can store additional information as well.

Stocks work always on StockItems. They add, remove and search StockItems. They are able to return an Iterator of StockItems for a given key, but can as well just count all StockItems for the same key.

Since:

v0.5

Author:

Steffen Zschaler

Field Summary

Fields inherited from interface data.Nameable

NAME_PROPERTY

Method Summary

void	add(T si, DataBasket db) Add an item to the Stock.
void	addStock(Stock<T,CT> st, DataBasket db, boolean fRemove) Add the contents of a Stock to this Stock.
boolean	contains(String sKey, DataBasket db) Check whether the Stock contains an item with the given key.
boolean	contains(T si, DataBasket db) Check whether the Stock contains the given StockItem.
boolean	containsStock(Stock<T,CT> st, DataBasket db) Check whether the given Stock is completely contained in this Stock.
int	countItems(String sKey, DataBasket db) Count the StockItems with a given key that are visible using a given DataBasket.
Value	fillStockWithValue(DataBasket db, Value vTarget, StockFromValueCreator sfvc) Increase the Stock's value by a given value.
Iterator<T>	get(String sKey, DataBasket db, boolean fForEdit) Iterate all items with a given key.
Catalog	getCatalog(DataBasket db) Get the Catalog associated to this Stock.
Iterator<T>	iterator(DataBasket db, boolean fForEdit) Iterate all items in the Stock.
Set<String>	keySet(DataBasket db) Return the set of keys for which StockItems are visible using the given DataBasket.
StockItem	remove(String sKey, DataBasket db) Remove one StockItem with the specified key from the Stock.
StockItem	remove(T si, DataBasket db) Remove the given StockItem from the Stock.
int	size(DataBasket db) Get the size of this Stock.
Value	sumStock(DataBasket db, CatalogItemValue civ, Value vInit) Sum up the Stock.

Methods inherited from interface data.StockItem

clone, getAssociatedItem, getStock

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface data.Nameable

addNameListener, addPropertyChangeListener, attach, detachNC, getName, removeNameListener, removePropertyChangeListener, setName

Method Detail

add

void add(T si,
         DataBasket db)

Add an item to the Stock.

The item will only be visible to users of the same DataBasket. Only after a DataBasket.commit() was performed on the DataBasket, the item will become visible to other users.

For a ListenableStock a addedStockItems event will be fired.

Parameters:

si - the item to be added.

db - the DataBasket relative to which the item will be added.

Throws:

CatalogConflictException - if the items key is not contained in the corresponding Catalog.

DataBasketConflictException - if the item has already been added/removed using another DataBasket.

Override:

Always

addStock

void addStock(Stock<T,CT> st,
              DataBasket db,
              boolean fRemove)

Add the contents of a Stock to this Stock. The method conceptually calls add(T, data.DataBasket) for each item in the source Stock so the same constraints apply and the same exceptions may be thrown.

Parameters:

st - the Stock whose contents is to be added to this Stock.

db - the DataBasket relative to which to perform the actions. addStock will add all items from the source Stock that are visible using this DataBasket.

fRemove - if true, the items will be removed from the source Stock prior to adding them to this Stock. Otherwise, they will be cloned prior to adding them to the Stock.

Override:

Always

get

Iterator<T> get(String sKey,
                DataBasket db,
                boolean fForEdit)

Iterate all items with a given key.

This method, together with iterator(data.DataBasket, boolean) is the only way of accessing the individual StockItems contained in a Stock. The iterator will deliver all items that have the specified key and are visible using the given DataBasket. Depending on the fForEdit parameter, the items will be retrieved in different ways. See DataBasket for an explanation of the different possibilities.

For a ListenableStock canEditStockItems and editingStockItems events will be fired if fForEdit == true. VetoExceptions will be converted into UnSupportedOperationExceptions.

Parameters:

sKey - the key for which to retrieve the StockItems.

db - the DataBasket relative to which to retrieve the StockItems.

fForEdit - if true, the StockItems will be retrieved for editing.

Override:

Always

countItems

int countItems(String sKey,
               DataBasket db)

Count the StockItems with a given key that are visible using a given DataBasket.

Parameters:

sKey - the key for which to count the StockItems.

db - the DataBasket that is used to determine visibility.

Override:

Always

contains

boolean contains(String sKey,
                 DataBasket db)

Check whether the Stock contains an item with the given key.

Equivalent to:(countItems(java.lang.String, data.DataBasket) (sKey, db) > 0).

Parameters:

sKey - the key for which to check containment.

db - the DataBasket used to check visibility.

Override:

Always

contains

boolean contains(T si,
                 DataBasket db)

Check whether the Stock contains the given StockItem.

Return true if the Stock contains a StockItem that is equal to the given one.

Parameters:

si - the StockItem for which to check containment.

db - the DataBasket used to check visibility.

Override:

Always.

containsStock

boolean containsStock(Stock<T,CT> st,
                      DataBasket db)

Check whether the given Stock is completely contained in this Stock.

Conceptually calls contains(data.StockItem, data.DataBasket) for each item in the given Stock.

Parameters:

st - the Stock for which to check containment.

db - the DataBasket used to determine visibility.

Override:

Always

remove

StockItem remove(String sKey,
                 DataBasket db)
                 throws VetoException

Remove one StockItem with the specified key from the Stock.

If there are any StockItems with the specified key, one will be removed. There is no guarantee as to which StockItem will be removed. The removed item, if any, will be returned.

For a ListenableStock canRemoveStockItems and removedStockItems events will be fired.

Parameters:

sKey - the key for which to remove an item.

db - the DataBasket relative to which to remove the item.

Returns:

the removed item

Throws:

VetoException - if a listener vetoed the removal.

DataBasketConflictException - if the item cannot be removed due to conflicts from DataBasket usage.

Override:

Always

remove

StockItem remove(T si,
                 DataBasket db)
                 throws VetoException

Remove the given StockItem from the Stock.

If the given StockItem is contained in the Stock, it will be removed. The removed item, if any, will be returned.

For a ListenableStock canRemoveStockItems and removedStockItems events will be fired.

Parameters:

si - the StockItem to be removed.

db - the DataBasket relative to which to remove the item.

Returns:

the removed item

Throws:

VetoException - if a listener vetoed the removal.

DataBasketConflictException - if the item cannot be removed due to conflicts from DataBasket usage.

Override:

Always

iterator

Iterator<T> iterator(DataBasket db,
                     boolean fForEdit)

Iterate all items in the Stock.

This method, together with get(java.lang.String, data.DataBasket, boolean) is the only way of accessing the individual StockItems contained in a Stock. The iterator will deliver all items that are visible using the given DataBasket. Depending on the fForEdit parameter, the items will be retrieved in different ways. See DataBasket for an explanation of the different possibilities.

For a ListenableStock canEditStockItems and editingStockItems events will be fired if fForEdit == true. VetoExceptions will be converted into UnSupportedOperationExceptions.

Parameters:

db - the DataBasket relative to which to retrieve the StockItems.

fForEdit - if true, the StockItems will be retrieved for editing.

Override:

Always

keySet

Set<String> keySet(DataBasket db)

Return the set of keys for which StockItems are visible using the given DataBasket.

The returned set is static and gives the state of the Stock at the time of the call. It will not automatically update when the contents of the Stock changes.

Parameters:

db - the DataBasket used for determining visibility.

Override:

Always

sumStock

Value sumStock(DataBasket db,
               CatalogItemValue civ,
               Value vInit)

Sum up the Stock.

The method will determine the value of each CatalogItem in the associated Catalog and multiply this by the number of StockItems for the respective key. These products will be added up and the resulting total will be returned.

Parameters:

db - the DataBasket that is used to determine visibility.

civ - the CatalogItemValue used for determining the value of a CatalogItem.

vInit - the initial value. The sum of the Stock will be added to this value.

Returns:

the resulting total. Usually the returned object is the same as the one passed as vInit, only with a changed value.

Override:

Always

fillStockWithValue

Value fillStockWithValue(DataBasket db,
                         Value vTarget,
                         StockFromValueCreator sfvc)

Increase the Stock's value by a given value.

The method will try to break the given value as exactly as possible into StockItems that will be added to the Stock. The actual algorithm used for breaking up the value will be determined by the last parameter. The return value of the method will specify the remaining value that could not be represented by StockItems by the given algorithm.

Parameters:

db - the DataBasket relative to which to perform the operation.

vTarget - the value by which to increase the Stock's total value.

sfvc - the strategy used to fill the Stock.

Returns:

the value that remained and could not be represented by StockItems.

Override:

Always

size

int size(DataBasket db)

Get the size of this Stock. I.e. calculate the number of StockItems that can be seen when using the given DataBasket.

Parameters:

db - the DataBasket used to determine visibility.

Override:

Always

getCatalog

Catalog getCatalog(DataBasket db)

Get the Catalog associated to this Stock.

For a substock of another stock this is essentially equivalent to

 Catalog cReturn = (Catalog) getAssociatedItem (db);

 if (cReturn != null) {
   return cReturn;
 }
 else {
   throw new DataBasketConflictException();
 }
 

Parameters:

db - a DataBasket determinig visibility of the stock's catalog.

Override:

Always