1 | package geniusweb.protocol;
|
---|
2 |
|
---|
3 | import com.fasterxml.jackson.annotation.JsonAutoDetect;
|
---|
4 | import com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility;
|
---|
5 | import com.fasterxml.jackson.annotation.JsonSubTypes;
|
---|
6 | import com.fasterxml.jackson.annotation.JsonSubTypes.Type;
|
---|
7 | import com.fasterxml.jackson.annotation.JsonTypeInfo;
|
---|
8 |
|
---|
9 | import geniusweb.connection.ConnectionFactory;
|
---|
10 | import geniusweb.deadline.Deadline;
|
---|
11 | import geniusweb.events.CurrentState;
|
---|
12 | import geniusweb.events.ProtocolEvent;
|
---|
13 | import geniusweb.protocol.partyconnection.ProtocolToPartyConnFactory;
|
---|
14 | import geniusweb.protocol.session.SessionProtocol;
|
---|
15 | import geniusweb.protocol.session.SessionState;
|
---|
16 | import geniusweb.protocol.tournament.TournamentProtocol;
|
---|
17 | import geniusweb.references.PartyWithProfile;
|
---|
18 | import geniusweb.references.ProtocolRef;
|
---|
19 | import geniusweb.references.Reference;
|
---|
20 | import tudelft.utilities.listener.Listenable;
|
---|
21 |
|
---|
22 | /**
|
---|
23 | * Abstract interface to all negotiation protocols, both single session and
|
---|
24 | * tournaments. Generally a protocol handles events on the provided connections
|
---|
25 | * according to the rules set by the protocol. The rules are explained by
|
---|
26 | * {@link #getDescription()}. A protocol reports the progress through its
|
---|
27 | * {@link Listenable} interface. <br>
|
---|
28 | * <h2>General information</h2>
|
---|
29 | *
|
---|
30 | * A protocol is mutable because the incoming connections cause state changes.
|
---|
31 | * But it is recommended to push changing properties into the state so that the
|
---|
32 | * complete state can be recovered and analysed.
|
---|
33 | * <p>
|
---|
34 | * Because a protocol contains an internal state, it can be used only once.
|
---|
35 | * <p>
|
---|
36 | * The protocol can emit a {@link CurrentState} event at any time. It should do
|
---|
37 | * so at least once, to log the final outcome of the nego.
|
---|
38 | * <p>
|
---|
39 | *
|
---|
40 | * Normally the constructor will receive a {@link ConnectionFactory} through
|
---|
41 | * which it can resolve received {@link Reference}s. <br>
|
---|
42 | * First call to instances <b>must be</b>
|
---|
43 | * {@link #start(ProtocolToPartyConnFactory)}.
|
---|
44 | *
|
---|
45 | * <h2>Ensure time deadline</h2>
|
---|
46 | *
|
---|
47 | * The protocol also needs to keep an eye on the deadline and take appropriate
|
---|
48 | * actions when the deadline is reached. <br>
|
---|
49 | * <p>
|
---|
50 | * All protocol implementations must ensure that the deadline is kept and that
|
---|
51 | * the session ends at the agreed time {@link Deadline#getDuration()}. This is
|
---|
52 | * to ensure that the negotiation ends and resources are freed up at or before
|
---|
53 | * some known time.
|
---|
54 | *
|
---|
55 | */
|
---|
56 | @JsonAutoDetect(fieldVisibility = Visibility.ANY, getterVisibility = Visibility.NONE, setterVisibility = Visibility.NONE, isGetterVisibility = Visibility.NONE)
|
---|
57 | @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.WRAPPER_OBJECT)
|
---|
58 | @JsonSubTypes({ @Type(value = SessionProtocol.class),
|
---|
59 | @Type(value = TournamentProtocol.class) })
|
---|
60 |
|
---|
61 | public interface NegoProtocol extends Listenable<ProtocolEvent> {
|
---|
62 | /**
|
---|
63 | * Start the protocol: make connection with parties and follow the protocol.
|
---|
64 | * This must be called once and should be the first call after construction.
|
---|
65 | * <p>
|
---|
66 | *
|
---|
67 | * The protocol implementation should not start any real work (eg making
|
---|
68 | * connections) before this point. That also allows us to construct protocol
|
---|
69 | * instances just to fetch the description.
|
---|
70 | * <p>
|
---|
71 | *
|
---|
72 | * All errors are to be handled through {@link SessionState#getResult()}
|
---|
73 | * except for bugs that use {@link RuntimeException} like
|
---|
74 | * {@link IllegalArgumentException}s. <br>
|
---|
75 | * The protocol usually uses the incoming connections to keep running. It
|
---|
76 | * does not need to run in a separate thread or so.
|
---|
77 | *
|
---|
78 | *
|
---|
79 | * @param connectionfactory the {@link ProtocolToPartyConnFactory} that
|
---|
80 | * allows the protocol to connect with the
|
---|
81 | * {@link Reference}s in the settings
|
---|
82 | */
|
---|
83 | void start(ProtocolToPartyConnFactory connectionfactory);
|
---|
84 |
|
---|
85 | /**
|
---|
86 | *
|
---|
87 | * @return a complete description of how this protocol behaves. Presented to
|
---|
88 | * the end users who should know negotiation basics but not all
|
---|
89 | * technical terms.
|
---|
90 | */
|
---|
91 | String getDescription();
|
---|
92 |
|
---|
93 | /**
|
---|
94 | * @return current state: the results of all sessions run so far and how to
|
---|
95 | * continue from that point. Changes over time as the session
|
---|
96 | * proceeds. Errors are also stored in the state.
|
---|
97 | */
|
---|
98 | NegoState getState();
|
---|
99 |
|
---|
100 | /**
|
---|
101 | *
|
---|
102 | * @return the {@link ProtocolRef} for this protocol
|
---|
103 | */
|
---|
104 | ProtocolRef getRef();
|
---|
105 |
|
---|
106 | /**
|
---|
107 | * Add a party after the protocol has started. Only some protocols can
|
---|
108 | * handle this call. Usual protocols take the settings with their
|
---|
109 | * constructor.
|
---|
110 | *
|
---|
111 | * @param party the {@link PartyWithProfile} to be added.
|
---|
112 | */
|
---|
113 | void addParticipant(PartyWithProfile party);
|
---|
114 |
|
---|
115 | }
|
---|