data
Interface DataBasket

All Superinterfaces:

Serializable

All Known Subinterfaces:

ListenableDataBasket

All Known Implementing Classes:

DataBasketImpl

public interface DataBasket

extends Serializable

An object collecting information about a activities on data objects in a shop.

The DataBasket is used in the manner of a "transcation handle", i.e. all actions with data containers (e.g. Catalogs, Stocks etc.) are processed relative to this DataBasket. The following rules apply:

• Adding items to data containers:
  All adding of items is only temporary until an explicit commit is performed on the DataBasket. Freshly added items are only visible to the owner of the DataBasket relative to which they were added. However, there may be cases when the temporary adding of an entry to a data container prevents other entries (e.g., of the same key) from being added. This is, for example, the case with Catalogs, because there can always be at most one CatalogItem for any given key in any given Catalog. The resulting conflict is conventionally resolved by throwing a DataBasketConflictException that also states the reason for the conflict in its detail message.
• Removing items from a data container:
  All removing of items is only temporary until an explicit commit is performed on the DataBasket. Usually, adding an item just removed using the same DataBasket, will roll back the activity. However, this is container specific behavior that may differ between containers.
• Looking at an item from a data container:
  Only items that are really in the container, plus items that have been added using the same DataBasket are visible. Usually there are two different modes of looking at an item: just for reading or for editing the item. These differ in several ways:
  1. There is no guarantee that an item just got for reading will still be in the container the next time you look. For items that you got for editing purposes this guarantee can be given.
  2. Items you got for editing will no longer be visible for users of different DataBaskets. This is the reason why the former assertion can be given. The items will become visible again, when a commit is performed.
  3. Although you can edit items that you just got for reading, by doing so, you loose the ability to undo the action and, because others can see the changing in progress, you risk inconsistencies in your data. Therefore, such behavior is considered bad style and is not recommended.

DataBaskets provide the capability to undo whole blocks of activities without having to consider the single activities. To do so, you simply call one of the rollback methods on the DataBasket relative to which the activities where performed. On the other hand, you will have to call commit to fix changes and make them visible to owners of other DataBaskets. Once commited, a change can no longer be rolled back.

Additionally, you can define subsections in a DataBasket, which can be commited or rolled back individually and independently. Also you can commit or rollback an arbitrary subset of elements by defining a selecting condition. These operations are, however, optional, and may not be implemented in all concrete implementations of the DataBasket interface.

In addition to their useability as "transaction handles", DataBaskets can be inspected, thus allowing for applications where customers can roam the Shop freely, deciding to take things and to put them back, and will only be charged at the end, based on the contents of their DataBasket. To implement such strategies, see iterator(data.DataBasketCondition), sumBasket(data.DataBasketCondition, data.BasketEntryValue, data.Value).

DataBaskets allow for a LogContext to be defined. Operations on the DataBasket can be logged using the current LogContext of the DataBasket. You can decide which actions are being logged by setting the appropriate parameter in a call to setLogMode(int).

Since:

v2.0

Author:

Steffen Zschaler

Field Summary

static String	DEFAULTSUBBASKET_NAME The name of the default subbasket.
static int	LOG_MODE_ALL Log mode constant.
static int	LOG_MODE_COMMITS_ONLY Log mode constant.
static int	LOG_MODE_NONE Log mode constant.
static int	LOG_MODE_ROLLBACKS_ONLY Log mode constant.

Method Summary

void	commit() Commit the entire contents of the DataBasket.
void	commit(DataBasketCondition dbc) Commit all items that match the given condition.
void	commitCurrentSubBasket() Commit the contents of the current subbasket.
void	commitSubBasket(String sName) Commit the contents of the named subbasket.
boolean	contains(DataBasketCondition dbc) Return true if the DataBasket contains an entry that matches the condition.
void	exchange(DataBasketEntry dbeOrg, DataBasketEntry dbeNew) Exchange a DataBasketEntry existing in the DataBasket with a new one.
DataBasketEntry	get(DataBasketCondition dbc) Get the first entry found that matches the given condition.
int	getLogMode() Return the current log mode of the DataBasket.
Iterator	iterator(DataBasketCondition dbc) Iterate the contents of this DataBasket.
void	put(DataBasketEntry dbe) Put an entry into the DataBasket's current subbasket.
void	rollback() Roll back the entire contents of the DataBasket.
void	rollback(DataBasketCondition dbc) Roll back all items that match the given condition.
void	rollbackCurrentSubBasket() Roll back the contents of the current subbasket.
void	rollbackSubBasket(String sName) Roll back the contents of the named subbasket.
void	setCurrentSubBasket(String sName) Set the current subbasket.
LogContext	setLogContext(LogContext lcNew) Set the log context for this DataBasket.
int	setLogMode(int nLogMode) Set the log mode for this DataBasket.
Iterator	subBasketIterator(String sName, DataBasketCondition dbc) Iterate the contents of a given SubBasket.
Value	sumBasket(DataBasketCondition dbc, BasketEntryValue bev, Value vInit) Sum up the values of all items in this DataBasket that match the condition.
Value	sumCurrentSubBasket(DataBasketCondition dbc, BasketEntryValue bev, Value vInit) Sum up the values of all items in the current subbasket that match the condition.
Value	sumSubBasket(String sName, DataBasketCondition dbc, BasketEntryValue bev, Value vInit) Sum up the values of all items in the given subbasket that match the condition.

Field Detail

DEFAULTSUBBASKET_NAME

public static final String DEFAULTSUBBASKET_NAME

The name of the default subbasket.

Every DataBasket has at least one SubBasket, that is used as long as no other SubBasket has been specified. This is the default subbasket and its name is stored in this constant.

See Also:

setCurrentSubBasket(java.lang.String), Constant Field Values

LOG_MODE_NONE

public static final int LOG_MODE_NONE

Log mode constant.

See Also:

setLogMode(int), getLogMode(), Constant Field Values

LOG_MODE_ALL

public static final int LOG_MODE_ALL

Log mode constant.

See Also:

setLogMode(int), getLogMode(), Constant Field Values

LOG_MODE_COMMITS_ONLY

public static final int LOG_MODE_COMMITS_ONLY

Log mode constant.

See Also:

setLogMode(int), getLogMode(), Constant Field Values

LOG_MODE_ROLLBACKS_ONLY

public static final int LOG_MODE_ROLLBACKS_ONLY

Log mode constant.

See Also:

setLogMode(int), getLogMode(), Constant Field Values

Method Detail

commit

public void commit()

Commit the entire contents of the DataBasket.

All temporarily added or removed items will be finally added or removed from their respective containers. All items got for editing will be put back into their container and any changes to them will be fixed. All items that have only been visible to users of this DataBasket will henceforward be visible for every user. Every item that was committed will be removed from the DataBasket and, thus, the DataBasket will be empty.

See Also:

rollback()

Override:

Always

rollback

public void rollback()

Roll back the entire contents of the DataBasket.

All temporarily added or removed items will be removed from, or put back into, their respective containers, resp. All changes that where made to items that were edited will be undone. All items will be restored to their original visibility. Every item that was rolled back will be removed from the DataBasket and, thus, the DataBasket will be empty.

See Also:

commit()

Override:

Always

commitSubBasket

public void commitSubBasket(String sName)

Commit the contents of the named subbasket.

All items in the named subbasket will be commited, and the subbasket will be empty afterwards. Any item that is not in the subbasket will not be touched, unless dependencies between the items require so. For a description of the commit process refer to commit().

This is an optional operation that does not need to be supported by concrete implementations of the interface. To indicate that this method is not supported, such implementations must throw an UnSupportedOperationException.

Parameters:

sName - the name of the subbasket to be commited.

Throws:

UnsupportedOperationException - to indicate that this method is not implemented in a certain implementation of the interface.

See Also:

setCurrentSubBasket(java.lang.String), rollbackSubBasket(java.lang.String)

Override:

Always

commitCurrentSubBasket

public void commitCurrentSubBasket()

Commit the contents of the current subbasket.

All items in the current subbasket will be commited, and the subbasket will be empty afterwards. Any item that is not in the subbasket will not be touched, unless dependencies between the items require so. For a description of the commit process refer to commit().

This is an optional operation that does not need to be supported by concrete implementations of the interface. To indicate that this method is not supported, such implementations must throw an UnSupportedOperationException.

Throws:

UnsupportedOperationException - to indicate that this method is not implemented in a certain implementation of the interface.

See Also:

setCurrentSubBasket(java.lang.String), rollbackCurrentSubBasket()

Override:

Always

rollbackSubBasket

public void rollbackSubBasket(String sName)

Roll back the contents of the named subbasket.

All items in the named subbasket will be rolled back, and the subbasket will be empty afterwards. Any item that is not in the subbasket will not be touched, unless dependencies between the items require so. For a description of the rollback process refer to rollback().

This is an optional operation that does not need to be supported by concrete implementations of the interface. To indicate that this method is not supported, such implementations must throw a UnSupportedOperationException.

Parameters:

sName - the name of the subbasket to be rolled back.

Throws:

UnsupportedOperationException - to indicate that this method is not implemented in a certain implementation of the interface.

See Also:

setCurrentSubBasket(java.lang.String), commitSubBasket(java.lang.String)

Override:

Always

rollbackCurrentSubBasket

public void rollbackCurrentSubBasket()

Roll back the contents of the current subbasket.

All items in the current subbasket will be rolled back, and the subbasket will be empty afterwards. Any item that is not in the subbasket will not be touched, unless dependencies between the items require so. For a description of the rollback process refer to rollback().

This is an optional operation that does not need to be supported by concrete implementations of the interface. To indicate that this method is not supported, such implementations must throw an UnSupportedOperationException.

Throws:

UnsupportedOperationException - to indicate that this method is not implemented in a certain implementation of the interface.

See Also:

setCurrentSubBasket(java.lang.String), commitCurrentSubBasket()

Override:

Always

commit

public void commit(DataBasketCondition dbc)

Commit all items that match the given condition.

All items matching the condition will be commited and removed from the DataBasket. No other item will be touched, unless dependencies between the items require so. For a description of the commit process refer to commit().

This is an optional operation that does not need to be supported by concrete implementations of the interface. To indicate that this method is not supported, such implementations must throw an UnSupportedOperationException.

Throws:

UnsupportedOperationException - to indicate that this method is not implemented in a certain implementation of the interface.

Override:

Always

rollback

public void rollback(DataBasketCondition dbc)

Roll back all items that match the given condition.

All items matching the condition will be rolled back and removed from the DataBasket. No other item will be touched, unless dependencies between the items require so. For a description of the rollback process refer to rollback().

This is an optional operation that does not need to be supported by concrete implementations of the interface. To indicate that this method is not supported, such implementations must throw an UnSupportedOperationException.

Throws:

UnsupportedOperationException - to indicate that this method is not implemented in a certain implementation of the interface.

Override:

Always

setCurrentSubBasket

public void setCurrentSubBasket(String sName)

Set the current subbasket.

If no SubBasket of the given name exists, an empty one will be created and made the current SubBasket.

All put operations put entries into the current subbasket of a DataBasket.

SubBaskets can be used to define sets of independently commitable (or rollbackable, resp.) entries in a DataBasket. Thus you can build something similar to nested Transactions or SafePoints. However, when using SubBaskets, it is at least partly your responsibility to make sure, there are no dependencies between the contents of different SubBaskets. If you don't, or if you do not take measures to resolve such situations, using SubBaskets may result in inconsistent data in your system.

This is an optional operation that does not need to be supported by concrete implementations of the interface. To indicate that this method is not supported, such implementations must throw an UnSupportedOperationException. Implementations may also choose to implement this method (and any other methods related to SubBaskets) in part, i.e. with more rigid preconditions defined. Such implementations would still throw an UnsupportedOperationException if the preconditions are not met. For example, an implementation based on relational databases might want to allow LIFO usage of SubBaskets as this can be modelled by nesting database transactions. It will throw an exception, however, when a client tries to use SubBaskets in a more random way.

Throws:

UnsupportedOperationException - to indicate that this method is not implemented in a certain implementation of the interface.

See Also:

commitSubBasket(java.lang.String), rollbackSubBasket(java.lang.String), commitCurrentSubBasket(), rollbackCurrentSubBasket(), DEFAULTSUBBASKET_NAME

Override:

Always

iterator

public Iterator iterator(DataBasketCondition dbc)

Iterate the contents of this DataBasket.

The iterator will iterate the entire contents of the DataBasket, but will return only such items, that match the given condition.

Parameters:

dbc - a condition, that items must match to be returned by the iterator.

Override:

Always

subBasketIterator

public Iterator subBasketIterator(String sName,
                                  DataBasketCondition dbc)

Iterate the contents of a given SubBasket.

The iterator will iterate all items in the given SubBasket that match the given condition.

Parameters:

sName - the name of the SubBasket. A NullPointerException may be thrown if this SubBasket does not exist.

dbc - the condition that must be matched by items that are to be returned by the iterator

Override:

Always

sumBasket

public Value sumBasket(DataBasketCondition dbc,
                       BasketEntryValue bev,
                       Value vInit)

Sum up the values of all items in this DataBasket that match the condition.

Parameters:

dbc - the condition that must be matched by all entries that are to be used in the process of adding up the DataBasket.

bev - an object helping in determining the value of a single entry.

vInit - the value that is to be used for adding up. All adding is performed by calling Value.addAccumulating(data.Value) on this object.

Returns:

the sum in vInit.

Override:

Always

sumSubBasket

public Value sumSubBasket(String sName,
                          DataBasketCondition dbc,
                          BasketEntryValue bev,
                          Value vInit)

Sum up the values of all items in the given subbasket that match the condition.

Parameters:

sName - the name of the subbasket whose items are to be used.

dbc - the condition that must be matched by all entries that are to be used in the process of adding up the DataBasket.

bev - an object helping in determining the value of a single entry.

vInit - the value that is to be used for adding up. All adding is performed by calling Value.addAccumulating(data.Value) on this object.

Returns:

the sum in vInit.

Override:

Always

sumCurrentSubBasket

public Value sumCurrentSubBasket(DataBasketCondition dbc,
                                 BasketEntryValue bev,
                                 Value vInit)

Sum up the values of all items in the current subbasket that match the condition.

Parameters:

dbc - the condition that must be matched by all entries that are to be used in the process of adding up the DataBasket.

bev - an object helping in determining the value of a single entry.

vInit - the value that is to be used for adding up. All adding is performed by calling Value.addAccumulating(data.Value) on this object.

Returns:

the sum in vInit.

Override:

Always

contains

public boolean contains(DataBasketCondition dbc)

Return true if the DataBasket contains an entry that matches the condition. The entire DataBasket will be searched.

Parameters:

dbc - the condition to be matched.

Returns:

whether or not the DataBasket currently contains such an entry.

Override:

Always

get

public DataBasketEntry get(DataBasketCondition dbc)

Get the first entry found that matches the given condition. The entire DataBasket will be searched.

In this context, "first" does not mean the first entry added or anything similar; it simply refers to the first entry found when searching the DataBasket. Although this may be the first entry added, no assertions are given.

Parameters:

dbc - the condition to be matched.

Returns:

an entry matching the condition, if any.

Override:

Always

put

public void put(DataBasketEntry dbe)

Put an entry into the DataBasket's current subbasket.

This method is vital for the correct functioning of the DataBasket and, therefore, must never be called directly. Instead, call appropriate methods in the data containers (Stock, Catalog, etc.) you use. These will in turn call put on the DataBasket, thus making sure, that the DataBasket contains valid information only at all times.

The put method will take the given entry as is and put it into the current subbasket. This is to say, that the caller is responsible for correctly setting up the fields in the entry - so that the information stored is meaningful to the client. In particular, resolving put after remove or remove after put of the same object and with regard to the same container is the responsibility of the caller.

Parameters:

dbe - the entry to be put into the DataBasket.

Override:

Always

exchange

public void exchange(DataBasketEntry dbeOrg,
                     DataBasketEntry dbeNew)

Exchange a DataBasketEntry existing in the DataBasket with a new one.

This method is vital for the correct functioning of the DataBasket and, therefore, must never be called directly. Instead, call appropriate methods in the data containers (Stock, Catalog, etc.) you use. These will in turn call exchange on the DataBasket, thus making sure, that the DataBasket contains valid information only at all times.

Parameters:

dbeOrg - the original DataBasketEntry, to be replaced. If the original entry is not found in the DataBasket, exchange() is equivalent to put (dbeNew).

dbeNew - the replacement.

Override:

Always

setLogContext

public LogContext setLogContext(LogContext lcNew)

Set the log context for this DataBasket.

All operations as defined through setLogMode(int) will be logged using the given log context. If the current log context is null no logging of any kind will occur.

Parameters:

lcNew - the new log context

Returns:

the previous log context, if any.

Override:

Always

setLogMode

public int setLogMode(int nLogMode)

Set the log mode for this DataBasket.

The current log mode decides what operations on the DataBasket are being logged. The default value is LOG_MODE_NONE, indicating that no logging occurs. Other possibilities are:

• LOG_MODE_ALL All operations on the DataBasket are being logged.
• LOG_MODE_COMMITS_ONLY Only commits are being logged. There will be one entry for each single step in the commit process.
• LOG_MODE_ROLLBACKS_ONLY Only rollbacks are being logged. There will be one entry for each single step in the rollback process.

For details on the concrete implementation for log entries, please refer to the concrete implementation of the DataBasket.

Parameters:

nLogMode - the new log mode.

Returns:

the previous log mode.

Override:

Always

getLogMode

public int getLogMode()

Return the current log mode of the DataBasket. For information on the possible values and their meaning, please refer to setLogMode(int).

Override:

Always