org.openmuc.framework.dataaccess
Interface Channel


public interface Channel

The Channel class is used to access a single data field of a communication device. A desired channel can be obtained using the DataAccessService. A channel instance can be used to

Note that only the call of the read or write functions will actually result in a corresponding read or write request being sent to the communication device.


Method Summary
 void addListener(RecordListener listener)
          Adds a listener that is notified of new records received my sampling or listening.
 java.lang.String getChannelAddress()
          Gets the address of this channel.
 ChannelState getChannelState()
          Gets the current channel state.
 java.lang.String getDescription()
          Gets the description of this channel.
 java.lang.String getDeviceAddress()
          Gets the channel's device address.
 java.lang.String getDeviceDescription()
          Gets the description of the communication device that this channel belongs to.
 java.lang.String getDeviceName()
          Gets the name of the communication device that this channel belongs to.
 DeviceState getDeviceState()
          Gets the current state of the communication device that this channel belongs to.
 java.lang.String getDriverName()
          Gets the unique name of the communication driver that is used by this channel to read/write data.
 java.lang.String getInterfaceAddress()
          Gets the channel's interface address.
 java.lang.String getLabel()
          Gets the label of this channel.
 Record getLatestSample()
          Gets the latest record that was either sampled or received by listening or an application set using setLatestSample.
 Record getLoggedValue(long timestamp)
          Gets the value that has been stored in the framework's logging data base at the given timestamp.
 java.util.List<Record> getLoggedValues(long startTime)
          Gets all historical values that have been stored in the framework's logging data base since the given startTime.
 java.util.List<Record> getLoggedValues(long startTime, long endTime)
           
 int getLoggingInterval()
          Get the channel's configured logging interval in milliseconds.
 int getLoggingTimeOffset()
          Gets the channel's configured logging time offset in milliseconds.
 ReadRecordContainer getReadContainer()
          Gets a ReadRecordContainer that corresponds to this channel.
 int getSamplingInterval()
          Gets the channel's configured sampling interval in milliseconds.
 int getSamplingTimeOffset()
          Gets the channel's configured sampling time offset in milliseconds.
 java.lang.String getUnit()
          Gets the unit of this channel.
 ValueType getValueType()
          Gets the value type of this channel.
 WriteValueContainer getWriteContainer()
          Gets a WriteValueContainer that corresponds to this channel.
 boolean isConnected()
          Returns true if a connection to the channel's communication device exist.
 Record read(int timeout)
          Actively reads a value from the channel's corresponding data field in the connected communication device.
 void removeListener(RecordListener listener)
          Removes a record listener.
 void setLatestSample(Record record)
          Sets the latest sample record.
 Flag write(Value value, int timeout)
          Writes the given value to the channel's corresponding data field in the connected communication device.
 

Method Detail

getLabel

java.lang.String getLabel()
Gets the label of this channel. The label is usually a meaningful string because it is used to get Channel objects using the DataAccessService.

Returns:
the label of this channel. May be null if not set.

getChannelAddress

java.lang.String getChannelAddress()
Gets the address of this channel.

Returns:
the address of this channel.

getDescription

java.lang.String getDescription()
Gets the description of this channel.

Returns:
the description of this channel. The empty string if not configured.

getUnit

java.lang.String getUnit()
Gets the unit of this channel. The unit is used for informational purposes only. Neither the framework nor any driver does value conversions based on the configured unit.

Returns:
the unit of this channel.

getValueType

ValueType getValueType()
Gets the value type of this channel. The value type is for informational purposes only. A data base is encouraged to store values using the configured value type if it supports that value type. There is no guarantee that the driver and data base that provide the values for this channel actually use a Value implementation that corresponds to the configured value type.

But usually an application does not need to know the value type of the channel because it can use the value type of its choice by using the corresponding function of the Value interface. Conversion is done transparently.

Returns:
the value type of this channel.

getSamplingInterval

int getSamplingInterval()
Gets the channel's configured sampling interval in milliseconds.

Returns:
the channel's configured sampling interval in milliseconds. Returns -1 if not configured.

getSamplingTimeOffset

int getSamplingTimeOffset()
Gets the channel's configured sampling time offset in milliseconds.

Returns:
the channel's configured sampling time offset in milliseconds. Returns the default of 0 if not configured.

getLoggingInterval

int getLoggingInterval()
Get the channel's configured logging interval in milliseconds.

Returns:
the channel's configured logging interval in milliseconds. Returns -1 if not configured.

getLoggingTimeOffset

int getLoggingTimeOffset()
Gets the channel's configured logging time offset in milliseconds.

Returns:
the channel's configured logging time offset in milliseconds. Returns the default of 0 if not configured.

getDriverName

java.lang.String getDriverName()
Gets the unique name of the communication driver that is used by this channel to read/write data.

Returns:
the unique name of the communication driver that is used by this channel to read/write data.

getInterfaceAddress

java.lang.String getInterfaceAddress()
Gets the channel's interface address.

Returns:
the channel's interface address. May be null if not configured.

getDeviceAddress

java.lang.String getDeviceAddress()
Gets the channel's device address.

Returns:
the channel's device address.

getDeviceName

java.lang.String getDeviceName()
Gets the name of the communication device that this channel belongs to.

Returns:
the name of the communication device that this channel belongs to. The empty string if not configured.

getDeviceDescription

java.lang.String getDeviceDescription()
Gets the description of the communication device that this channel belongs to.

Returns:
the description of the communication device that this channel belongs to. The empty string if not configured.

getChannelState

ChannelState getChannelState()
Gets the current channel state.

Returns:
the current channel state.

getDeviceState

DeviceState getDeviceState()
Gets the current state of the communication device that this channel belongs to.

Returns:
the current state of the communication device that this channel belongs to.

addListener

void addListener(RecordListener listener)
Adds a listener that is notified of new records received my sampling or listening.

Parameters:
listener - the record listener that is notified of new records.

removeListener

void removeListener(RecordListener listener)
Removes a record listener.

Parameters:
listener - the listener that no longer shall be notified new records.

isConnected

boolean isConnected()
Returns true if a connection to the channel's communication device exist.

Returns:
true if a connection to the channel's communication device exist.

getLatestSample

Record getLatestSample()
Gets the latest record that was either sampled or received by listening or an application set using setLatestSample.

Returns:
the latest sample.

setLatestSample

void setLatestSample(Record record)
Sets the latest sample record. This function should only be used with channels that are neither sampling nor listening. Using this function it is possible to realize "virtual" channels that get their data not from drivers but from applications in the framework.

Note that the framework treats the passed record in exactly the same way as if it had been received from a driver. In particular that means:

Parameters:
record - the record that the latest sample is set to.

write

Flag write(Value value,
           int timeout)
Writes the given value to the channel's corresponding data field in the connected communication device. If a timeout or other error occurs, the returned Flag will indicate this.

Parameters:
value - the value that is to be written
timeout - the time in milliseconds after which the write process shall be interrupted and the timeout flag is returned. A timeout of 0 indicates infinite time.
Returns:
the flag indicating whether the value was successfully written ( Flag.VALID) or not (any other flag).

getWriteContainer

WriteValueContainer getWriteContainer()
Gets a WriteValueContainer that corresponds to this channel. This container can be passed to the write function of DataAccessService to write several values in one transaction.

Returns:
a WriteValueContainer that corresponds to this channel.

read

Record read(int timeout)
Actively reads a value from the channel's corresponding data field in the connected communication device. If an error occurs it will be indicated in the returned record's flag.

Parameters:
timeout - the time in milliseconds after which the read process shall be interrupted and the timeout flag is set.
Returns:
the record containing the value read, the time the value was received and a flag indicating success ( Flag.VALID) or a an error (any other flag).

getReadContainer

ReadRecordContainer getReadContainer()
Gets a ReadRecordContainer that corresponds to this channel. This container can be passed to the read function of DataAccessService to read several values in one transaction.

Returns:
a ReadRecordContainer that corresponds to this channel.

getLoggedValue

Record getLoggedValue(long timestamp)
                      throws DataLoggerNotAvailableException,
                             java.io.IOException
Gets the value that has been stored in the framework's logging data base at the given timestamp. Note that it is the logging data base's choice whether it stores values using the timestamp that the driver recorded when it received it or the timestamp at which the value is to be logged. If the former is the case then this function is not useful because it is impossible for an application to know the exact time at which a value was received. In this case use getLoggedValues instead.

Parameters:
timestamp - the time as milliseconds since midnight, January 1, 1970 UTC.
Returns:
the record that the framework's data base stored for the given timestamp.
Throws:
DataLoggerNotAvailableException
java.io.IOException

getLoggedValues

java.util.List<Record> getLoggedValues(long startTime)
                                       throws DataLoggerNotAvailableException,
                                              java.io.IOException
Gets all historical values that have been stored in the framework's logging data base since the given startTime.

Parameters:
startTime - the time as milliseconds since midnight, January 1, 1970 UTC.
Returns:
a list of records that the framework's data base stored since the given startTime.
Throws:
DataLoggerNotAvailableException
java.io.IOException

getLoggedValues

java.util.List<Record> getLoggedValues(long startTime,
                                       long endTime)
                                       throws DataLoggerNotAvailableException,
                                              java.io.IOException
Throws:
DataLoggerNotAvailableException
java.io.IOException