001 package data.swing;
002
003 import data.*;
004
005 import java.io.Serializable;
006
007 /**
008 * Strategy grouping {@link DataBasketEntry DataBasketEntries} together for display.
009 *
010 * <p>When displaying the contents of a DataBasket, there may be several DataBasketEntries describing what to
011 * the user should be displayed as conceptually one operation. For example, there may be several entries
012 * noting that individual amounts of items of the same key have been taken from a CountingStock. To the user
013 * you would probably want to display only the net result of this, i.e. one entry giving the total number of
014 * items of the given key that were removed from the Stock. In general, this is were you provide a
015 * DataBasketEntryGrouper to group together entries that conceptually represent one entry. For cases like in
016 * the above example you can use the predefined {@link CountingStockDBEGrouper}.</p>
017 *
018 * @author Steffen Zschaler
019 * @version 2.0 23/08/1999
020 * @since v2.0
021 */
022 public interface DataBasketEntryGrouper extends Serializable {
023
024 /**
025 * Return true to indicate that the two entries are conceptually part of one more general entry and that
026 * they must be grouped together.
027 *
028 * <p>The relation defined hereby is an equality relation, i.e. it must be reflexive, symmetric and
029 * transitive. All tuples <code>(dbe1, dbe2)</code> must be evaluated to either true or false, i.e. there
030 * must be no exceptions thrown by this method.</p>
031 *
032 * @override Always
033 */
034 public boolean canGroup(DataBasketEntry dbe1, DataBasketEntry dbe2);
035
036 /**
037 * Group the two given DataBaskeEntries and return the resulting, more general entry.
038 *
039 * <p>The resulting entry must be groupable with any DataBasketEntry with which <code>dbe1</code> or
040 * <code>dbe2</code> are groupable.</p>
041 *
042 * @override Always
043 */
044 public DataBasketEntry group(DataBasketEntry dbe1, DataBasketEntry dbe2);
045 }