1 package cz.cuni.amis.pogamut.base.component.controller;
2
3 import cz.cuni.amis.pogamut.base.component.IComponent;
4 import cz.cuni.amis.pogamut.base.component.bus.event.IFatalErrorEvent;
5 import cz.cuni.amis.pogamut.base.component.bus.event.IPausingEvent;
6 import cz.cuni.amis.pogamut.base.component.bus.event.IResetEvent;
7 import cz.cuni.amis.pogamut.base.component.bus.event.IResumingEvent;
8 import cz.cuni.amis.pogamut.base.component.bus.event.IStartingEvent;
9 import cz.cuni.amis.pogamut.base.component.bus.event.IStartingPausedEvent;
10 import cz.cuni.amis.pogamut.base.component.bus.event.IStoppingEvent;
11 import cz.cuni.amis.utils.exception.PogamutException;
12
13 /**
14 * Provides a way to control the component.
15 * <p><p>
16 * We have purposefully created specific helper interface for the control of the {@link IComponent}. That's because
17 * the designer of the component might want to hide its start/stop/kill method (e.g. they should not be accessible
18 * by anyone). This is typical when using {@link IComponentController} to automatically start/stop the component
19 * based on its dependencies.
20 * <p><p>
21 * So if you want to hide these methods from the public interface of your component, than create private inner
22 * class inside your component and implement how the component is starting/stopping/killing itself possibly by recalling
23 * private methods of the component.
24 *
25 * @author Jimmy
26 */
27 public interface IComponentControlHelper {
28
29 /**
30 * Called before the {@link IStartingEvent} of the component is broadcast.
31 * <p><p>
32 * You may need to prepare some stuff before starting event is generated
33 *
34 * @throws PogamutException
35 */
36 public void preStart() throws PogamutException;
37
38 /**
39 * Starts the component. It should throw exception, if it can not start.
40 *
41 * @throws PogamutException
42 */
43 public void start() throws PogamutException;
44
45 /**
46 * Called before {@link IStartingPausedEvent} of the component is broadcast.
47 * <p><p>
48 * You may need to prepare some stuff before starting event is generated.
49 *
50 * @throws PogamutException
51 */
52 public void preStartPaused() throws PogamutException;
53
54 /**
55 * Starts the component but it assumes that the component just prepares whatever data
56 * structures it needs / make connections / handshake whatever it needs with the environment / etc.
57 * <p><p>
58 * It should not let the agent to perform designers work (i.e., UT2004 bots should not start playing in the game).
59 * <p><p>
60 * After this call, the component should behave as it would have been paused with {@link IComponentControlHelper#pause()}.
61 *
62 * @throws PogamutException
63 */
64 public void startPaused() throws PogamutException;
65
66 /**
67 * Called before the {@link IPausingEvent} of the component is broadcast.
68 * <p><p>
69 * You may need to pre-clean some stuff.
70 *
71 * @throws PogamutException
72 */
73 public void prePause() throws PogamutException;
74
75 /**
76 * Pauses the component.
77 * <p><p>
78 * Called whenever {@link IPausingEvent} is caught from one of the dependencies.
79 *
80 * @throws PogamutException
81 */
82 public void pause() throws PogamutException;
83
84 /**
85 * Called before the {@link IResumingEvent} of the component is broadcast.
86 * <p><p>
87 * You may need to pre-clean some stuff.
88 *
89 * @throws PogamutException
90 */
91 public void preResume() throws PogamutException;
92
93 /**
94 * Resumes the component.
95 * <p><p>
96 * Called whenever {@link IResumingEvent} is caught from one of the dependencies.
97 *
98 * @throws PogamutException
99 */
100 public void resume() throws PogamutException;
101
102 /**
103 * Called before the {@link IStoppingEvent} of the component is broadcast.
104 * <p><p>
105 * You may need to pre-clean some stuff.
106 *
107 * @throws PogamutException
108 */
109 public void preStop() throws PogamutException;
110
111 /**
112 * Stops the component.
113 * <p><p>
114 * It should throw an exception if the component can't be stopped.
115 *
116 * @throws PogamutException
117 */
118 public void stop() throws PogamutException;
119
120 /**
121 * Kills the component in ruthless way. It must be non-blocking method.
122 * <p><p>
123 * Called whenever {@link IFatalErrorEvent} is caught.
124 * <p><p>
125 * Must not throw any exception whatsoever.
126 */
127 public void kill();
128
129 /**
130 * Called whenever {@link IResetEvent} is caught. It should reinitialize data structures of the
131 * component so it can be started again.
132 * <p><p>
133 * Should throw an exception in case that the component can't be reseted.
134 *
135 * @throws PogamutException
136 */
137 public void reset() throws PogamutException;
138
139 }