SalesPoint Framework v3.1

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:

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:

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

SalesPoint Framework v3.1