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 }