org.openmuc.framework.driver.spi
Interface DriverService


public interface DriverService

The 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:

Some guidelines should be followed when implementing a driver for OpenMUC:


Method Summary
 java.lang.Object connect(java.lang.String interfaceAddress, java.lang.String deviceAddress, java.lang.String settings, int timeout)
          Attempts to connect to the given communication device using the given settings.
 void disconnect(DeviceConnection connection)
          Disconnects or closes the given connection.
 java.lang.String getDescription()
          Returns a string with a description of what the driver does.
 java.lang.String getId()
          Returns the ID of the driver.
 java.lang.Object read(DeviceConnection connection, java.util.List<ChannelRecordContainer> containers, java.lang.Object containerListHandle, java.lang.String samplingGroup, int timeout)
          Reads the data channels that correspond to the given record containers.
 java.util.List<ChannelScanInformation> scanForChannels(DeviceConnection connection, int timeout)
          Scan a given communication device for available data channels.
 java.util.List<DeviceScanInformation> scanForDevices(java.lang.String interfaceAddress, java.lang.String scanFilter, java.lang.String settings, int timeout)
          Scans for available communication devices and returns information about them.
 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, int timeout)
          Writes the data channels that correspond to the given value containers.
 

Method Detail

getId

java.lang.String getId()
Returns the ID of the driver. By convention the ID should be meaningful and all lower case letters (e.g. "mbus", "modbus").

Returns:
the unique ID of the driver.

getDescription

java.lang.String getDescription()
Returns a string with a description of what the driver does.

Returns:
a string with a description of what the driver does

scanForDevices

java.util.List<DeviceScanInformation> scanForDevices(java.lang.String interfaceAddress,
                                                     java.lang.String scanFilter,
                                                     java.lang.String settings,
                                                     int timeout)
                                                     throws java.lang.UnsupportedOperationException,
                                                            ArgumentSyntaxException,
                                                            java.io.IOException
Scans for available communication devices and returns information about them. This operation is optional and may not be supported by specific drivers.

Parameters:
scanFilter - a string whose syntax depends on the specific communication driver being used. It tells the driver where to scan for communication devices.
Returns:
A list of communication devices that were found. Returns an empty list if no device was found.
Throws:
MethodNotSupportedException - if the method is not implemented by the driver
ArgumentSyntaxException - if an the scanFilter string cannot be understood by the driver
java.io.IOException - if an error occurs while scanning
java.lang.UnsupportedOperationException

scanForChannels

java.util.List<ChannelScanInformation> scanForChannels(DeviceConnection connection,
                                                       int timeout)
                                                       throws java.lang.UnsupportedOperationException,
                                                              ConnectionException
Scan a given communication device for available data channels. This operation is optional and my not be supported by specific drivers.

Parameters:
connection - ihe DeviceConnection of the communication device that is to be scanned for data channels.
Returns:
A list of data channels that were found.
Throws:
MethodNotSupportedException - if the method is not implemented by the driver.
java.io.IOException - if an error occurs while scanning.
java.lang.UnsupportedOperationException
ConnectionException

connect

java.lang.Object connect(java.lang.String interfaceAddress,
                         java.lang.String deviceAddress,
                         java.lang.String settings,
                         int timeout)
                         throws ArgumentSyntaxException,
                                ConnectionException
Attempts to connect to the given communication device using the given settings. The resulting connection resource object can be return by this function. The framework will then pass the connection object in all subsequent function calls meant for this device. If the syntax of the given interfaceAddress, deviceAddresse, or settings String is incorrect it will throw an ArgumentSyntaxException. If the connection attempt fails it throws a ConnectionException.

Parameters:
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.
timeout - the time in milliseconds after which the connection attempt shall be aborted and a ConnectionException shall be thrown.
Returns:
the connection handle that is passed to subsequent read/listen/write/scanForChannels/disconnect function calls.
Throws:
ArgumentSyntaxException - if the syntax of interfaceAddress, deviceAddress or settings is incorrect.
ConnectionException - if the connection attempt fails.

disconnect

void disconnect(DeviceConnection connection)
Disconnects or closes the given connection. Cleans up any resources associated with the connection.

Parameters:
connection - the device connection that is to closed.

read

java.lang.Object read(DeviceConnection connection,
                      java.util.List<ChannelRecordContainer> containers,
                      java.lang.Object containerListHandle,
                      java.lang.String samplingGroup,
                      int timeout)
                      throws java.lang.UnsupportedOperationException,
                             ConnectionException
Reads the data channels that correspond to the given record containers. The read result is returned by setting the record in the containers. If for some reason no value can be read the record should be set anyways. In this case the record shall have a value and timestamp of null and a flag that best describes the reason of failure. 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.

Parameters:
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.
timeout - the time after which the read function should interrupt the read process and return records with the flag set to Flag.TIMEOUT. Note that OpenMUC Data Manager automatically sets the Flag of the latest sample to Flag.TIMEOUT once the time has elapsed without the read function returning. Thus even if driver neglects the timeout the latest sample will always be flagged correctly. The main disadvantage of ignoring the timeout is that the driver could potentially block new read, write or disconnect requests from executing.
Returns:
the containerListHandle Object that will passed the next time the same list of channels is to be read. Use this Object as a handle to improve performance or simply return null.
Throws:
java.lang.UnsupportedOperationException - if the method is not implemented by the driver.
ConnectionException - if the connection to the device was interrupted.

startListening

void startListening(DeviceConnection connection,
                    java.util.List<ChannelRecordContainer> containers,
                    RecordsReceivedListener listener)
                    throws java.lang.UnsupportedOperationException,
                           ConnectionException
Starts listening on the given connection for data from the channels that correspond to the given record containers. Will overwrite all data channels set by the previous startListening call. Will notify the given listener of new records that arrive on the data channels.

Parameters:
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.
Throws:
java.lang.UnsupportedOperationException - if the method is not implemented by the driver.
ConnectionException - if the connection to the device was interrupted.

write

java.lang.Object write(DeviceConnection connection,
                       java.util.List<ChannelValueContainer> containers,
                       java.lang.Object containerListHandle,
                       int timeout)
                       throws java.lang.UnsupportedOperationException,
                              ConnectionException
Writes the data channels that correspond to the given value containers. The write result is returned by setting the flag in the containers. 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.

Parameters:
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.
timeout - see read for detailed documentation.
Returns:
the containerListHandle Object that will passed the next time the same list of channels is to be written. Use this Object as a handle to improve performance or simply return null.
Throws:
java.lang.UnsupportedOperationException - if the method is not implemented by the driver.
ConnectionException - if the connection to the device was interrupted.