package data;

/**
  * An entry in a {@link DataBasket}.
  *
  * <p>DataBasketEntries describe an object that was removed from a data container, put into a data container
  * or moved between data containers. They know about the {@link #getSource source} and
  * {@link #getDestination destination} of the operation and about the {@link #getValue object} that was moved.
  * Additionally, they know how to {@link #commit commit} or {@link #rollback rollback} the operation.</p>
  *
  * <p>For reasons of efficency, DataBasketEntries are stored in a hierarchical structure, with three levels:
  * categories, these are selected via the DataBasketEntry's {@link #getMainKey main key}; subcategories,
  * selected via the DataBasketEntry's {@link #getSecondaryKey secondary key}; and the items selected by the
  * DataBasketEntry's {@link #getValue value}.</p>
  *
  * @author Steffen Zschaler
  * @version 2.0 14/06/1999
  * @since v2.0
  */
public interface DataBasketEntry extends DataBasketKeys {

  /**
    * Roll back the operation described by the DataBasketEntry.
    *
    * @override Always
    */
  public void rollback();

  /**
    * Commit the operation described by the DataBasketEntry.
    *
    * @override Always
    */
  public void commit();

  /**
    * Notification that the DataBasketEntry was put into a DataBasket.
    *
    * @param dbOwner the DataBasket that owns this DataBasketEntry. Can be <code>null</code>.
    *
    * @override Always
    */
  public void setOwner (DataBasket dbOwner);

  /**
    * Return the DataBasket containing this DataBasketEntry. Initially <code>null</code>. Once
    * {@link #setOwner} has been called, always returns the last value of the <code>dbOwner</code>
    * parameter passed to <code>setOwner</code>.
    *
    * @return the DataBasket containing this DataBasketEntry.
    */
  public DataBasket getOwner();

  /**
    * Get the source of the operation described by the DataBasketEntry.
    *
    * @override Always
    */
  public DataBasketEntrySource getSource();

  /**
    * Get the destination of the operation described by the DataBasketEntry.
    *
    * @override Always
    */
  public DataBasketEntryDestination getDestination();

  /**
    * Get the object moved by the operation described by the DataBasketEntry.
    *
    * @override Always
    */
  public Object getValue();

  /**
    * Get the DataBasketEntry's main key.
    *
    * @override Always
    */
  public String getMainKey();

  /**
    * Get the DataBasketEntry's secondary key.
    *
    * @override Always
    */
  public String getSecondaryKey();

  /**
    * Return false as long as no complete commit or rollback has been issued for this
    * DataBasketEntry. Returning true will lead to the DataBasketEntry being removed from the
    * DataBasket as soon as convenient. DataBasketEntries that return true from this method
    * are, however, guaranteed to no longer participate in any iterations of the DataBasket.
    *
    * @override Always
    */
  public boolean isHandled();
}