com.tibbo.aggregate.common.device

## Interface DeviceDriver

- All Superinterfaces:
    AggreGatePlugin
  All Known Implementing Classes:
    AbstractDeviceDriver, DemoDeviceDriver

      public interface DeviceDriver
      extends AggreGatePlugin

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    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)