001 package sale;
002
003 import java.io.Serializable;
004
005 import java.util.*;
006
007 import users.User;
008
009 /**
010 * A node in the graph representing the deterministic finite automaton implementing a
011 * {@link SaleProcess process}.
012 *
013 * <p>Gates are the points at which user communication and control flow branching take place. A process can
014 * stay at a gate as long as may be necessary, but must be aware that it can be interrupted and
015 * suspended at any time. In contrast, a process can never be interrupted when in a {@link Transition}, but
016 * transitions must be very short and must not comprise any user communication.</p>
017 *
018 * <p>As every process begins and ends at a gate, there are special gates for special occasions. See
019 * the <code>getXXXGate()</code> methods in {@link SaleProcess}.</p>
020 *
021 * @author Steffen Zschaler
022 * @version 2.0 27/05/1999
023 * @since v2.0
024 */
025 public interface Gate extends Serializable {
026
027 /**
028 * Determine the next Transition.
029 *
030 * <p>This is the key (and sole) method of the gate. By entering this method, the calling process
031 * enters the gate. This method must do anything that is necessary to determine the next transition
032 * and must then return this transition. It is invalid, to return a <code>null</code> transition,
033 * except in the special cases noted below.</p>
034 *
035 * <p>The method must be interruptible by calls to {@link java.lang.Thread#interrupt()} on the executing
036 * thread and it must propagate these interrupts as a InterruptedException. In this case it is obviously no
037 * problem, if the method returns a <code>null</code> transition.</p>
038 *
039 * <p>Also, if any other exception causes the method to be left, or in the case of an explicit call
040 * to the process' {@link SaleProcess#error} method, the result may be <code>null</code>.</p>
041 *
042 * @override Always
043 *
044 * @param pOwner the process that entered the gate and triggered the method.
045 * @param usr the user currently active in the process' {@link ProcessContext}
046 *
047 * @return the Transition to be performed after leaving the gate.
048 *
049 * @exception InterruptedException if an interrupt ocurred while at the gate.
050 */
051 public Transition getNextTransition(SaleProcess pOwner, User usr) throws InterruptedException;
052 }