|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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:
debug
. 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.
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 |
---|
java.lang.String getId()
java.lang.String getDescription()
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
scanFilter
- a string whose syntax depends on the specific communication driver being used. It tells the driver
where to scan for communication devices.
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
java.util.List<ChannelScanInformation> scanForChannels(DeviceConnection connection, int timeout) throws java.lang.UnsupportedOperationException, ConnectionException
connection
- ihe DeviceConnection of the communication device that is to be scanned for data channels.
MethodNotSupportedException
- if the method is not implemented by the driver.
java.io.IOException
- if an error occurs while scanning.
java.lang.UnsupportedOperationException
ConnectionException
java.lang.Object connect(java.lang.String interfaceAddress, java.lang.String deviceAddress, java.lang.String settings, int timeout) throws 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.timeout
- the time in milliseconds after which the connection attempt shall be aborted and a
ConnectionException
shall be thrown.
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, int timeout) throws java.lang.UnsupportedOperationException, ConnectionException
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.
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 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.
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, int timeout) 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 timeout
- see read for detailed documentation.
null
.
java.lang.UnsupportedOperationException
- if the method is not implemented by the driver.
ConnectionException
- if the connection to the device was interrupted.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |