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    }