1 package cz.cuni.amis.pogamut.base.component.controller;
2
3 import cz.cuni.amis.pogamut.base.agent.IAgentId;
4 import cz.cuni.amis.pogamut.base.component.IComponent;
5 import cz.cuni.amis.pogamut.base.component.bus.event.IFatalErrorEvent;
6 import cz.cuni.amis.pogamut.base.component.bus.event.IPausingEvent;
7 import cz.cuni.amis.pogamut.base.component.bus.event.IResetEvent;
8 import cz.cuni.amis.pogamut.base.component.bus.event.IResumingEvent;
9 import cz.cuni.amis.pogamut.base.component.bus.event.IStartingEvent;
10 import cz.cuni.amis.pogamut.base.component.bus.event.IStartingPausedEvent;
11 import cz.cuni.amis.pogamut.base.component.bus.event.IStoppingEvent;
12 import cz.cuni.amis.pogamut.base.component.lifecyclebus.ILifecycleBus;
13 import cz.cuni.amis.utils.exception.PogamutException;
14
15 /**
16 * Provides a way to control the shared component.
17 * <p><p>
18 * We have purposefully created specific helper interface for the control of the {@link IComponent}. That's because
19 * the designer of the component might want to hide its start/stop/kill method (e.g. they should not be accessible
20 * by anyone). This is typical when using {@link ISharedComponentController} to automatically start/stop the component
21 * based on its dependencies.
22 * <p><p>
23 * So if you want to hide these methods from the public interface of your component, than create private inner
24 * class inside your component and implement how the component is starting/stopping/killing itself possibly by recalling
25 * private methods of the component.
26 * <p><p>
27 * This helper is similar but quite different from the simpler {@link IComponentControlHelper} as it covers more lifecycle cases
28 * which {@link ISharedComponent} has over simple {@link IComponent}.
29 *
30 * @author Jimmy
31 */
32 public interface ISharedComponentControlHelper extends IComponentControlHelper {
33
34 /**
35 * Called whenever starting dependencies of some (first) agent becomes satisfied.
36 * <p><p>
37 * Similar to {@link IComponentControlHelper#preStart()} (sort of a global version).
38 * <p><p>
39 * This method or {@link ISharedComponentControlHelper#preStartPaused()} method is called prior to
40 * any localXXX() methods are called. Which means that you are always informed that your component
41 * should start before it "accepts" starts from respective agents.
42 * <p><p>
43 * NOTE: this method does not have much meaning for {@link ISharedComponent} as method {@link ISharedComponentControlHelper#start()}
44 * is called right after ... nothing is taking place between these two calls.
45 *
46 * @throws PogamutException
47 */
48 @Override
49 public void preStart() throws PogamutException;
50
51 /**
52 * Called to start the component whenever starting dependencies of some (first) agent becomes satisfied.
53 * <p><p>
54 * Similar to {@link IComponentControlHelper#start()} (sort of a global version).
55 * <p><p>
56 * <p><p>
57 * This method or {@link ISharedComponentControlHelper#startPaused()} method is called prior to
58 * any localXXX() methods are called. Which means that you are always informed that your component
59 * should start before it "accepts" starts from respective agents.
60 *
61 * @throws PogamutException
62 */
63 @Override
64 public void start() throws PogamutException;
65
66 /**
67 * Called whenever starting dependencies of some (first) agent becomes satisfied, should start the component
68 * into paused state.
69 * <p><p>
70 * You may need to prepare some stuff before starting event is generated.
71 * <p><p>
72 * Similar to {@link IComponentControlHelper#preStartPaused()} (sort of a global version).
73 * <p><p>
74 * NOTE: this method does not have much meaning for {@link ISharedComponent} as method {@link ISharedComponentControlHelper#startPaused()}
75 * is called right after ... nothing is taking place between these two calls.
76 *
77 * @throws PogamutException
78 */
79 @Override
80 public void preStartPaused() throws PogamutException;
81
82 /**
83 * Starts the component whenever starting dependencies of some (first) agent becomes satisfied.
84 * But it assumes that the component just prepares whatever data
85 * structures it needs / make connections / handshake whatever it needs with the environment / etc.
86 * <p><p>
87 * Similar to {@link IComponentControlHelper#startPaused()} (sort of a global version).
88 *
89 * @throws PogamutException
90 */
91 @Override
92 public void startPaused() throws PogamutException;
93
94 /**
95 * Called whenever there is no running dependencies and the rest is going to be paused or is paused.
96 * <p><p>
97 * Similar to {@link IComponentControlHelper#prePause()} (sort of a global version).
98 * <p><p>
99 * NOTE: this method does not have much meaning for {@link ISharedComponent} as method {@link ISharedComponentControlHelper#pause()}
100 * is called right after ... nothing is taking place between these two calls.
101 *
102 * @throws PogamutException
103 */
104 @Override
105 public void prePause() throws PogamutException;
106
107 /**
108 * Pauses the component. Called whenever there is no running dependencies and the rest is going to be paused or is paused.
109 * <p><p>
110 * Called whenever {@link IPausingEvent} is caught from one of the dependencies.
111 * <p><p>
112 * Similar to {@link IComponentControlHelper#pause()} (sort of a global version).
113 *
114 * @throws PogamutException
115 */
116 @Override
117 public void pause() throws PogamutException;
118
119 /**
120 * Called whenever some of paused dependencies is starting / is started.
121 * <p><p>
122 * Similar to {@link IComponentControlHelper#preResume()} (sort of a global version).
123 * <p><p>
124 * NOTE: this method does not have much meaning for {@link ISharedComponent} as method {@link ISharedComponentControlHelper#resume()}
125 * is called right after ... nothing is taking place between these two calls.
126 *
127 * @throws PogamutException
128 */
129 @Override
130 public void preResume() throws PogamutException;
131
132 /**
133 * Resumes the component. Called whenever some of paused dependencies is starting / is started.
134 * <p><p>
135 * Similar to {@link IComponentControlHelper#resume()} (sort of a global version).
136 *
137 * @throws PogamutException
138 */
139 @Override
140 public void resume() throws PogamutException;
141
142 /**
143 * Called whenever there is no running dependencies and the rest is going to be stopped.
144 * <p><p>
145 * Similar to {@link IComponentControlHelper#preStop()} (sort of a global version).
146 *
147 * @throws PogamutException
148 */
149 @Override
150 public void preStop() throws PogamutException;
151
152 /**
153 * Stops the component. Called whenever there is no running dependencies and the rest is going to be stopped.
154 * <p><p>
155 * Similar to {@link IComponentControlHelper#stop()} (sort of a global version).
156 * <p><p>
157 * NOTE: this method does not have much meaning for {@link ISharedComponent} as method {@link ISharedComponentControlHelper#stop()}
158 * is called right after ... nothing is taking place between these two calls.
159 *
160 * @throws PogamutException
161 */
162 @Override
163 public void stop() throws PogamutException;
164
165 /**
166 * Kills the component in ruthless way. It must be non-blocking method.
167 * <p><p>
168 * Called whenever {@link IFatalErrorEvent} is caught in any agent's bus.
169 * <p><p>
170 * Must not throw any exception whatsoever.
171 * <p><p>
172 * Similar to {@link IComponentControlHelper#kill()} (sort of a global version).
173 */
174 @Override
175 public void kill();
176
177 /**
178 * Called whenever {@link IResetEvent} is caught in any of stopped bus.
179 * It should reinitialize data structures of the
180 * component so it can be started again.
181 * <p><p>
182 * Should throw an exception in case that the component can't be reseted.
183 * <p><p>
184 * Similar to {@link IComponentControlHelper#reset()} (sort of a global version).
185 *
186 * @throws PogamutException
187 */
188 @Override
189 public void reset() throws PogamutException;
190
191 /**
192 * Called before the {@link IStartingEvent} of the component is broadcast into {@link ILifecycleBus} of
193 * the agent identified by 'agentId'.
194 * <p><p>
195 * You may need to prepare some stuff before starting event is generated
196 *
197 * @param agentId
198 * @throws PogamutException
199 */
200 public void localPreStart(IAgentId agentId) throws PogamutException;
201
202 /**
203 * The component is being started inside the {@link ILifecycleBus} of the agent identified by 'agentId'.
204 * It should throw exception, if it can not start for the particular agent.
205 *
206 * @throws PogamutException
207 */
208 public void localStart(IAgentId agentId) throws PogamutException;
209
210 /**
211 * Called before {@link IStartingPausedEvent} of the component is broadcast into {@link ILifecycleBus} of
212 * the agent identified by 'agentId'.
213 * <p><p>
214 * You may need to prepare some stuff before starting event is generated.
215 *
216 * @param agentId
217 * @throws PogamutException
218 */
219 public void localPreStartPaused(IAgentId agentId) throws PogamutException;
220
221 /**
222 * Starts the component for the agent identified by 'agentId' but it assumes that the component just prepares whatever data
223 * structures it needs / make connections / handshake whatever it needs with the environment / etc.
224 * <p><p>
225 * It should not let the agent to perform designers work (i.e., UT2004 bots should not start playing in the game).
226 * <p><p>
227 * After this call, the component should behave as it would have been paused with {@link IComponentControlHelper#pause()}.
228 *
229 * @param agentId
230 * @throws PogamutException
231 */
232 public void localStartPaused(IAgentId agentId) throws PogamutException;
233
234 /**
235 * Called before the {@link IPausingEvent} of the component is broadcast into {@link ILifecycleBus} of
236 * the agent identified by 'agentId'.
237 * <p><p>
238 * You may need to pre-clean some stuff.
239 *
240 * @param agentId
241 * @throws PogamutException
242 */
243 public void localPrePause(IAgentId agentId) throws PogamutException;
244
245 /**
246 * Pauses the component for agent identified by 'agentId'.
247 * <p><p>
248 * Called whenever {@link IPausingEvent} is caught from one of the dependencies of the given agent.
249 *
250 * @param agentId
251 * @throws PogamutException
252 */
253 public void localPause(IAgentId agentId) throws PogamutException;
254
255 /**
256 * Called before the {@link IResumingEvent} of the component is broadcast into {@link ILifecycleBus} of
257 * the agent identified by 'agentId'.
258 * <p><p>
259 * You may need to pre-clean some stuff.
260 *
261 * @param agentId
262 * @throws PogamutException
263 */
264 public void localPreResume(IAgentId agentId) throws PogamutException;
265
266 /**
267 * Resumes the component for the agent identified by 'agentId'.
268 * <p><p>
269 * Called whenever {@link IPausingEvent} is caught from one of the dependencies of the given agent.
270 *
271 * @param agentId
272 * @throws PogamutException
273 */
274 public void localResume(IAgentId agentId) throws PogamutException;
275
276 /**
277 * Called before the {@link IStoppingEvent} of the component is broadcast into {@link ILifecycleBus} of
278 * the agent identified by 'agentId'.
279 * <p><p>
280 * You may need to pre-clean some stuff.
281 *
282 * @param agentId
283 * @throws PogamutException
284 */
285 public void localPreStop(IAgentId agentId) throws PogamutException;
286
287 /**
288 * Stops the component for the agent identified by 'agentId'.
289 * <p><p>
290 * It should throw an exception if the component can't be stopped for the given agent.
291 *
292 * @param agentId
293 * @throws PogamutException
294 */
295 public void localStop(IAgentId agentId) throws PogamutException;
296
297 /**
298 * Kills the component for the agent identified by 'agentId'. It must be non-blocking method.
299 * <p><p>
300 * Called whenever {@link IFatalErrorEvent} is caught for a given agent.
301 * <p><p>
302 * Must not throw any exception whatsoever.
303 *
304 * @param agentId
305 */
306 public void localKill(IAgentId agentId);
307
308 /**
309 * Called whenever {@link IResetEvent} is caught at the {@link ILifecycleBus} of the agent identified by 'agentId'.
310 * <p><p>
311 * It should reinitialize data structures of the
312 * component so it can be usable by the given agent again.
313 * <p><p>
314 * Should throw an exception in case that the component can't be reseted for a given agent.
315 *
316 * @param agentId
317 * @throws PogamutException
318 */
319 public void localReset(IAgentId agentId);
320
321 }