Package 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
    • Access the latest record. That is the latest data record that the framework either sampled or received by listening or an application set using setLatestRecord.
    • Directly read/write data from/to the corresponding communication device.
    • Access historical data that was stored by a data logger such as SlotsDB.
    • Get configuration information about this channel such as its unit.

    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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void addListener​(RecordListener listener)
      Adds a listener that is notified of new records received by sampling or listening.
      java.lang.String getChannelAddress()
      Returns the address of this channel.
      ChannelState getChannelState()
      Returns the current channel state.
      java.lang.String getDescription()
      Returns the description of this channel.
      java.lang.String getDeviceAddress()
      Returns the channel's device address.
      java.lang.String getDeviceDescription()
      Returns the description of the communication device that this channel belongs to.
      java.lang.String getDeviceName()
      Returns the name of the communication device that this channel belongs to.
      DeviceState getDeviceState()
      Returns the current state of the communication device that this channel belongs to.
      java.lang.String getDriverName()
      Returns the unique name of the communication driver that is used by this channel to read/write data.
      java.lang.String getId()
      Returns the ID of this channel.
      Record getLatestRecord()
      Returns the latest record of this channel.
      Record getLoggedRecord​(long time)
      Returns the logged data record whose timestamp equals the given time.
      java.util.List<Record> getLoggedRecords​(long startTime)
      Returns a list of all logged data records with timestamps from startTime up until now.
      java.util.List<Record> getLoggedRecords​(long startTime, long endTime)
      Returns a list of all logged data records with timestamps from startTime to endTime inclusive.
      int getLoggingInterval()
      Returns the channel's configured logging interval in milliseconds.
      java.lang.String getLoggingSettings()  
      int getLoggingTimeOffset()
      Returns the channel's configured logging time offset in milliseconds.
      ReadRecordContainer getReadContainer()
      Returns a ReadRecordContainer that corresponds to this channel.
      int getSamplingInterval()
      Returns the channel's configured sampling interval in milliseconds.
      int getSamplingTimeOffset()
      Returns the channel's configured sampling time offset in milliseconds.
      int getSamplingTimeout()
      Returns the parent's device's configured sampling timeout in milliseconds.
      double getScalingFactor()
      Returns the scaling factor.
      java.lang.String getSettings()
      Returns the settings of this channel.
      java.lang.String getUnit()
      Returns the unit of this channel.
      ValueType getValueType()
      Returns the value type of this channel.
      WriteValueContainer getWriteContainer()
      Returns a WriteValueContainer that corresponds to this channel.
      boolean isConnected()
      Returns true if a connection to the channel's communication device exist.
      Record read()
      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 setLatestRecord​(Record record)
      Sets the latest record of this channel.
      Flag write​(Value value)
      Writes the given value to the channel's corresponding data field in the connected communication device.
      void writeFuture​(java.util.List<FutureValue> values)
      Schedules a List<records> with future timestamps as write tasks
      This function will schedule single write tasks to the provided timestamps.
      Once this function is called, previously scheduled write tasks will be erased.

    • Method Detail

      • getId

        java.lang.String getId()
        Returns the ID of this channel. The ID is usually a meaningful string. It is used to get Channel objects using the DataAccessService.
        Returns:
        the ID of this channel.

      • getChannelAddress

        java.lang.String getChannelAddress()
        Returns the address of this channel. Returns the empty string if not configured.
        Returns:
        the address of this channel.

      • getDescription

        java.lang.String getDescription()
        Returns the description of this channel. Returns the empty string if not configured.
        Returns:
        the description of this channel.

      • getSettings

        java.lang.String getSettings()
        Returns the settings of this channel. Returns the empty string if not configured.
        Returns:
        the settings of this channel.

      • getLoggingSettings

        java.lang.String getLoggingSettings()

      • getUnit

        java.lang.String getUnit()
        Returns the unit of this channel. Returns the empty string if not configured. 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()
        Returns the value type of this channel. The value type specifies how the value of the latest record of a channel is stored. A data logger is encouraged to store values using the configured value type if it supports that value type.

        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 Value (e.g. Value.asDouble()). Necessary conversions will be done transparently.

        If no value type was configured, the default ValueType.DOUBLE is used.

        Returns:
        the value type of this channel.

      • getScalingFactor

        double getScalingFactor()
        Returns the scaling factor. Returns 1.0 if the scaling factor is not configured.

        The scaling factor is applied in the following cases:

        • Values received by this channel's driver or from apps through setLatestRecord(Record) are multiplied with the scaling factor before they are stored in the latest record.
        • Values written (e.g. using write(Value)) are divided by the scaling factor before they are handed to the driver for transmission.
        Returns:
        the scaling factor

      • getSamplingInterval

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

      • getSamplingTimeOffset

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

      • getSamplingTimeout

        int getSamplingTimeout()
        Returns the parent's device's configured sampling timeout in milliseconds. Returns the default of 0 if not configured.
        Returns:
        the parent's device's configured sampling timeout in milliseconds.

      • getLoggingInterval

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

      • getLoggingTimeOffset

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

      • getDriverName

        java.lang.String getDriverName()
        Returns 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.

      • getDeviceAddress

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

      • getDeviceName

        java.lang.String getDeviceName()
        Returns the name of the communication device that this channel belongs to. The empty string if not configured.
        Returns:
        the name of the communication device that this channel belongs to.

      • getDeviceDescription

        java.lang.String getDeviceDescription()
        Returns the description of the communication device that this channel belongs to. The empty string if not configured.
        Returns:
        the description of the communication device that this channel belongs to.

      • getChannelState

        ChannelState getChannelState()
        Returns the current channel state.
        Returns:
        the current channel state.

      • getDeviceState

        DeviceState getDeviceState()
        Returns 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 by 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 shall be removed.

      • 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.

      • getLatestRecord

        Record getLatestRecord()
        Returns the latest record of this channel. Every channel holds its latest record in memory. There exist three possible source for the latest record:
        • It may be provided by a communication driver that was configured to sample or listen on the channel. In this case the timestamp of the record represents the moment in time that the value was received by the driver.
        • An application may also set the latest record using setLatestRecord.
        • Finally values written using write are also stored as the latest record

        Note that the latest record is never NULL. When a channel is first created its latest record is automatically initialized with a flag that indicates that its value is not valid.

        Returns:
        the latest record.

      • setLatestRecord

        void setLatestRecord​(Record record)
        Sets the latest record of this channel. 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:

        • If data logging is enabled for this channel the latest record is being logged by the registered loggers.
        • Other applications can access the value set by this function using getLatestRecord.
        • Applications are notified of the new record if they registered as listeners using addListener.
        • If a scaling factor has been configured for this channel then the value passed to this function is scaled.
        Parameters:
        record - the record to be set.

      • write

        Flag write​(Value value)
        Writes the given value to the channel's corresponding data field in the connected communication device. If an error occurs, the returned Flag will indicate this.
        Parameters:
        value - the value that is to be written
        Returns:
        the flag indicating whether the value was successfully written ( Flag.VALID) or not (any other flag).

      • writeFuture

        void writeFuture​(java.util.List<FutureValue> values)
        Schedules a List<records> with future timestamps as write tasks
        This function will schedule single write tasks to the provided timestamps.
        Once this function is called, previously scheduled write tasks will be erased.
        Parameters:
        values - a list of future write values.

      • getWriteContainer

        WriteValueContainer getWriteContainer()
        Returns 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()
        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.
        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()
        Returns 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.

      • getLoggedRecord

        Record getLoggedRecord​(long time)
                throws DataLoggerNotAvailableException,
                       java.io.IOException
        Returns the logged data record whose timestamp equals the given time. Note that it is the data logger'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 getLoggedRecords instead.
        Parameters:
        time - the time in milliseconds since midnight, January 1, 1970 UTC.
        Returns:
        the record that has been stored by the framework's data logger at the given timestamp. Returns null if no record exists for this point in time.
        Throws:
        DataLoggerNotAvailableException - if no data logger is installed and therefore no logged data can be accessed.
        java.io.IOException - if any kind of error occurs accessing the logged data.

      • getLoggedRecords

        java.util.List<Record> getLoggedRecords​(long startTime)
                                 throws DataLoggerNotAvailableException,
                                        java.io.IOException
        Returns a list of all logged data records with timestamps from startTime up until now.
        Parameters:
        startTime - the starting time in milliseconds since midnight, January 1, 1970 UTC. inclusive
        Returns:
        a list of all logged data records with timestamps from startTime up until now.
        Throws:
        DataLoggerNotAvailableException - if no data logger is installed and therefore no logged data can be accessed.
        java.io.IOException - if any kind of error occurs accessing the logged data.

      • getLoggedRecords

        java.util.List<Record> getLoggedRecords​(long startTime,
                                        long endTime)
                                 throws DataLoggerNotAvailableException,
                                        java.io.IOException
        Returns a list of all logged data records with timestamps from startTime to endTime inclusive.
        Parameters:
        startTime - the starting time in milliseconds since midnight, January 1, 1970 UTC. inclusive
        endTime - the ending time in milliseconds since midnight, January 1, 1970 UTC. inclusive
        Returns:
        a list of all logged data records with timestamps from startTime to endTime inclusive.
        Throws:
        DataLoggerNotAvailableException - if no data logger is installed and therefore no logged data can be accessed.
        java.io.IOException - if any kind of error occurs accessing the logged data.