package sale;

import java.io.Serializable;

import java.util.*;

import users.User;

/**
  * An edge in the graph representing the deterministic finite automaton implementing a
  * {@link SaleProcess process}.
  *
  * <p>Transitions are where the actual work of the process is done. Although very short, Transitions will be
  * the parts of your processes that take the real hard design bits. Transitions should be rather short, in
  * particular they must not comprise user communication or other potentially infinite activities. As a balance,
  * transitions are guaranteed never to be interrupted by the Framework.</p>
  *
  * <p>In contrast, {@link sale.Gate gates} are the points at which user communication can take place. A
  * process can stay at a gate as long as may be necessary, but must be aware that it can be interrupted and
  * suspended at any time.</p>
  *
  * @author Steffen Zschaler
  * @version 2.0 27/05/1999
  * @since v2.0
  */
public interface Transition extends Serializable {

  /**
    * Actually perform the transition.
    *
    * <p>This is the key method of the Transition and should contain any code that is necessary to
    * transit from one gate to another. The new gate that should be entered after this transition must
    * be returned by this method. <code>null</code> is a valid return value and will stop the calling
    * process.</p>
    *
    * <p>This method must not trigger any user communication or any other potentially infinite
    * operation. Potentially infinite means, in this context, that the end of the operation cannot be
    * planned ahead, but can potentially be at any time in the future, usually further in the future,
    * possibly even never. An example for potentially infinite operations are all operations that
    * comprise user communication and, therefore, the potential that the user just &quot;forgets&quot;
    * to respond. As transitions are guaranteed to be uninteruptible by the Framework, but processes are
    * to be interruptible, transitions must, as a consequence, be very short and not comprise any
    * potentially infinite operations.</p>
    *
    * @override Always
    *
    * @param pOwner the process that triggered the Transition
    * @param usr the user currently active in the process' {@link sale.ProcessContext}
    *
    * @return the gate to enter after this transition has completed. <code>null</code> is a valid value,
    * causing the calling process to stop.
    */
  public Gate perform (SaleProcess pOwner, User usr);
}