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    }