package sale;

import java.io.Serializable;

import java.util.*;

import users.User;

/**
  * A node in the graph representing the deterministic finite automaton implementing a
  * {@link SaleProcess process}.
  *
  * <p>Gates are the points at which user communication and control flow branching 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. In contrast, a process can never be interrupted when in a {@link Transition}, but
  * transitions must be very short and must not comprise any user communication.</p>
  *
  * <p>As every process begins and ends at a gate, there are special gates for special occasions. See
  * the <code>getXXXGate()</code> methods in {@link SaleProcess}.</p>
  *
  * @author Steffen Zschaler
  * @version 2.0 27/05/1999
  * @since v2.0
  */
public interface Gate extends Serializable {

  /**
    * Determine the next Transition.
    *
    * <p>This is the key (and sole) method of the gate. By entering this method, the calling process
    * enters the gate. This method must do anything that is necessary to determine the next transition
    * and must then return this transition. It is invalid, to return a <code>null</code> transition,
    * except in the special cases noted below.</p>
    *
    * <p>The method must be interruptible by calls to {@link java.lang.Thread#interrupt()} on the executing
    * thread and it must propagate these interrupts as a InterruptedException. In this case it is obviously no
    * problem, if the method returns a <code>null</code> transition.</p>
    *
    * <p>Also, if any other exception causes the method to be left, or in the case of an explicit call
    * to the process' {@link SaleProcess#error} method, the result may be <code>null</code>.</p>
    *
    * @override Always
    *
    * @param pOwner the process that entered the gate and triggered the method.
    * @param usr the user currently active in the process' {@link ProcessContext}
    *
    * @return the Transition to be performed after leaving the gate.
    *
    * @exception InterruptedException if an interrupt ocurred while at the gate.
    */
  public Transition getNextTransition (SaleProcess pOwner, User usr)
    throws InterruptedException;
}