Package org.openmuc.framework.driver.spi

Interface Connection

public interface Connection

A connection represents an association to particular device. A driver returns an implementation of this interface when DriverService.connect(String, String) is called. The OpenMUC framework can give certain guarantees about the order of the functions it calls:

• Communication related functions (e.g. connect,read,write..) are never called concurrently for the same device.
• The framework calls read,listen,write or channelScan only if a the device is considered connected. The device is only considered connected if the connect function has been called successfully.
• Before a driver service is unregistered or the data manager is stopped the framework calls disconnect for all connected devices. The disconnect function should do any necessary resource clean up.

Method Summary

Modifier and Type	Method	Description
void	disconnect()	Disconnects or closes the connection.
java.lang.Object	read(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<ChannelScanInfo>	scanForChannels(java.lang.String settings)	Scan a given communication device for available data channels.
void	startListening(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(java.util.List<ChannelValueContainer> containers, java.lang.Object containerListHandle)	Writes the data channels that correspond to the given value containers.

Method Detail

scanForChannels

java.util.List<ChannelScanInfo> scanForChannels(java.lang.String settings)
                                         throws java.lang.UnsupportedOperationException,
                                                ArgumentSyntaxException,
                                                ScanException,
                                                ConnectionException

Scan a given communication device for available data channels.

Parameters:

settings - scanning settings. The syntax is driver specific.

Returns:

A list of channels that were found.

Throws:

ArgumentSyntaxException - if the syntax of the deviceAddress or settings string is incorrect.

java.lang.UnsupportedOperationException - if the method is not implemented by the driver.

ScanException - if an error occurs while scanning but the connection is still alive.

ConnectionException - if an error occurs while scanning and the connection was closed

read

java.lang.Object read(java.util.List<ChannelRecordContainer> containers,
                      java.lang.Object containerListHandle,
                      java.lang.String samplingGroup)
               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 constructor that takes only a flag should be used. The flag shall best describe the reason of failure. If no record is set the default Flag is Flag.DRIVER_ERROR_UNSPECIFIED. 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:

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.

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(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. The list of containers will overwrite the list passed by the previous startListening call. Will notify the given listener of new records that arrive on the data channels.

Parameters:

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(java.util.List<ChannelValueContainer> containers,
                       java.lang.Object containerListHandle)
                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:

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.

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.

disconnect

void disconnect()

Disconnects or closes the connection. Cleans up any resources associated with the connection.