Package org.openmuc.framework.dataaccess

Interface ChannelRuntime

  • All Known Subinterfaces:
    Channel
    public interface ChannelRuntime
    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.

    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.
      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.
      ReadRecordContainer getReadContainer()
      Returns a ReadRecordContainer that corresponds to 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

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