examples.driver

## Class DemoDeviceDriver

- java.lang.Object
- - org.java.plugin.Plugin
  - - com.tibbo.aggregate.common.plugin.BasePlugin
    - - com.tibbo.aggregate.common.device.AbstractDeviceDriver
      - - examples.driver.DemoDeviceDriver

- All Implemented Interfaces:
    DeviceDriver, AggreGatePlugin, java.lang.Comparable<AggreGatePlugin>

      public class DemoDeviceDriver
      extends AbstractDeviceDriver

  This demo device driver illustrates the usage of device-provided settings, operations and events. It doesn't communicate with any real hardware, all variables, functions and events are pre-defined.

- - ### Field Summary

    - ### Fields inherited from class com.tibbo.aggregate.common.plugin.BasePlugin

      `INDEX_HIGH, INDEX_HIGHER, INDEX_HIGHEST, INDEX_LOW, INDEX_LOWER, INDEX_LOWEST, INDEX_NORMAL, INDEX_VERY_HIGH, INDEX_VERY_LOW`

    - ### Fields inherited from class org.java.plugin.Plugin

      `log`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DemoDeviceDriver()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.lang.String` | `getDemoSettingValue()`
    `java.util.List<EventDefinition>` | `readEventDefinitions(DeviceEntities entities)` This method should return definitions of events that may be generated by the device.
    `java.util.List<FunctionDefinition>` | `readFunctionDefinitions(DeviceEntities entities)` This method should return definitions of device operations (functions).
    `java.util.List<VariableDefinition>` | `readVariableDefinitions(DeviceEntities entities)` This method should return definitions of device settings (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.
    `void` | `setupDeviceContext(DeviceContext deviceContext)` This method is called once during creation of the device context (after device creation and on server startup).
    `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 class com.tibbo.aggregate.common.device.AbstractDeviceDriver

      `accessSettingUpdated, acklowledgeEvent, configureDeviceAccount, connect, createConnectionPropertiesFormat, createDiscoveryProvider, definitionsToDescriptors, deviceDestroyed, deviceMoved, disconnect, discoverEvent, discoverFunction, discoverVariable, getAddresses, getConnectionPropertiesFormat, getCustomVariableStatus, getDeviceContext, getPrimaryAddress, getProtocol, getStatus, getStatusExpressions, getVariableModificationTime, isConnected, isUseDeviceSideValuesCache, isUsesAssets, isUsesConnections, readAssets, readBufferedData, readEventDefinitions, readEventDescriptors, readFunctionDefinitions, readFunctionDescriptors, readVariableDefinitions, readVariableDescriptors, runFullSynchronizationOnStartup, setConnected, shouldSynchronize, startSynchronization, updateVariableModificationTime`

    - ### Methods inherited from class com.tibbo.aggregate.common.plugin.BasePlugin

      `compareTo, createGlobalConfigContext, createGlobalConfigContext, createUserConfigContext, doStart, doStop, getDescription, getGlobalConfigContext, getId, getPluginDirector, getShortId, getSortIndex, getUserConfigContext, globalDeinit, globalInit, globalStart, globalStop, setDescription, setId, setIndex, setPluginDirector, userDeinit, userInit`

    - ### Methods inherited from class org.java.plugin.Plugin

      `getDescriptor, getManager, isActive, toString`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface com.tibbo.aggregate.common.device.DeviceDriver

      `createDeviceContext`

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

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

- - ### Constructor Detail

    - #### DemoDeviceDriver

          public DemoDeviceDriver()

  - ### Method Detail

    - #### setupDeviceContext

          public void setupDeviceContext(DeviceContext deviceContext)
                                  throws ContextException

      Description copied from interface: `DeviceDriver`

      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.

      Specified by:
        `setupDeviceContext` in interface `DeviceDriver`
      Overrides:
        `setupDeviceContext` in class `AbstractDeviceDriver`
      Throws:
        `ContextException`

    - #### readVariableDefinitions

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

      Description copied from interface: `DeviceDriver`

      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 `DeviceDriver.isUsesAssets()` method returns false.

      Specified by:
        `readVariableDefinitions` in interface `DeviceDriver`
      Overrides:
        `readVariableDefinitions` in class `AbstractDeviceDriver`
      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

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

      Description copied from interface: `DeviceDriver`

      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 `DeviceDriver.isUsesAssets()` method returns false.

      Specified by:
        `readFunctionDefinitions` in interface `DeviceDriver`
      Overrides:
        `readFunctionDefinitions` in class `AbstractDeviceDriver`
      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

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

      Description copied from interface: `DeviceDriver`

      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 `DeviceDriver.isUsesAssets()` method returns false.

      Specified by:
        `readEventDefinitions` in interface `DeviceDriver`
      Overrides:
        `readEventDefinitions` in class `AbstractDeviceDriver`
      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

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

      Description copied from interface: `DeviceDriver`
      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.
      Specified by:
        `readVariableValue` in interface `DeviceDriver`
      Overrides:
        `readVariableValue` in class `AbstractDeviceDriver`
      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

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

      Description copied from interface: `DeviceDriver`
      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.
      Specified by:
        `writeVariableValue` in interface `DeviceDriver`
      Overrides:
        `writeVariableValue` in class `AbstractDeviceDriver`
        `deviceValue` - 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;
      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

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

      Description copied from interface: `DeviceDriver`
      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
      Specified by:
        `executeFunction` in interface `DeviceDriver`
      Overrides:
        `executeFunction` in class `AbstractDeviceDriver`
      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

    - #### finishSynchronization

          public void finishSynchronization()
                                     throws DeviceException

      Description copied from interface: `DeviceDriver`
      This method is called in the end of every synchronization. Its implementations may perform some cleanup.
      Specified by:
        `finishSynchronization` in interface `DeviceDriver`
      Overrides:
        `finishSynchronization` in class `AbstractDeviceDriver`
      Throws:
        `DeviceException` - If some device communications were performed and error occurred

    - #### getDemoSettingValue

          public java.lang.String getDemoSettingValue()