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