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