package data.swing;

import data.*;

import java.io.Serializable;

/**
  * Strategy grouping {@link DataBasketEntry DataBasketEntries} together for display.
  *
  * <p>When displaying the contents of a DataBasket, there may be several DataBasketEntries describing what to
  * the user should be displayed as conceptually one operation. For example, there may be several entries
  * noting that individual amounts of items of the same key have been taken from a CountingStock. To the user
  * you would probably want to display only the net result of this, i.e. one entry giving the total number of
  * items of the given key that were removed from the Stock. In general, this is were you provide a
  * DataBasketEntryGrouper to group together entries that conceptually represent one entry. For cases like in
  * the above example you can use the predefined {@link CountingStockDBEGrouper}.</p>
  *
  * @author Steffen Zschaler
  * @version 2.0 23/08/1999
  * @since v2.0
  */
public interface DataBasketEntryGrouper extends Serializable {

  /**
    * Return true to indicate that the two entries are conceptually part of one more general entry and that
    * they must be grouped together.
    *
    * <p>The relation defined hereby is an equality relation, i.e. it must be reflexive, symmetric and
    * transitive. All tuples <code>(dbe1, dbe2)</code> must be evaluated to either true or false, i.e. there
    * must be no exceptions thrown by this method.</p>
    *
    * @override Always
    */
  public boolean canGroup (DataBasketEntry dbe1, DataBasketEntry dbe2);

  /**
    * Group the two given DataBaskeEntries and return the resulting, more general entry.
    *
    * <p>The resulting entry must be groupable with any DataBasketEntry with which <code>dbe1</code> or
    * <code>dbe2</code> are groupable.</p>
    *
    * @override Always
    */
  public DataBasketEntry group (DataBasketEntry dbe1, DataBasketEntry dbe2);
}