001    package sale;
002    
003    import java.io.Serializable;
004    
005    import java.util.*;
006    
007    import users.User;
008    
009    /**
010     * An edge in the graph representing the deterministic finite automaton implementing a
011     * {@link SaleProcess process}.
012     *
013     * <p>Transitions are where the actual work of the process is done. Although very short, Transitions will be
014     * the parts of your processes that take the real hard design bits. Transitions should be rather short, in
015             * particular they must not comprise user communication or other potentially infinite activities. As a balance,
016     * transitions are guaranteed never to be interrupted by the Framework.</p>
017     *
018     * <p>In contrast, {@link sale.Gate gates} are the points at which user communication can take place. A
019     * process can stay at a gate as long as may be necessary, but must be aware that it can be interrupted and
020     * suspended at any time.</p>
021     *
022     * @author Steffen Zschaler
023     * @version 2.0 27/05/1999
024     * @since v2.0
025     */
026    public interface Transition extends Serializable {
027    
028        /**
029         * Actually perform the transition.
030         *
031         * <p>This is the key method of the Transition and should contain any code that is necessary to
032         * transit from one gate to another. The new gate that should be entered after this transition must
033         * be returned by this method. <code>null</code> is a valid return value and will stop the calling
034         * process.</p>
035         *
036         * <p>This method must not trigger any user communication or any other potentially infinite
037         * operation. Potentially infinite means, in this context, that the end of the operation cannot be
038         * planned ahead, but can potentially be at any time in the future, usually further in the future,
039         * possibly even never. An example for potentially infinite operations are all operations that
040         * comprise user communication and, therefore, the potential that the user just "forgets"
041         * to respond. As transitions are guaranteed to be uninteruptible by the Framework, but processes are
042         * to be interruptible, transitions must, as a consequence, be very short and not comprise any
043         * potentially infinite operations.</p>
044         *
045         * @override Always
046         *
047         * @param pOwner the process that triggered the Transition
048         * @param usr the user currently active in the process' {@link sale.ProcessContext}
049         *
050         * @return the gate to enter after this transition has completed. <code>null</code> is a valid value,
051         * causing the calling process to stop.
052         */
053        public Gate perform(SaleProcess pOwner, User usr);
054    }