org.sensorhub.api.module

Interface IModule<ConfigType extends ModuleConfig>

Type Parameters:

ConfigType -

All Superinterfaces:

IEventProducer

All Known Subinterfaces:

IClientModule<ConfigType>, ICommNetwork<ConfigType>, ICommProvider<ConfigType>, IDataProducerModule<ConfigType>, IObsStorageModule<ConfigType>, IOnDemandProcessModule<ConfigType>, IProcessModule<ConfigType>, IRecordStorageModule<ConfigType>, ISensorModule<ConfigType>, IServiceModule<ConfigType>, IStorageModule<ConfigType>, IStreamProcessModule<ConfigType>

All Known Implementing Classes:

AbstractModule, AbstractSensorModule, AbstractStreamProcess, AdminUIModule, BasicSecurityRealm, BasicStorageImpl, GenericStreamStorage, HttpServer, InMemoryBasicStorage, MultiEntityStorageImpl, ObsStorageImpl, SensorSystem, SMLStreamProcess, SOSService, SOSTClient, SOSVirtualSensor, SPSService, SWEVirtualSensor, TCPCommProvider, UDPCommProvider

public interface IModule<ConfigType extends ModuleConfig>
extends IEventProducer

Generic interface for all modules in the system.

Since:

Nov 12, 2010

Author:

Alex Robin

Method Summary

Methods

Modifier and Type	Method and Description
void	cleanup() Cleans up all ressources used by the module when deleted All persistent resources created by the module should be cleaned when this is called
ConfigType	getConfiguration() Retrieves a copy of the module configuration (i.e.
Throwable	getCurrentError()
ModuleEvent.ModuleState	getCurrentState()
String	getLocalID() Helper method to get the module's local ID
String	getName() Helper method to get the module's name
String	getStatusMessage()
void	init() Initializes the module synchronously with the current configuration. Implementations of this method must block until the module is successfully initialized or send an exception. Module lifecycle events may not be generated when calling this method directly.
void	init(ConfigType config) Initializes the module synchronously with the specified configuration. Implementations of this method must block until the module is successfully initialized or send an exception. This is equivalent to calling setConfiguration(ModuleConfig) and then init() with no arguments. Module lifecycle events may not be generated when calling this method directly.
boolean	isInitialized() Checks if module is initialized
boolean	isStarted() Checks if module is started
void	loadState(IModuleStateManager loader) Restores the state of this module Implementations of this method must block until the module state is successfully loaded or send an exception.
void	registerListener(IEventListener listener) Registers a listener to receive events generated by this module. When this method is called, the current state of the module is also notified synchronously to guarantee that the listener always receives it.
void	requestInit(boolean force) Requests to initialize the module with the current configuration. Implementations of this method block until the module is initialized or return immediately while they wait for the proper init conditions. When this method returns without error the module state is guaranteed to be ModuleEvent.ModuleState.INITIALIZING
void	requestStart() Requests the module to start. Implementations of this method may block until the module is started or return immediately while they wait for the proper start conditions. When this method returns without error the module state is guaranteed to be ModuleEvent.ModuleState.STARTING
void	requestStop() Requests the module to stop. Implementations of this method may block until the module is stopped or return immediately while they wait for the proper stop conditions. When this method returns without error the module state is guaranteed to be ModuleEvent.ModuleState.STOPPING
void	saveState(IModuleStateManager saver) Saves the state of this module. Implementations of this method must block until the module state is successfully saved or send an exception.
void	setConfiguration(ConfigType config) Sets the module configuration
void	start() Starts the module synchronously with the current configuration. Implementations of this method must block until the module is successfully started or send an exception. Module lifecycle events may not be generated when calling this method directly. init() should always be called before start().
void	stop() Stops the module. All temporary resources created by the module should be cleaned when this is called (ex: memory, files, connections, etc.) Implementations of this method must block until the module is successfully stopped or send an exception. Module lifecycle events may not be generated when calling this method directly. stop() can be called right after init() even if start() hasn't been called.
void	unregisterListener(IEventListener listener) Unregisters a listener and thus stop receiving events generayed by this module
void	updateConfig(ConfigType config) Updates the module's configuration dynamically. The module must honor this new configuration unless an error is detected.
boolean	waitForState(ModuleEvent.ModuleState state, long timeout) Waits until the module reaches the specified state or times out. This method will return immediately if the state has already been reached.

Method Detail

setConfiguration

void setConfiguration(ConfigType config)

Sets the module configuration

Parameters:

config -

getConfiguration

ConfigType getConfiguration()

Retrieves a copy of the module configuration (i.e. for reading only since changes won't have any effect until updateConfig is called)

Returns:

a copy of the configuration object associated to this module

getName

String getName()

Helper method to get the module's name

Returns:

name string

getLocalID

String getLocalID()

Helper method to get the module's local ID

Returns:

id string

isInitialized

boolean isInitialized()

Checks if module is initialized

Returns:

true if module is initialized, false otherwise

isStarted

boolean isStarted()

Checks if module is started

Returns:

true if module is started, false otherwise

getCurrentState

ModuleEvent.ModuleState getCurrentState()

Returns:

the current state of the module

waitForState

boolean waitForState(ModuleEvent.ModuleState state,
                   long timeout)

Waits until the module reaches the specified state or times out.
This method will return immediately if the state has already been reached.

Parameters:

state - state to wait for

timeout - maximum time to wait in milliseconds or <= 0 to wait forever

Returns:

true if module state has been reached, false in case of timeout or error

getStatusMessage

String getStatusMessage()

Returns:

the current status message

getCurrentError

Throwable getCurrentError()

Returns:

the last error that occured executing the module

requestInit

void requestInit(boolean force)
                 throws SensorHubException

Requests to initialize the module with the current configuration.
Implementations of this method block until the module is initialized or return immediately while they wait for the proper init conditions.
When this method returns without error the module state is guaranteed to be ModuleEvent.ModuleState.INITIALIZING

Parameters:

force - set to true to force a reinit, even if module was already initialized

Throws:

SensorHubException - if module could not enter initialization phase

init

void init()
          throws SensorHubException

Initializes the module synchronously with the current configuration.
Implementations of this method must block until the module is successfully initialized or send an exception.
Module lifecycle events may not be generated when calling this method directly.

Throws:

SensorHubException

init

void init(ConfigType config)
          throws SensorHubException

Initializes the module synchronously with the specified configuration.
Implementations of this method must block until the module is successfully initialized or send an exception.
This is equivalent to calling setConfiguration(ModuleConfig) and then init() with no arguments.
Module lifecycle events may not be generated when calling this method directly.

Parameters:

config -

Throws:

SensorHubException

updateConfig

void updateConfig(ConfigType config)
                  throws SensorHubException

Updates the module's configuration dynamically.
The module must honor this new configuration unless an error is detected. It is the responsability of the module to initiate a restart if the new configuration requires it.

Parameters:

config -

Throws:

SensorHubException

requestStart

void requestStart()
                  throws SensorHubException

Requests the module to start.
Implementations of this method may block until the module is started or return immediately while they wait for the proper start conditions.
When this method returns without error the module state is guaranteed to be ModuleEvent.ModuleState.STARTING

Throws:

SensorHubException - if startup could not be initiated

start

void start()
           throws SensorHubException

Starts the module synchronously with the current configuration.
Implementations of this method must block until the module is successfully started or send an exception.
Module lifecycle events may not be generated when calling this method directly.
init() should always be called before start().

Throws:

SensorHubException

requestStop

void requestStop()
                 throws SensorHubException

Requests the module to stop.
Implementations of this method may block until the module is stopped or return immediately while they wait for the proper stop conditions.
When this method returns without error the module state is guaranteed to be ModuleEvent.ModuleState.STOPPING

Throws:

SensorHubException - if shutdown could not be initiated

stop

void stop()
          throws SensorHubException

Stops the module.
All temporary resources created by the module should be cleaned when this is called (ex: memory, files, connections, etc.)
Implementations of this method must block until the module is successfully stopped or send an exception.
Module lifecycle events may not be generated when calling this method directly.
stop() can be called right after init() even if start() hasn't been called.

Throws:

SensorHubException

saveState

void saveState(IModuleStateManager saver)
               throws SensorHubException

Saves the state of this module.
Implementations of this method must block until the module state is successfully saved or send an exception.

Parameters:

saver -

Throws:

SensorHubException

loadState

void loadState(IModuleStateManager loader)
               throws SensorHubException

Restores the state of this module
Implementations of this method must block until the module state is successfully loaded or send an exception.

Parameters:

loader -

Throws:

SensorHubException

cleanup

void cleanup()
             throws SensorHubException

Cleans up all ressources used by the module when deleted All persistent resources created by the module should be cleaned when this is called

Throws:

SensorHubException

registerListener

void registerListener(IEventListener listener)

Registers a listener to receive events generated by this module.
When this method is called, the current state of the module is also notified synchronously to guarantee that the listener always receives it.

Specified by:

registerListener in interface IEventProducer

Parameters:

listener -

unregisterListener

void unregisterListener(IEventListener listener)

Unregisters a listener and thus stop receiving events generayed by this module

Specified by:

unregisterListener in interface IEventProducer

Parameters:

listener -