com.sssw.fw.api
Interface EbiManagableService

public interface EbiManagableService

This interface is to be implemented by Director services that wish to be life cycle managed. If a service class implements this interface, the framework will invioke the lifecycle methods at the appropriate times.
It is recommended that the implementations of these methods be synchonized as there is the possibility for multiple threads to concurrently call the methods of this interface.

Since:

5.2

Method Summary

void	destroy() Called sometime after init() and meant to indicate that the instance of the service will never be used again during the application lifetime.
void	init() Called shortly after the service is constructed but before any other methods on the service are called.
boolean	isStarted() The service must return true is the service has been successfully started and is currently running.
void	start() Called sometime after init() and after other system initialization.
void	stop() Called some time after init() and presumably some time after start() has been called at least once, however the method will never be called while the isStarted() returns false.

Method Detail

init

public void init()
          throws EboUnrecoverableSystemException

Called shortly after the service is constructed but before any other methods on the service are called. This is where initialization code that might throw an exception should be placed as opposed to in the service constructor. The order in which init is called for the subsystems shall be indeterminate relative to other subsystems (i.e. don't coun't on other subsystems being usable at this point). This method will only be called once per construction of the service (e.g. if a singleton, once per application lifetime). If an exception is thrown, the service will be considered to have failed initialization and will be considered unusable and unavailable.

Throws:

EboUnrecoverableSystemException - the service should throw this if an error occurs during the initialization. If the exception is thrown, the service will be considered to have failed initialization and will be considered unusble and unavailable.

Since:

5.2

start

public void start()
           throws EboApiException,
                  EboServiceDependencyException,
                  EboUnrecoverableSystemException

Called sometime after init() and after other system initialization. The relative initial start-up order in which this method is called for a given service is guaranteed to correspond to the position of the subsystem in the subsystem.xml configuration file and the position of the service in the services.xml configuration file. This method will never be called while the isStarted() returns true. When the service is successfully started and considered usable, it must thereafter return true when isStarted() is called.
Note that this method may be called at an arbitrary time after the initial init() and start() of the service and may be called more than once during the life of the service. If the service can not start due to some dependency on a another service that is not started it should throw and EboServiceDependencyException and indicate the name of the service that it depends on. The system may then attempt to start the depended on service(s) and recall start on this service().
This is where service threads may be started and other runtime required objects allocated.

Throws:

EboApiException - the service should throw this to mean that the operation failed but may be tried at a later time with the possibility of succeeding. The service is still considered usable, but is not considered started, and in such a case, the service should take care to return false from the isStarted().

EboServiceDependencyException - the service should throw this exception if it can not start because it relies on other services to be started. Once thrown the system may start the other services and attempt to start this service again. The service is still considered usable, but is not considered started, and in such a case, the service should take care to return false from the isStarted().

EboUnrecoverableSystemException - the service should throw to mean that the service has failed in a way that it can not be made usable, and in such a case the framework will consider the service to be unusable and will destroy the service and remove it from the list of active services.

Since:

5.2

stop

public void stop()
          throws EboApiException,
                 EboServiceDependencyException,
                 EboUnrecoverableSystemException

Called some time after init() and presumably some time after start() has been called at least once, however the method will never be called while the isStarted() returns false. The relative order in which this method is called for a given service during system shutdown is guaranteed to correspond to the reverse ordinal position of the subsystem in the subsystem.xml configuration file and then the reverse ordinal position of the service in the services.xml configuration file. When the service is successfully stopped and considered temporarily unusable, it must thereafter return false when isStarted() is called. This method may be called at an arbitrary time provided init() has been executed, and it may be called more than once during the life of the service. Here is where service threads may be stopped when they are done servicing requests and other runtime required objects may be freed.

Throws:

EboApiException - the service should throw this to mean that the operation failed but may be tried at a later time with the possibility of succeeding. The service is still considered usable and started, and in such a case, the service should take care to return true from the isStarted() until stop is run sucessfully.

EboServiceDependencyException - the service should throw this exception if it can not stop because it relies on other services to be stopped. Once thrown the system may stop the other services and attempt to stop this service again. The service is still considered usable and started, and in such a case, the service should take care to return true from the isStarted() until stop is run sucessfully.

EboUnrecoverableSystemException - the service should throw to mean that the service has failed in a way that it can not be made usable, and in such a case the framework will consider the service to be unusable and will destroy the service and remove it from the list of active services.

Since:

5.2

destroy

public void destroy()
             throws EboUnrecoverableSystemException

Called sometime after init() and meant to indicate that the instance of the service will never be used again during the application lifetime. There is no guarantee that the start() or stop() methods have ever been called since the init() was called and the subsystem relative order that this method will be called in is indeterminate. Exceptions thrown from this method will be logged but the object will still be considered to have been destroyed since no further handling can be done. Once destroy is called, the service should expect that none of its methods will be called, and should fail any requests after the destroy() is invoked. A destroyed service will never be reused, so the object can expect that init() will not be called again. Here is where a service can release any resources allocated in the constructor or the init() method.

Throws:

EboUnrecoverableSystemException - the service should throw this if an error occurs during the destruction. If the exception is thrown, the service will be considered to have failed destruction, but there is no recourse that the framework can take, so the exception will simply be noted and the service destruction proceedure continued with. The service should do its best job cleaning up what resources it can despite any exceptions that may occur cleaning up some resources.

Since:

5.2

isStarted

public boolean isStarted()

The service must return true is the service has been successfully started and is currently running. If the system is in a stopped state, then it should return false when this method is called. This method will be consulted before calling the start or stop method so it is important that the service return accurate information about its running state.

Returns:

boolean true to indicate that the service has been started and is running.

Since:

5.2