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 * <p><p>
72 * WARNING: if you want to use this method, you have to carefully type your runner instance, i.e., provide java-generic <AGENT_CLASS>
73 * information, otherwise Java won't compile your code correctly!
74 *
75 * @param agentsParameters
76 * @return list of started agents
77 */
78 public List<AGENT> startAgents(PARAMS... agentsParameters) throws PogamutException;
79
80 /**
81 * Sets the pausing behavior.
82 * <p><p>
83 * If set true, the runner will pause all agents after their construction and resume them
84 * at once whenever all agents has been successfully started.
85 *
86 * @param state
87 * @return this instance
88 */
89 public IAgentRunner<AGENT, PARAMS> setPausing(boolean state);
90
91 /**
92 * Tells, whether the pausing behavior is enabled.
93 * <p><p>
94 * If enabled, the runner will pause all agents after their construction and resume them
95 * at once whenever all agents has been instantiated.
96 *
97 * @return state of the pausing behavior
98 */
99 public boolean isPausing();
100
101 /**
102 * Sets 'main' functionality (see the Javadoc for the whole class).
103 * @param state
104 * @return
105 */
106 public IAgentRunner<AGENT, PARAMS> setMain(boolean state);
107
108 /**
109 * Whether the runner is set to provide 'main' functionality (see the Javadoc for the whole class).
110 * @return
111 */
112 public boolean isMain();
113
114 }