org.openmuc.framework.driver.spi
public interface DriverService
DriverService
is the interface that all OpenMUC communication drivers have to implement and register
as a service in the OSGi environment. The OpenMUC Core Data Manager tracks this service and will therefore be
automatically notified of any new drivers in the framework. If sampling, listening or logging has been configured for
this driver, then the data manager will start right away with the appropriate actions.
The OpenMUC framework can give certain guarantees about the order of the functions it calls:
debug
or trace
. Even these debug messages should be
used very sparsely. Only use them to further explain errors that occur.ConnectionException
. The framework will then
try to reconnect by calling the connect
function.DriverService
are caught by the OpenMUC framework and logged
with level error
. It is bad practice to throw these unchecked exceptions because they can clutter the
log file and slow down performance if the function is called many times. Instead the appropriate Flag should be
returned for the affected channels.Modifier and Type | Method and Description |
---|---|
java.lang.Object |
connect(java.lang.String interfaceAddress,
java.lang.String deviceAddress,
java.lang.String settings)
Attempts to connect to the given communication device using the given settings.
|
void |
disconnect(DeviceConnection connection)
Disconnects or closes the given connection.
|
org.openmuc.framework.config.DriverInfo |
getInfo()
Returns the driver information.
|
void |
interruptDeviceScan()
A call of this function signals the driver to stop the device scan as soon as possible.
|
java.lang.Object |
read(DeviceConnection connection,
java.util.List<ChannelRecordContainer> containers,
java.lang.Object containerListHandle,
java.lang.String samplingGroup)
Reads the data channels that correspond to the given record containers.
|
java.util.List<org.openmuc.framework.config.ChannelScanInfo> |
scanForChannels(DeviceConnection connection,
java.lang.String settings)
Scan a given communication device for available data channels.
|
void |
scanForDevices(java.lang.String settings,
DriverDeviceScanListener listener)
Scans for available devices.
|
void |
startListening(DeviceConnection connection,
java.util.List<ChannelRecordContainer> containers,
RecordsReceivedListener listener)
Starts listening on the given connection for data from the channels that correspond to the given record
containers.
|
java.lang.Object |
write(DeviceConnection connection,
java.util.List<ChannelValueContainer> containers,
java.lang.Object containerListHandle)
Writes the data channels that correspond to the given value containers.
|
org.openmuc.framework.config.DriverInfo getInfo()
void scanForDevices(java.lang.String settings, DriverDeviceScanListener listener) throws java.lang.UnsupportedOperationException, org.openmuc.framework.config.ArgumentSyntaxException, org.openmuc.framework.config.ScanException, org.openmuc.framework.config.ScanInterruptedException
deviceFound()
function. Optionally this method may occasionally call the
updateScanProgress function of DeviceScanListener. The updateScanProgress function should be passed the progress
in percent. The progress should never be explicitly set to 100%. The caller of this function will know that the
progress is at 100% once the function has returned.settings
- scanning settings (e.g. location where to scan, baud rate etc.). The syntax is driver specific.listener
- the listener that is notified of devices found and progress updates.java.lang.UnsupportedOperationException
- if the method is not implemented by the driverorg.openmuc.framework.config.ArgumentSyntaxException
- if an the settings string cannot be understood by the driverorg.openmuc.framework.config.ScanException
- if an error occurs while scanningorg.openmuc.framework.config.ScanInterruptedException
- if the scan was interrupted through a call of interruptDeviceScan()
before it was done.void interruptDeviceScan() throws java.lang.UnsupportedOperationException
java.lang.UnsupportedOperationException
- if the method is not implemented by the driverjava.util.List<org.openmuc.framework.config.ChannelScanInfo> scanForChannels(DeviceConnection connection, java.lang.String settings) throws java.lang.UnsupportedOperationException, org.openmuc.framework.config.ArgumentSyntaxException, org.openmuc.framework.config.ScanException, ConnectionException
connection
- the DeviceConnection of the communication device that is to be scanned for data channels.settings
- scanning settings. The syntax is driver specific.org.openmuc.framework.config.ArgumentSyntaxException
- if an the settings string cannot be understood by the driverjava.lang.UnsupportedOperationException
- if the method is not implemented by the driver.org.openmuc.framework.config.ScanException
- if an error occurs while scanning but the connection is still alive.ConnectionException
- if an error occurs while scanning and the connection was closedjava.lang.Object connect(java.lang.String interfaceAddress, java.lang.String deviceAddress, java.lang.String settings) throws org.openmuc.framework.config.ArgumentSyntaxException, ConnectionException
ArgumentSyntaxException
. If the connection attempt fails it
throws a ConnectionException
.interfaceAddress
- the configured interface address. Will be null
if not configured.deviceAddress
- the configured device address.settings
- the settings that should be used for the communication with this device.org.openmuc.framework.config.ArgumentSyntaxException
- if the syntax of interfaceAddress, deviceAddress or settings is incorrect.ConnectionException
- if the connection attempt fails.void disconnect(DeviceConnection connection)
connection
- the device connection that is to closed.java.lang.Object read(DeviceConnection connection, java.util.List<ChannelRecordContainer> containers, java.lang.Object containerListHandle, java.lang.String samplingGroup) throws java.lang.UnsupportedOperationException, ConnectionException
Flag.DRIVER_ERROR_CHANNEL_NOT_ACCESSIBLE
. If the
connection to the device is interrupted, then any necessary resources that correspond to this connection should
be cleaned up and a ConnectionException
shall be thrown.connection
- the device connection that is to be used to read the channels.containers
- the containers hold the information of what channels are to be read. They will be filled by this
function with the records read.containerListHandle
- the containerListHandle returned by the last read call for this exact list of containers. Will be
equal to null
if this is the first read call for this container list after a connection
has been established. Driver implementations can optionally use this object to improve the read
performance.samplingGroup
- the samplingGroup that was configured for this list of channels that are to be read. Sometimes it may
be desirable to give the driver a hint on how to group several channels when reading them. This can
done through the samplingGroup.null
.java.lang.UnsupportedOperationException
- if the method is not implemented by the driver.ConnectionException
- if the connection to the device was interrupted.void startListening(DeviceConnection connection, java.util.List<ChannelRecordContainer> containers, RecordsReceivedListener listener) throws java.lang.UnsupportedOperationException, ConnectionException
connection
- the device connection that is to be used to listen.containers
- the containers identify the channels to listen on. They will be filled by this function with the
records received and passed to the listener.listener
- the listener to inform that new data has arrived.java.lang.UnsupportedOperationException
- if the method is not implemented by the driver.ConnectionException
- if the connection to the device was interrupted.java.lang.Object write(DeviceConnection connection, java.util.List<ChannelValueContainer> containers, java.lang.Object containerListHandle) throws java.lang.UnsupportedOperationException, ConnectionException
ConnectionException
shall be thrown.connection
- the device connection that is to be used to write the channels.containers
- the containers hold the information of what channels are to be written and the values that are to
written. They will be filled by this function with a flag stating whether the write process was
successful or not.containerListHandle
- the containerListHandle returned by the last write call for this exact list of containers. Will be
equal to null
if this is the first read call for this container list after a connection
has been established. Driver implementations can optionally use this object to improve the write
performance.null
.java.lang.UnsupportedOperationException
- if the method is not implemented by the driver.ConnectionException
- if the connection to the device was interrupted.