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 }