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 }