source: protocol/src/main/java/geniusweb/protocol/session/mopac/phase/Phase.java@ 21

package geniusweb.protocol.session.mopac.phase;

import java.util.Set;

import geniusweb.actions.Action;
import geniusweb.actions.PartyId;
import geniusweb.inform.Inform;
import geniusweb.protocol.ProtocolException;
import geniusweb.protocol.session.mopac.PartyStates;
import geniusweb.voting.VotingEvaluator;

/**
 * A Phase is a part of the round structure. In each round parties have to take
 * multiple actions. Each action is part of a phase.
 *
 */
public interface Phase {
        public static final Long PHASE_MAXTIME = 30000l; // 30sec
        public static final Long PHASE_MINTIME = 100l; // 100 millisec

        /**
         * Handle an actor's action. If a {@link ProtocolException} occurs, this is
         * handled by updating the PartyStates
         * 
         * @param prevPhases the list of all previous phases
         * @param actor      the real actor
         * @param action     the action submitted by actor, which this phase can
         *                   really handle.
         * @param now        the current time
         * @return new VotingPhase
         */
        public Phase with(PartyId actor, Action action, long now);

        /**
         * 
         * @param e a {@link ProtocolException}
         * @return new Phase with a party disabled because it violated a protocol eg
         *         breaking a websocket link.
         */
        public Phase with(ProtocolException e);

        /**
         * 
         * @return the inform object to send to all parties at start of phase.
         */
        public Inform getInform();

        /**
         * 
         * @param now the current time
         * @return true iff past deadline or no more actions are allowed anyway.
         *         (which usually means, all parties have done exactly one act).
         *         Notice, this is the main reason that it is desirable to require
         *         all parties to act exactly once in each phase. Without such a
         *         rule, the protocol will always have to wait till the deadline.
         */
        public boolean isFinal(long now);

        /**
         * 
         * @return finished state. That means, all parties that did not act have
         *         been kicked, new agreements have been computed, etc.
         */
        public Phase finish();

        /**
         * Determines the next phase. Resets the actions field. Can only be called
         * after {@link #finish()}
         * 
         * @param now      the curren time
         * @param duration the max duration of the next phase. Must be between
         *                 {@link #PHASE_MINTIME} and {@link #PHASE_MAXTIME}. Also
         *                 make sure that now+duration is at most at the total
         *                 negotiation deadline.
         * @return the next phase, or null if negotiation is complete.
         */
        public Phase next(long now, long duration);

        /**
         * Get the voting evaluator
         * 
         * @return
         */
        public VotingEvaluator getEvaluator();

        /**
         * 
         * @return time (ms since 1970) at which phase ends. The phase may end
         *         before, but never after this.
         */
        public long getDeadline();

        /**
         * @param now the current time
         * 
         * @return the party states. Notice that someone must call
         *         {@link PartyStates#finish(Set)} if passed the deadline.
         */
        public PartyStates getPartyStates();

}