com.tibbo.aggregate.common.device

Interface DeviceDriver

All Superinterfaces:

AggreGatePlugin

All Known Implementing Classes:

AbstractDeviceDriver, DemoDeviceDriver

public interface DeviceDriver
extends AggreGatePlugin

Method Summary

Modifier and Type	Method and Description
void	accessSettingUpdated(java.lang.String name) This method is called when any variable belonging to ContextUtils.GROUP_ACCESS variable group is changed.
void	acklowledgeEvent(Event ev, Acknowledgement acknowledgement) Can be used to register an event acknowledgement in a device.
void	configureDeviceAccount(DeviceContext deviceContext, CallerController caller) In contrast to setupDeviceContext(DeviceContext), this method is called only once in the end of initial device account creation.
void	connect() This method is called if isConnected() method returned false or DeviceContext.setReconnectionRequired(true) was called by the driver during previous synchronization.
TableFormat	createConnectionPropertiesFormat() Should return device connection properties as a single-record TableFormat.
default Context	createDeviceContext(DeviceDriver driver, Context userContext, java.lang.String cname)
DiscoveryProvider	createDiscoveryProvider() Should return implementation of a DiscoveryProvider is driver supports device discovery or null otherwise.
void	deviceDestroyed(boolean moving) This method is called when the device is removed.
void	deviceMoved(Context newParent, java.lang.String newName) This method is called when the device is moved.
void	disconnect() This method is called when device account is being deleted, server is being stopped, or DeviceContext.setReconnectionRequired(true) was called by the driver during previous synchronization.
EventDefinition	discoverEvent(java.lang.String name, java.lang.Object helper) Tries to discover device event that was not found during automatic metadata reading.
FunctionDefinition	discoverFunction(java.lang.String name, java.lang.Object helper) Tries to discover device variable that was not found during automatic metadata reading.
VariableDefinition	discoverVariable(java.lang.String name, java.lang.Object helper) Tries to discover device variable that was not found during automatic metadata reading.
DataTable	executeFunction(FunctionDefinition fd, CallerController caller, DataTable parameters) This method should implement the call of the device-side operation (function).
void	finishSynchronization() This method is called in the end of every synchronization.
java.util.Set<java.lang.String>	getAddresses() Returns the list of device addresses.
VariableStatus	getCustomVariableStatus(java.lang.String name) This method allows the driver to report custom variable status to the system core.
java.lang.String	getPrimaryAddress() This method should return string representation of device address or null if device has no address.
java.lang.String	getProtocol() Returns device protocol description.
java.lang.String	getStatus() Returns current status of device and/or driver or null if detailed status is not available.
java.util.List<Expression>	getStatusExpressions(CallerController caller) Implementations of this method should provide list of expression that will be used to show device status on dynamic maps.
java.util.Date	getVariableModificationTime(java.lang.String name) This method should return timestamp of device setting last modification time as reported by the hardware.
boolean	isConnected() This method should return true driver has successfully established a link with the hardware.
boolean	isUseDeviceSideValuesCache() Should return true if server should cache device-side values and pass them to writeVariableValue(VariableDefinition, CallerController, DataTable, DataTable) along with new values.
boolean	isUsesAssets() Should return true if device driver has support for assets.
boolean	isUsesConnections() This method should return true if device uses normal connection model.
java.util.List<DeviceAssetDefinition>	readAssets() This method returns the hierarchical list of assets provided by the device.
void	readBufferedData() This method should handle reading variable values and device events buffered by remote side during a disconnection period.
java.util.List<EventDefinition>	readEventDefinitions(DeviceEntities entities) This method should return definitions of events that may be generated by the device.
java.util.List<EventDefinition>	readEventDefinitions(java.util.List<DeviceAssetDefinition> assets, DeviceEntities entities) This method is similar to the readEventDefinitions(DeviceEntities).
java.util.List<DeviceEntityDescriptor>	readEventDescriptors(java.util.List<DeviceAssetDefinition> assets) This method should return a list of potentially available device events.
java.util.List<FunctionDefinition>	readFunctionDefinitions(DeviceEntities entities) This method should return definitions of device operations (functions).
java.util.List<FunctionDefinition>	readFunctionDefinitions(java.util.List<DeviceAssetDefinition> assets, DeviceEntities entities) This method is similar to the readFunctionDefinitions(DeviceEntities).
java.util.List<DeviceEntityDescriptor>	readFunctionDescriptors(java.util.List<DeviceAssetDefinition> assets) This method should return a list of potentially available device functions.
java.util.List<VariableDefinition>	readVariableDefinitions(DeviceEntities entities) This method should return definitions of device settings (variables).
java.util.List<VariableDefinition>	readVariableDefinitions(java.util.List<DeviceAssetDefinition> assets, DeviceEntities entities) This method is similar to the readVariableDefinitions(DeviceEntities).
java.util.List<DeviceEntityDescriptor>	readVariableDescriptors(java.util.List<DeviceAssetDefinition> assets) This method should return a list of potentially available device variables.
DataTable	readVariableValue(VariableDefinition vd, CallerController caller) Implementation of this method should read value of device setting pointed by the argument, convert it to the form of Data Table and return it.
boolean	runFullSynchronizationOnStartup() Defines whether full synchronization of the device should occur on every server restart.
void	setupDeviceContext(DeviceContext deviceContext) This method is called once during creation of the device context (after device creation and on server startup).
boolean	shouldSynchronize(SynchronizationParameters parameters) This method is called once before every synchronization.
void	startSynchronization() Called in the beginning of every synchronization cycle.
void	updateVariableModificationTime(java.lang.String name, java.util.Date value) This method should update device-side modification time of a setting pointed by name argument or do nothing if modification-time-based synchronization is not supported.
void	writeVariableValue(VariableDefinition vd, CallerController caller, DataTable value, DataTable deviceValue) Implementation of this method should write server-side value of device setting into a hardware.

Methods inherited from interface com.tibbo.aggregate.common.plugin.AggreGatePlugin

createGlobalConfigContext, createUserConfigContext, getDescription, getGlobalConfigContext, getId, getShortId, getSortIndex, getUserConfigContext, globalDeinit, globalInit, globalStart, globalStop, userDeinit, userInit

Method Detail

createConnectionPropertiesFormat

TableFormat createConnectionPropertiesFormat()

Should return device connection properties as a single-record TableFormat. The format must include at least "name" field.

This method is defined in AtestbstractDeviceDriver and should not be overridden in most cases.

setupDeviceContext

void setupDeviceContext(DeviceContext deviceContext)
                 throws ContextException

This method is called once during creation of the device context (after device creation and on server startup). Driver implementation usually override it to add definitions of device communication settings (e.g. IP address and port number) to the device context. Setup of synchronization settings for the whole device and individual settings is also performed at this point.

Variable definitions representing device communication settings should belong to ContextUtils.GROUP_ACCESS variable group.

Throws:

ContextException

configureDeviceAccount

void configureDeviceAccount(DeviceContext deviceContext,
                            CallerController caller)
                     throws ContextException

In contrast to setupDeviceContext(DeviceContext), this method is called only once in the end of initial device account creation. Its implementation can correct necessary default values of device context variables, such as metadata reading mode or device settings caching mode. Overriding this method is not necessary for most drivers.

Throws:

ContextException

accessSettingUpdated

void accessSettingUpdated(java.lang.String name)

This method is called when any variable belonging to ContextUtils.GROUP_ACCESS variable group is changed. Driver implementations may override it to respond to device communication settings changes by resetting driver internal state.

Note, that in most cases overriding this method is not necessary as driver implementations should re-read device communication settings from device context in the beginning of every synchronization, e.g. from startSynchronization() method.

createDiscoveryProvider

DiscoveryProvider createDiscoveryProvider()

Should return implementation of a DiscoveryProvider is driver supports device discovery or null otherwise.

shouldSynchronize

boolean shouldSynchronize(SynchronizationParameters parameters)
                   throws ContextException

This method is called once before every synchronization. The synchronization is silently skipped if it returns null. Certain drivers may override this method to skip synchronization if device communication settings were not yet filled in.

Throws:

ContextException - Should be thrown by the driver to force generating Info event in addition to skipping the synchronization. This Info event contains exception message that is supposed to describe the reason of synchronization skip, e.g. "device address not specified". In order to avoid event flooding, driver should throw an exception only if full synchronization is performed.

startSynchronization

void startSynchronization()
                   throws DeviceException

Called in the beginning of every synchronization cycle. Driver implementations may read communication settings from device context at this point.

Throws:

DeviceException - If some device communications were performed and error occurred

isUsesConnections

boolean isUsesConnections()

This method should return true if device uses normal connection model.

isConnected

boolean isConnected()

This method should return true driver has successfully established a link with the hardware.

connect

void connect()
      throws DeviceException

This method is called if isConnected() method returned false or DeviceContext.setReconnectionRequired(true) was called by the driver during previous synchronization. It should establish connection with the hardware.

Throws:

DeviceException - If connection has failed

disconnect

void disconnect()
         throws DeviceException

This method is called when device account is being deleted, server is being stopped, or DeviceContext.setReconnectionRequired(true) was called by the driver during previous synchronization. The method should break a link with the hardware and clean up any internal data related to the connection.

Throws:

DeviceException - If proper disconnection has failed

isUsesAssets

boolean isUsesAssets()

Should return true if device driver has support for assets.

readBufferedData

void readBufferedData()
               throws ContextException,
                      DeviceException,
                      DisconnectionException

This method should handle reading variable values and device events buffered by remote side during a disconnection period.

Throws:

ContextException - If some server-side error occurred

DeviceException - If device assets reading failed (e.g. hardware error occurred)

DisconnectionException - If device connection was interrupted during metadata reading

readAssets

java.util.List<DeviceAssetDefinition> readAssets()
                                          throws ContextException,
                                                 DeviceException,
                                                 DisconnectionException

This method returns the hierarchical list of assets provided by the device.

Throws:

ContextException - If some server-side error occurred

DeviceException - If device assets reading failed (e.g. hardware error occurred)

DisconnectionException - If device connection was interrupted during metadata reading

readVariableDescriptors

java.util.List<DeviceEntityDescriptor> readVariableDescriptors(java.util.List<DeviceAssetDefinition> assets)
                                                        throws ContextException,
                                                               DeviceException,
                                                               DisconnectionException

This method should return a list of potentially available device variables.

Throws:

ContextException - If some server-side error occurred

DeviceException - If device assets reading failed (e.g. hardware error occurred)

DisconnectionException - If device connection was interrupted during metadata reading

readFunctionDescriptors

java.util.List<DeviceEntityDescriptor> readFunctionDescriptors(java.util.List<DeviceAssetDefinition> assets)
                                                        throws ContextException,
                                                               DeviceException,
                                                               DisconnectionException

This method should return a list of potentially available device functions.

Throws:

ContextException - If some server-side error occurred

DeviceException - If device assets reading failed (e.g. hardware error occurred)

DisconnectionException - If device connection was interrupted during metadata reading

readEventDescriptors

java.util.List<DeviceEntityDescriptor> readEventDescriptors(java.util.List<DeviceAssetDefinition> assets)
                                                     throws ContextException,
                                                            DeviceException,
                                                            DisconnectionException

This method should return a list of potentially available device events.

Throws:

ContextException - If some server-side error occurred

DeviceException - If device assets reading failed (e.g. hardware error occurred)

DisconnectionException - If device connection was interrupted during metadata reading

isUseDeviceSideValuesCache

boolean isUseDeviceSideValuesCache()

Should return true if server should cache device-side values and pass them to writeVariableValue(VariableDefinition, CallerController, DataTable, DataTable) along with new values.

readVariableDefinitions

java.util.List<VariableDefinition> readVariableDefinitions(DeviceEntities entities)
                                                    throws ContextException,
                                                           DeviceException,
                                                           DisconnectionException

This method should return definitions of device settings (variables). Its implementations may read device metadata or construct the definitions based on server-side device configuration.

The method is called only if isUsesAssets() method returns false.

Parameters:

entities - Interface allowing to check what variables are active and those definitions should be returned by this method.

Throws:

ContextException - If some server-side error occurred

DeviceException - If device metadata reading failed (e.g. hardware error occurred)

DisconnectionException - If device connection was interrupted during metadata reading

readVariableDefinitions

java.util.List<VariableDefinition> readVariableDefinitions(java.util.List<DeviceAssetDefinition> assets,
                                                           DeviceEntities entities)
                                                    throws ContextException,
                                                           DeviceException,
                                                           DisconnectionException

This method is similar to the readVariableDefinitions(DeviceEntities). If should return only definitions of variables that belong to enabled assets and their children.

The method is called only if isUsesAssets() returns true.

Parameters:

entities - Interface allowing to check what variables are active and those definitions should be returned by this method.

Throws:

ContextException - If some server-side error occurred

DeviceException - If device metadata reading failed (e.g. hardware error occurred)

DisconnectionException - If device connection was interrupted during metadata reading

readFunctionDefinitions

java.util.List<FunctionDefinition> readFunctionDefinitions(DeviceEntities entities)
                                                    throws ContextException,
                                                           DeviceException,
                                                           DisconnectionException

This method should return definitions of device operations (functions). Its implementations may read device metadata or construct the definitions based on server-side device configuration.

The method is called only if isUsesAssets() method returns false.

Parameters:

entities - Interface allowing to check what functions are active and those definitions should be returned by this method.

Throws:

ContextException - If some server-side error occurred

DeviceException - If device metadata reading failed (e.g. hardware error occurred)

DisconnectionException - If device connection was interrupted during metadata reading

readFunctionDefinitions

java.util.List<FunctionDefinition> readFunctionDefinitions(java.util.List<DeviceAssetDefinition> assets,
                                                           DeviceEntities entities)
                                                    throws ContextException,
                                                           DeviceException,
                                                           DisconnectionException

This method is similar to the readFunctionDefinitions(DeviceEntities). If should return only definitions of functions that belong to enabled assets and their children.

The method is called only if isUsesAssets() returns true.

Parameters:

entities - Interface allowing to check what functions are active and those definitions should be returned by this method.

Throws:

ContextException - If some server-side error occurred

DeviceException - If device metadata reading failed (e.g. hardware error occurred)

DisconnectionException - If device connection was interrupted during metadata reading

readEventDefinitions

java.util.List<EventDefinition> readEventDefinitions(DeviceEntities entities)
                                              throws ContextException,
                                                     DeviceException,
                                                     DisconnectionException

This method should return definitions of events that may be generated by the device. Its implementations may read device metadata or construct the definitions based on server-side device configuration.

Note, that instances of these events may be generated by the driver asynchronously at any time after at least one device synchronization has finished. This is performed by calling DeviceContext.fireEvent().

The method is called only if isUsesAssets() method returns false.

Parameters:

entities - Interface allowing to check what events are active and those definitions should be returned by this method.

Throws:

ContextException - If some server-side error occurred

DeviceException - If device metadata reading failed (e.g. hardware error occurred)

DisconnectionException - If device connection was interrupted during metadata reading

readEventDefinitions

java.util.List<EventDefinition> readEventDefinitions(java.util.List<DeviceAssetDefinition> assets,
                                                     DeviceEntities entities)
                                              throws ContextException,
                                                     DeviceException,
                                                     DisconnectionException

This method is similar to the readEventDefinitions(DeviceEntities). If should return only definitions of events that belong to enabled assets and their children.

The method is called only if isUsesAssets() returns true.

Parameters:

entities - Interface allowing to check what events are active and those definitions should be returned by this method.

Throws:

ContextException - If some server-side error occurred

DeviceException - If device metadata reading failed (e.g. hardware error occurred)

DisconnectionException - If device connection was interrupted during metadata reading

readVariableValue

DataTable readVariableValue(VariableDefinition vd,
                            CallerController caller)
                     throws ContextException,
                            DeviceException,
                            DisconnectionException

Implementation of this method should read value of device setting pointed by the argument, convert it to the form of Data Table and return it.

Throws:

ContextException - If conversion of device value to the Data Table has occurred

DeviceException - If reading of device setting has failed (e.g. hardware error occurred)

DisconnectionException - If device connection was lost during operation

writeVariableValue

void writeVariableValue(VariableDefinition vd,
                        CallerController caller,
                        DataTable value,
                        DataTable deviceValue)
                 throws ContextException,
                        DeviceException,
                        DisconnectionException

Implementation of this method should write server-side value of device setting into a hardware. This method will be called only if device setting definition is writable (e.g server-side changes are allowed.

Parameters:

deviceValue - Previous value of setting received from device by calling readVariableValue(VariableDefinition, CallerController). Will be NULL if server was restarted since previous read operation or isUseDeviceSideValuesCache() returns false;

Throws:

ContextException - If conversion of the Data Table to a device value has occurred

DeviceException - If writing of device setting has failed (e.g. hardware error occurred)

DisconnectionException - If device connection was lost during operation

executeFunction

DataTable executeFunction(FunctionDefinition fd,
                          CallerController caller,
                          DataTable parameters)
                   throws ContextException,
                          DeviceException,
                          DisconnectionException

This method should implement the call of the device-side operation (function). It should decode parameters Data Table to a device native format, pass this input to the device and call requested operation. Opeartion output should be encoded in the form of Data Table and returned by this method

Throws:

ContextException - If server-side error occurred (e.g. conversion of input/output between Data Tables and device native format)

DeviceException - If device-side error occurred

DisconnectionException - If device connection was lost during operation

getVariableModificationTime

java.util.Date getVariableModificationTime(java.lang.String name)
                                    throws DeviceException,
                                           DisconnectionException

This method should return timestamp of device setting last modification time as reported by the hardware. If modification-time-based synchronization is not supported, the method should return null.

Throws:

DeviceException - If device-side error occurred

DisconnectionException - If device connection was lost during operation

updateVariableModificationTime

void updateVariableModificationTime(java.lang.String name,
                                    java.util.Date value)
                             throws DeviceException,
                                    DisconnectionException

This method should update device-side modification time of a setting pointed by name argument or do nothing if modification-time-based synchronization is not supported.

Throws:

DeviceException - If device-side error occurred

DisconnectionException - If device connection was lost during operation

getCustomVariableStatus

VariableStatus getCustomVariableStatus(java.lang.String name)
                                throws DeviceException,
                                       DisconnectionException

This method allows the driver to report custom variable status to the system core. It should return null if no custom status should be used.

Throws:

DeviceException

DisconnectionException

finishSynchronization

void finishSynchronization()
                    throws DeviceException,
                           DisconnectionException

This method is called in the end of every synchronization. Its implementations may perform some cleanup.

Throws:

DeviceException - If some device communications were performed and error occurred

DeviceException - If some device communications were performed and disconnection occurred

DisconnectionException

getPrimaryAddress

java.lang.String getPrimaryAddress()

This method should return string representation of device address or null if device has no address. The address will be used by device discovery module to find existing devices.

Returns:

Device address

getAddresses

java.util.Set<java.lang.String> getAddresses()

Returns the list of device addresses. For example, for a network device this list can contain device host name and IPv4/IPv6 addresses of devices' network interfaces.

Returns:

Set of device addresses

getProtocol

java.lang.String getProtocol()

Returns device protocol description. This method should return null, if device protocol name matches driver description.

Returns:

Device protocol description

getStatus

java.lang.String getStatus()

Returns current status of device and/or driver or null if detailed status is not available.

Returns:

Textual description of device/driver status

getStatusExpressions

java.util.List<Expression> getStatusExpressions(CallerController caller)

Implementations of this method should provide list of expression that will be used to show device status on dynamic maps. The expressions may include relative references to variables/functions of device context.

Returns:

The list of device status expressions

runFullSynchronizationOnStartup

boolean runFullSynchronizationOnStartup()

Defines whether full synchronization of the device should occur on every server restart. Returns false by default. In this case, full synchronization is only performed if full synchronization period elapsed since the previous full synchronization, in other cases connect-only synchronization takes place.

discoverVariable

VariableDefinition discoverVariable(java.lang.String name,
                                    java.lang.Object helper)

Tries to discover device variable that was not found during automatic metadata reading.

Returns:

Variable definition or null if nothing was found

discoverFunction

FunctionDefinition discoverFunction(java.lang.String name,
                                    java.lang.Object helper)

Tries to discover device variable that was not found during automatic metadata reading.

Returns:

Variable definition or null if nothing was found

discoverEvent

EventDefinition discoverEvent(java.lang.String name,
                              java.lang.Object helper)

Tries to discover device event that was not found during automatic metadata reading.

Returns:

Event definition or null if nothing was found

acklowledgeEvent

void acklowledgeEvent(Event ev,
                      Acknowledgement acknowledgement)
               throws ContextException,
                      DeviceException

Can be used to register an event acknowledgement in a device.

Throws:

ContextException

DeviceException

deviceDestroyed

void deviceDestroyed(boolean moving)

This method is called when the device is removed.

deviceMoved

void deviceMoved(Context newParent,
                 java.lang.String newName)
          throws ContextException

This method is called when the device is moved.

Throws:

ContextException

createDeviceContext

default Context createDeviceContext(DeviceDriver driver,
                                    Context userContext,
                                    java.lang.String cname)