SalesPoint Framework v3.1

data
Interface Catalog

All Superinterfaces:
CatalogItem, Comparable, DataBasketEntryDestination, DataBasketEntrySource, Nameable, Serializable
All Known Subinterfaces:
Currency, ListenableCatalog
All Known Implementing Classes:
AbstractCurrency, CatalogFilter, CatalogImpl, CurrencyFilter, CurrencyImpl

public interface Catalog
extends CatalogItem, DataBasketEntrySource, DataBasketEntryDestination

A Catalog.

Catalogs are - usually system global - lists of items. Each Catalog has a name unique to its scope of usage. It is identified by this name. Catalogs consist of CatalogItems, which comprise a key (String), possibly a value (Value) and any number of additional attributes as needed to correctly describe the item.

A Catalog is capable to test whether it contains CatalogItems with a certain key or matching a given CatalogItem. It will make available for editing the CatalogItem of a given key, if this key is contained in the Catalog.

Catalogs support the usage of DataBaskets so that all operations on the Catalog can be performed in a transactional style.

As a Catalog is itself a CatalogItem, constructing arbitrarily nested Catalogs is possible.

A Catalog is serializable to allow for it to be stored to an ObjectOutputStream.

Since:
v0.5
Author:
Steffen Zschaler
See Also:
Stock

Field Summary
 
Fields inherited from interface data.CatalogItem
VALUE_PROPERTY
 
Fields inherited from interface data.Nameable
NAME_PROPERTY
 
Method Summary
 void add(CatalogItem ci, DataBasket db)
          Add a CatalogItem to the Catalog.
 boolean contains(String sKey, DataBasket db)
          Check whether the Catalog contains a certain CatalogItem.
 CatalogItem get(String sKey, DataBasket db, boolean fForEdit)
          Get a CatalogItem by its key.
 Iterator iterator(DataBasket db, boolean fForEdit)
          Return an iterator of all items in the Catalog.
 Set keySet(DataBasket db)
          Get a set of all keys currently in the Catalog.
 CatalogItem remove(CatalogItem ci, DataBasket db)
          Remove a CatalogItem from the Catalog.
 CatalogItem remove(String sKey, DataBasket db)
          Remove a CatalogItem from the Catalog.
 int size(DataBasket db)
          Calculate the size of the Catalog.
 
Methods inherited from interface data.CatalogItem
addValueListener, getCatalog, getValue, removeValueListener
 
Methods inherited from interface data.Nameable
addNameListener, addPropertyChangeListener, attach, detachNC, getName, removeNameListener, removePropertyChangeListener, setName
 
Methods inherited from interface java.lang.Comparable
compareTo
 

Method Detail

add

public void add(CatalogItem ci,
                DataBasket db)
Add a CatalogItem to the Catalog.

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

For a ListenableCatalog, a addedCatalogItem event will be fired.

Parameters:
ci - the CatalogItem to be added. This item must not be contained in another Catalog.
db - the DataBasket relative to which the operation is to be performed.
Throws:
NotEditableException - if the Catalog is currently not editable.
DuplicateKeyException - if a CatalogItem of the same name does already exist in the Catalog.
DataBasketConflictException - if the CatalogItem cannot be added because an item of the same name has already been added/removed using another DataBasket.
Override:
Always

remove

public CatalogItem remove(CatalogItem ci,
                          DataBasket db)
                   throws VetoException
Remove a CatalogItem from the Catalog.

The item's removal will be immediately visible to all users of the Catalog. However, only users of the same DataBasket that was used to remove the item will be able to add an item with the same key later. Only after a commit() was executed on the DataBasket, other users of the Catalog will have a chance to add an item with the same key.

For a ListenableCatalog, canRemoveCatalogItem and removedCatalogItem events will be fired. If one of the listeners vetos the removal, a VetoException will be thrown.

Parameters:
ci - the CatalogItem to be removed.
db - the DataBasket relative to which the operation is to be performed.
Returns:
the item that was actually removed.
Throws:
NotEditableException - if the Catalog is currently not editable.
VetoException - if one of the listeners vetos the removal.
DataBasketConflictException - if the CatalogItem cannot be removed because an item of the same name has already been added using another DataBasket.
Override:
Always

remove

public CatalogItem remove(String sKey,
                          DataBasket db)
                   throws VetoException
Remove a CatalogItem from the Catalog.

The item's removal will be immediately visible to all users of the Catalog. However, only users of the same DataBasket that was used to remove the item will be able to add an item with the same key later. Only after a commit() was executed on the DataBasket, other users of the Catalog will have a chance to add an item with the same key.

For a ListenableCatalog, canRemoveCatalogItem and removedCatalogItem events will be fired. If one of the listeners vetos the removal, a VetoException will be thrown.

Parameters:
sKey - the key of the CatalogItem to be removed.
db - the DataBasket relative to which the operation is to be performed.
Returns:
the item that was actually removed.
Throws:
NotEditableException - if the Catalog is currently not editable.
VetoException - if one of the listeners vetos the removal.
DataBasketConflictException - if the CatalogItem cannot be removed because an item of the same name has already been added using another DataBasket.
Override:
Always

get

public CatalogItem get(String sKey,
                       DataBasket db,
                       boolean fForEdit)
                throws VetoException
Get a CatalogItem by its key.

There are two distinct possibilities when getting a CatalogItem from a Catalog:

  1. Just for looking at it (fForEdit == false):
    In this case the original item is delivered if it is visible for users of the given DataBasket. However, no guarantee is given that the item will still be in the Catalog the next time you look. Also, editing the retrieved item is illegal and may result in corrupted data.
  2. For editing (fForEdit == true):
    In this case, the item is specially prepared for editing before delivering it. The item will no longer be visible to users of other DataBaskets until a DataBasket.commit() is performed on the DataBasket. It is legal to edit the retrieved item (however, not necessarily the same item that was retrieved earlier using possibility 1 !!!), and all editing can be commited or rolled back using the DataBasket. This possibility can, however, be vetoed if this is a ListenableCatalog.

    For a ListenableCatalog, canEditCatalogItem and editingCatalogItem events will be fired. If one of the listeners vetos the editing, a VetoException will be thrown.

 

Parameters:
sKey - the key of the CatalogItem to be retrieved.
db - the DataBasket relative to which the operation is to be performed.
fForEdit - if true, the CatalogItem will be retrieved for editing.
Returns:
the item that is associated with the given key.
Throws:
NotEditableException - if the Catalog is not currently editable, but an attempt is made to edit one of its items.
VetoException - if one of the listeners vetos the editing.
DataBasketConflictException - if the CatalogItem cannot be retrieved because it is not visible to users of the given DataBasket.
Override:
Always

contains

public boolean contains(String sKey,
                        DataBasket db)
Check whether the Catalog contains a certain CatalogItem.

Will return true only if an item of the given key is contained in the Catalog and if that item is visible to users of the given DataBasket.

Parameters:
sKey - the key for which to check containment.
db - the DataBasket that defines visibility of items. See add(data.CatalogItem, data.DataBasket) and remove(data.CatalogItem, data.DataBasket) for details on visibility.
Override:
Always

iterator

public Iterator iterator(DataBasket db,
                         boolean fForEdit)
Return an iterator of all items in the Catalog.

The iterator will conceptually call get(java.lang.String, data.DataBasket, boolean) for each CatalogItem, using the given parameters.

Parameters:
db - the DataBasket that defines visibility.
fForEdit - if true, the items are retrieved for editing. VetoException will be converted into UnsupportedOperationExceptions.
Override:
Always

keySet

public Set keySet(DataBasket db)
Get a set of all keys currently in the Catalog.

This will retrieve a static set that gives the state of the Catalog at the time of the call.

Parameters:
db - the DataBasket used to determine visibility of elements.
Override:
Always

size

public int size(DataBasket db)
Calculate the size of the Catalog. I.e. count the CatalogItems that are visible to users of the given DataBasket.

Parameters:
db - the DataBasket used to determine visibility.
Override:
Always

SalesPoint Framework v3.1