1 package cz.cuni.amis.pogamut.base.agent.utils.runner;
2
3 import cz.cuni.amis.pogamut.base.agent.params.IAgentParameters;
4 import cz.cuni.amis.pogamut.base.agent.utils.runner.impl.AgentDescriptor;
5 import cz.cuni.amis.pogamut.base.factory.guice.GuiceAgentFactory;
6 import cz.cuni.amis.pogamut.base.factory.guice.GuiceAgentModule;
7
8 /**
9 * This interface describes everything that is needed to instantiate and start of the agent.
10 * <p><p>
11 * It describes three things:
12 * <ol>
13 * <li>Guice module that contains a definition (bindings) for the factory, so we know how to instantiate the agent ({@link IAgentDescriptor#getAgentModule()})</li>
14 * <li>number of the agents that should be instantiated/started ({@link IAgentDescriptor#getCount()})</li>
15 * <li>respective parameters that should be passed to the agents during construction ({@link IAgentDescriptor#getAgentParameters()})</li>
16 * </ol>
17 * <p><p>
18 * Used by implementors of {@link IMultipleAgentRunner}. It allows you to start different agents (of different classes)
19 * at once.
20 * <p><p>
21 * Note that the {@link IAgentDescriptor#getCount()} does not need to match the {@link IAgentDescriptor#getAgentParameters()}.length.
22 * There are three scenarios (according to the relation between those two numbers) and the number of agents the {@link IMultipleAgentRunner} will instantiate:
23 * <ol>
24 * <li>{@link IAgentDescriptor#getCount()} > {@link IAgentDescriptor#getAgentParameters()}.length - in this case, the {@link IMultipleAgentRunner} will instantiate specified number of agents with default parameters</li>
25 * <li>{@link IAgentDescriptor#getCount()} == {@link IAgentDescriptor#getAgentParameters()}.length - in this case, the {@link IMultipleAgentRunner} will instantiate the same number of agents as there are parameters</li>
26 * <li>{@link IAgentDescriptor#getCount()} < {@link IAgentDescriptor#getAgentParameters()}.length - the {@link IMultipleAgentRunner} will instantiate 'count' of agents and first 'number of parameters' will have custom params as specified, rest will have defaults</li>
27 * </ol>
28 *
29 * @author Jimmy
30 *
31 * @param <PARAMS>
32 * @param <MODULE>
33 */
34 public interface IAgentDescriptor<PARAMS extends IAgentParameters, MODULE extends GuiceAgentModule> {
35
36 /**
37 * Agent module that contains bindings for the classes, used by {@link GuiceAgentFactory} (or concretely by the Guice)
38 * to instantiate the agent.
39 *
40 * @return agent's module
41 */
42 public MODULE getAgentModule();
43
44 /**
45 * How many instances this object describes, i.e., how many agents should be instantiated using {@link IAgentDescriptor#getAgentModule()}.
46 * @return number of agents to instantiate
47 */
48 public int getCount();
49
50 /**
51 * Respective parameters of the agents. The length of the array must be the same as {@link IAgentDescriptor#getCount()}, i.e.,
52 * there must be a separate parameter instance for every agent).
53 * <p><p>
54 * Note that some parameters may be null as {@link IMultipleAgentRunner} implementation can provide
55 * default parameters for agents (usually).
56 *
57 * @return
58 */
59 public PARAMS[] getAgentParameters();
60
61 }