public abstract class AbstractDeviceDriver extends BasePlugin implements DeviceDriver
INDEX_HIGH, INDEX_HIGHER, INDEX_HIGHEST, INDEX_LOW, INDEX_LOWER, INDEX_LOWEST, INDEX_NORMAL, INDEX_VERY_HIGH, INDEX_VERY_LOW| Constructor and Description |
|---|
AbstractDeviceDriver(java.lang.String description,
java.lang.String protocol,
TableFormat connectionProperties) |
AbstractDeviceDriver(java.lang.String description,
TableFormat connectionPropertiesFormat) |
| 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
DeviceDriver.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.
|
DiscoveryProvider |
createDiscoveryProvider()
Should return implementation of a DiscoveryProvider is driver supports device discovery or null otherwise.
|
java.util.List<DeviceEntityDescriptor> |
definitionsToDescriptors(java.util.List<? extends EntityDefinition> definitions,
boolean activeByDefault) |
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.
|
TableFormat |
getConnectionPropertiesFormat() |
VariableStatus |
getCustomVariableStatus(java.lang.String name)
This method allows the driver to report custom variable status to the system core.
|
DeviceContext |
getDeviceContext() |
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 aCallerController)
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
DeviceDriver.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> groups,
DeviceEntities entities)
This method is similar to the
DeviceDriver.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> groups,
DeviceEntities entities)
This method is similar to the
DeviceDriver.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> groups,
DeviceEntities entities)
This method is similar to the
DeviceDriver.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 |
setConnected(boolean connected) |
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.
|
compareTo, createGlobalConfigContext, createGlobalConfigContext, createUserConfigContext, doStart, doStop, getDescription, getGlobalConfigContext, getId, getPluginDirector, getShortId, getSortIndex, getUserConfigContext, globalDeinit, globalInit, globalStart, globalStop, setDescription, setId, setIndex, setPluginDirector, userDeinit, userInitclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitcreateDeviceContextcreateGlobalConfigContext, createUserConfigContext, getDescription, getGlobalConfigContext, getId, getShortId, getSortIndex, getUserConfigContext, globalDeinit, globalInit, globalStart, globalStop, userDeinit, userInitpublic AbstractDeviceDriver(java.lang.String description,
TableFormat connectionPropertiesFormat)
public AbstractDeviceDriver(java.lang.String description,
java.lang.String protocol,
TableFormat connectionProperties)
public java.lang.String getPrimaryAddress()
DeviceDrivergetPrimaryAddress in interface DeviceDriverpublic java.util.Set<java.lang.String> getAddresses()
DeviceDrivergetAddresses in interface DeviceDriverpublic java.lang.String getStatus()
DeviceDrivergetStatus in interface DeviceDriverpublic java.util.List<Expression> getStatusExpressions(CallerController aCallerController)
DeviceDrivergetStatusExpressions in interface DeviceDriverpublic void setupDeviceContext(DeviceContext deviceContext) throws ContextException
DeviceDriverThis 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.
setupDeviceContext in interface DeviceDriverContextExceptionpublic void configureDeviceAccount(DeviceContext deviceContext, CallerController caller) throws ContextException
DeviceDriverDeviceDriver.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.configureDeviceAccount in interface DeviceDriverContextExceptionpublic void accessSettingUpdated(java.lang.String name)
DeviceDriverThis 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.
accessSettingUpdated in interface DeviceDriverpublic boolean shouldSynchronize(SynchronizationParameters parameters) throws ContextException
DeviceDrivershouldSynchronize in interface DeviceDriverContextException - 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.public void startSynchronization()
throws DeviceException
DeviceDriverstartSynchronization in interface DeviceDriverDeviceException - If some device communications were performed and error occurredpublic boolean isUsesConnections()
DeviceDriverisUsesConnections in interface DeviceDriverpublic boolean isConnected()
DeviceDriverisConnected in interface DeviceDriverpublic void connect()
throws DeviceException
DeviceDriverconnect in interface DeviceDriverDeviceException - If connection has failedpublic boolean isUsesAssets()
DeviceDriverisUsesAssets in interface DeviceDriverpublic java.util.List<DeviceAssetDefinition> readAssets() throws ContextException, DeviceException, DisconnectionException
DeviceDriverreadAssets in interface DeviceDriverContextException - If some server-side error occurredDeviceException - If device assets reading failed (e.g. hardware error occurred)DisconnectionException - If device connection was interrupted during metadata readingpublic java.util.List<DeviceEntityDescriptor> readVariableDescriptors(java.util.List<DeviceAssetDefinition> assets) throws ContextException, DeviceException, DisconnectionException
DeviceDriverreadVariableDescriptors in interface DeviceDriverContextException - If some server-side error occurredDeviceException - If device assets reading failed (e.g. hardware error occurred)DisconnectionException - If device connection was interrupted during metadata readingpublic java.util.List<DeviceEntityDescriptor> readFunctionDescriptors(java.util.List<DeviceAssetDefinition> assets) throws ContextException, DeviceException, DisconnectionException
DeviceDriverreadFunctionDescriptors in interface DeviceDriverContextException - If some server-side error occurredDeviceException - If device assets reading failed (e.g. hardware error occurred)DisconnectionException - If device connection was interrupted during metadata readingpublic java.util.List<DeviceEntityDescriptor> readEventDescriptors(java.util.List<DeviceAssetDefinition> assets) throws ContextException, DeviceException, DisconnectionException
DeviceDriverreadEventDescriptors in interface DeviceDriverContextException - If some server-side error occurredDeviceException - If device assets reading failed (e.g. hardware error occurred)DisconnectionException - If device connection was interrupted during metadata readingpublic boolean isUseDeviceSideValuesCache()
DeviceDriverDeviceDriver.writeVariableValue(VariableDefinition, CallerController, DataTable, DataTable) along with new values.isUseDeviceSideValuesCache in interface DeviceDriverpublic java.util.List<VariableDefinition> readVariableDefinitions(DeviceEntities entities) throws ContextException, DeviceException, DisconnectionException
DeviceDriverThis 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 DeviceDriver.isUsesAssets() method returns false.
readVariableDefinitions in interface DeviceDriverentities - Interface allowing to check what variables are active and those definitions should be returned by this method.ContextException - If some server-side error occurredDeviceException - If device metadata reading failed (e.g. hardware error occurred)DisconnectionException - If device connection was interrupted during metadata readingpublic java.util.List<VariableDefinition> readVariableDefinitions(java.util.List<DeviceAssetDefinition> groups, DeviceEntities entities) throws ContextException, DeviceException, DisconnectionException
DeviceDriver
This method is similar to the DeviceDriver.readVariableDefinitions(DeviceEntities). If should return only definitions of variables that belong to enabled assets and their children.
The method is called only if DeviceDriver.isUsesAssets() returns true.
readVariableDefinitions in interface DeviceDriverentities - Interface allowing to check what variables are active and those definitions should be returned by this method.ContextException - If some server-side error occurredDeviceException - If device metadata reading failed (e.g. hardware error occurred)DisconnectionException - If device connection was interrupted during metadata readingpublic java.util.List<FunctionDefinition> readFunctionDefinitions(DeviceEntities entities) throws ContextException, DeviceException, DisconnectionException
DeviceDriverThis 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 DeviceDriver.isUsesAssets() method returns false.
readFunctionDefinitions in interface DeviceDriverentities - Interface allowing to check what functions are active and those definitions should be returned by this method.ContextException - If some server-side error occurredDeviceException - If device metadata reading failed (e.g. hardware error occurred)DisconnectionException - If device connection was interrupted during metadata readingpublic java.util.List<FunctionDefinition> readFunctionDefinitions(java.util.List<DeviceAssetDefinition> groups, DeviceEntities entities) throws ContextException, DeviceException, DisconnectionException
DeviceDriver
This method is similar to the DeviceDriver.readFunctionDefinitions(DeviceEntities). If should return only definitions of functions that belong to enabled assets and their children.
The method is called only if DeviceDriver.isUsesAssets() returns true.
readFunctionDefinitions in interface DeviceDriverentities - Interface allowing to check what functions are active and those definitions should be returned by this method.ContextException - If some server-side error occurredDeviceException - If device metadata reading failed (e.g. hardware error occurred)DisconnectionException - If device connection was interrupted during metadata readingpublic java.util.List<EventDefinition> readEventDefinitions(DeviceEntities entities) throws ContextException, DeviceException, DisconnectionException
DeviceDriverThis 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 DeviceDriver.isUsesAssets() method returns false.
readEventDefinitions in interface DeviceDriverentities - Interface allowing to check what events are active and those definitions should be returned by this method.ContextException - If some server-side error occurredDeviceException - If device metadata reading failed (e.g. hardware error occurred)DisconnectionException - If device connection was interrupted during metadata readingpublic java.util.List<EventDefinition> readEventDefinitions(java.util.List<DeviceAssetDefinition> groups, DeviceEntities entities) throws ContextException, DeviceException, DisconnectionException
DeviceDriver
This method is similar to the DeviceDriver.readEventDefinitions(DeviceEntities). If should return only definitions of events that belong to enabled assets and their children.
The method is called only if DeviceDriver.isUsesAssets() returns true.
readEventDefinitions in interface DeviceDriverentities - Interface allowing to check what events are active and those definitions should be returned by this method.ContextException - If some server-side error occurredDeviceException - If device metadata reading failed (e.g. hardware error occurred)DisconnectionException - If device connection was interrupted during metadata readingpublic DataTable readVariableValue(VariableDefinition vd, CallerController caller) throws ContextException, DeviceException, DisconnectionException
DeviceDriverreadVariableValue in interface DeviceDriverContextException - If conversion of device value to the Data Table has occurredDeviceException - If reading of device setting has failed (e.g. hardware error occurred)DisconnectionException - If device connection was lost during operationpublic void writeVariableValue(VariableDefinition vd, CallerController caller, DataTable value, DataTable deviceValue) throws ContextException, DeviceException, DisconnectionException
DeviceDriverwriteVariableValue in interface DeviceDriverdeviceValue - Previous value of setting received from device by calling DeviceDriver.readVariableValue(VariableDefinition, CallerController). Will be NULL if server was restarted since previous read
operation or DeviceDriver.isUseDeviceSideValuesCache() returns false;ContextException - If conversion of the Data Table to a device value has occurredDeviceException - If writing of device setting has failed (e.g. hardware error occurred)DisconnectionException - If device connection was lost during operationpublic DataTable executeFunction(FunctionDefinition fd, CallerController caller, DataTable parameters) throws ContextException, DeviceException, DisconnectionException
DeviceDriverexecuteFunction in interface DeviceDriverContextException - If server-side error occurred (e.g. conversion of input/output between Data Tables and device native format)DeviceException - If device-side error occurredDisconnectionException - If device connection was lost during operationpublic java.util.Date getVariableModificationTime(java.lang.String name)
throws DeviceException,
DisconnectionException
DeviceDrivergetVariableModificationTime in interface DeviceDriverDeviceException - If device-side error occurredDisconnectionException - If device connection was lost during operationpublic void updateVariableModificationTime(java.lang.String name,
java.util.Date value)
throws DeviceException,
DisconnectionException
DeviceDriverupdateVariableModificationTime in interface DeviceDriverDeviceException - If device-side error occurredDisconnectionException - If device connection was lost during operationpublic VariableStatus getCustomVariableStatus(java.lang.String name) throws DeviceException, DisconnectionException
DeviceDrivergetCustomVariableStatus in interface DeviceDriverDeviceExceptionDisconnectionExceptionpublic void disconnect()
throws DeviceException
DeviceDriverdisconnect in interface DeviceDriverDeviceException - If proper disconnection has failedpublic void finishSynchronization()
throws DeviceException,
DisconnectionException
DeviceDriverfinishSynchronization in interface DeviceDriverDeviceException - If some device communications were performed and error occurredDisconnectionExceptionpublic void setConnected(boolean connected)
public DeviceContext getDeviceContext()
public DiscoveryProvider createDiscoveryProvider()
DeviceDrivercreateDiscoveryProvider in interface DeviceDriverpublic java.lang.String getProtocol()
DeviceDrivergetProtocol in interface DeviceDriverpublic TableFormat getConnectionPropertiesFormat()
public TableFormat createConnectionPropertiesFormat()
DeviceDriverShould 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.
createConnectionPropertiesFormat in interface DeviceDriverpublic java.util.List<DeviceEntityDescriptor> definitionsToDescriptors(java.util.List<? extends EntityDefinition> definitions, boolean activeByDefault)
public VariableDefinition discoverVariable(java.lang.String name, java.lang.Object helper)
DeviceDriverdiscoverVariable in interface DeviceDriverpublic FunctionDefinition discoverFunction(java.lang.String name, java.lang.Object helper)
DeviceDriverdiscoverFunction in interface DeviceDriverpublic EventDefinition discoverEvent(java.lang.String name, java.lang.Object helper)
DeviceDriverdiscoverEvent in interface DeviceDriverpublic void acklowledgeEvent(Event ev, Acknowledgement acknowledgement) throws ContextException, DeviceException
DeviceDriveracklowledgeEvent in interface DeviceDriverContextExceptionDeviceExceptionpublic boolean runFullSynchronizationOnStartup()
DeviceDriverrunFullSynchronizationOnStartup in interface DeviceDriverpublic void deviceDestroyed(boolean moving)
DeviceDriverdeviceDestroyed in interface DeviceDriverpublic void deviceMoved(Context newParent, java.lang.String newName) throws ContextException
DeviceDriverdeviceMoved in interface DeviceDriverContextExceptionpublic void readBufferedData()
throws ContextException,
DeviceException,
DisconnectionException
DeviceDriverreadBufferedData in interface DeviceDriverContextException - If some server-side error occurredDeviceException - If device assets reading failed (e.g. hardware error occurred)DisconnectionException - If device connection was interrupted during metadata reading