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