hkontrol.core
Class AbstractModule

java.lang.Object
  hkontrol.core.AbstractModule

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

Module, Module, Module, Module, Module

public abstract class AbstractModule
extends java.lang.Object
implements java.lang.Runnable

AbstractModule is the base class for all of HKontrol's modules.

To implement a new module (named mymodule)

• create package hkontrol.module.mymodule,
• create class hkontrol.module.mymodule.Module derived from AbstractModule,
• overwrite the work method,
• overwrite the init method if needed.

The derived class can use getConnection if it needs to communicate or getConfig for details on its configuration.

Constructor Summary

protected

AbstractModule() The default constructor actually does NOT initialize the object.

Method Summary

void	construct(Configuration.Entry config, State state) Replaces the empty default constructor and must be called immediately after object instantiation.
protected Configuration.Entry	getConfig() returns the configuration element which led to the module's instantiation.
protected HKConnection	getConnection() returns a HKConnection object if a connection is associated with the calling module instance.
protected State	getState() returns the current State object.
protected boolean	init() is being called within the construct method to give the module the chance to initialize itself while knowing about its configuration.
void	run()
protected abstract int	work() is called repeatedly by run in a seperate thread.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractModule

protected AbstractModule()

The default constructor actually does NOT initialize the object. Instead, the contruct method must be called after instantiation. Doing it that way, the derived actions are not being enforced to implement a constructor.

Method Detail

construct

public final void construct(Configuration.Entry config,
                            State state)

Replaces the empty default constructor and must be called immediately after object instantiation. Since construct is final and the creation of action objects take place in the HKontrol core, the derived actions do not need to know anything about the instantiation details. However, the implementing module is given the chance to initialize itself by overriding the init method which is called before creating a new thread and calling work therein.

Parameters:

config - the configuration element referring to the instantiated module

state - the State object which is to be changed when applicable

run

public final void run()

Specified by:

run in interface java.lang.Runnable

getState

protected State getState()

returns the current State object. Implemented modules can change the state if applicable. Observing rules will be notified automatically and execute suitable actions if they match the new state.

Returns:

the state which is being observed

getConfig

protected Configuration.Entry getConfig()

returns the configuration element which led to the module's instantiation. The module can retrieve additional configuration information if needed.

Returns:

the configuration element which led to the module's instantiation

work

protected abstract int work()
                     throws ModuleException

is called repeatedly by run in a seperate thread. Since doing some work and then sleeping some time is a common use case, work must return the number of milliseconds that will have to pass before work should be called again. As a matter of fact, the implementing modules can be designed easily not to use this mechanism but implement their own.

Returns:

number of milliseconds to wait before the call of work. If the returned value is negative the module will cease execution.

Throws:

ModuleException - which will be caught and logged

init

protected boolean init()

is being called within the construct method to give the module the chance to initialize itself while knowing about its configuration. If init returns false, the module won't be used!

Returns:

true, if the module could be initialized successfully, false otherwise

getConnection

protected HKConnection getConnection()
                              throws ModuleException

returns a HKConnection object if a connection is associated with the calling module instance.

Returns:

the associated connection or null if no connection is configured

Throws:

ModuleException - if connection could not be established