1 package cz.cuni.amis.pogamut.base.agent.utils.runner;
2
3 import java.util.List;
4
5 import cz.cuni.amis.pogamut.base.agent.IAgent;
6 import cz.cuni.amis.pogamut.base.agent.params.IAgentParameters;
7 import cz.cuni.amis.utils.exception.PogamutException;
8
9 /**
10 * Utility interface for classes that can instantiate & start (possibly multiple) agents at once. All agents must be
11 * of the same class though. Note that this usually is not a problem as the agent class is a shell that may
12 * contain arbitrary agent's logic implementations. (If it proves to be a problem, check whether there is a suitable
13 * implementation of the {@link IMultipleAgentRunner} implementation that you can use.)
14 * <p><p>
15 * Every implementor is instantiated with default values that should be passed into the agent when no
16 * other parameters are provided. Therefore you may use {@link IAgentRunner#startAgent()} to start agent
17 * with default params, or {@link IAgentRunner#startAgents(int)} and {@link IAgentRunner#startAgents(IAgentParameters...)}
18 * where you may specify your own params.
19 * <p><p>
20 * Note that the {@link IAgentRunner} utilize {@link IAgentParameters#assignDefaults(IAgentParameters)} to fill
21 * missing fields into {@link IAgentParameters} which allows you to instantiate the {@link IAgentParameters} implementor
22 * with custom data leaving the rest to the {@link IAgentRunner} (eases the pain of starting agents greatly).
23 * <p><p>
24 * The interface also provides a "synchronizing" feature via {@link IAgentRunner#setPausing(boolean)}. If set true,
25 * the runner will pause all agents after they start and resume them at once when all agents have been instantiated.
26 * <p>
27 * Pausing behavior is disabled (== set to false) as default.
28 * <p><p>
29 * <b>USING FROM THE main(String[] args) METHOD</b>
30 * <p>
31 * Starting agents from the main method requires special care:
32 * <ol>
33 * <li>if one of your agents fails, all agents should be closed (simulation has been broken)</li>
34 * <li>when all your agent dies, Pogamut platform should be closed (so the JVM could terminate)</li>
35 * </ol>
36 * Previous two points are not-so-easy to implement (and we won't bother you with them). Instead, you
37 * could just call {@link IAgentRunner#setMain(boolean)} with 'true' and the runner will behave differently.
38 * (Note that all startAgent methods will block!)
39 *
40 * @author jimmy
41 */
42 public interface IAgentRunner<AGENT extends IAgent, PARAMS extends IAgentParameters> {
43
44 /**
45 * Starts the agent by providing default parameters (defined during the construction of the implementor).
46 *
47 * @return agent instance configured with default parameters that has been started
48 * @throws PogamutException
49 */
50 public AGENT startAgent() throws PogamutException;
51
52 /**
53 * Starts agents by providing every one of them with default parameters
54 * (defined during the construction of the implementor).
55 * <p><p>
56 * Note that if any instantiation/start of the agent fails, all agents are killed before the method throws
57 * the exception.
58 *
59 * @param count how many agents should be started
60 * @return list of started agents
61 * @throws PogamutException
62 */
63 public List<AGENT> startAgents(int count) throws PogamutException;
64
65 /**
66 * Start an agent instance configured with 'agentsParameters'. The length of the 'agentsParameters' array
67 * determines how many agents are going to be started.
68 * <p><p>
69 * Note that if any instantiation/start of the agent fails, all agents are killed before the method throws
70 * the exception.
71 *
72 * @param agentsParameters
73 * @return list of started agents
74 */
75 public List<AGENT> startAgents(PARAMS... agentsParameters) throws PogamutException;
76
77 /**
78 * Sets the pausing behavior.
79 * <p><p>
80 * If set true, the runner will pause all agents after their construction and resume them
81 * at once whenever all agents has been successfully started.
82 *
83 * @param state
84 * @return this instance
85 */
86 public IAgentRunner<AGENT, PARAMS> setPausing(boolean state);
87
88 /**
89 * Tells, whether the pausing behavior is enabled.
90 * <p><p>
91 * If enabled, the runner will pause all agents after their construction and resume them
92 * at once whenever all agents has been instantiated.
93 *
94 * @return state of the pausing behavior
95 */
96 public boolean isPausing();
97
98 /**
99 * Sets 'main' functionality (see the Javadoc for the whole class).
100 * @param state
101 * @return
102 */
103 public IAgentRunner<AGENT, PARAMS> setMain(boolean state);
104
105 /**
106 * Whether the runner is set to provide 'main' functionality (see the Javadoc for the whole class).
107 * @return
108 */
109 public boolean isMain();
110
111 }