Package com.tccc.kos.core.service.criticaldata

Interface CriticalDataSource

public interface CriticalDataSource
Interface for objects that can store and retrieve critical data. Critical data is information that must survive board swaps in order for the device to continue to function properly. For example, if the kOS node that contains the disk is replaced with another board, certain key information about the device needs to survive, such as the device serial number, which typically needs to match the sticker placed on the chassis during manufacturing.

The CriticalDataService provides this capability by using multiple sources to store critical data in other pieces of hardware, typically other embedded boards within the device. By using a voting algorithm, the service can recover this critical data even when boards are swapped during maintenance.

A CriticalDataSource is responsible for storing and fetching an array of bytes from some type of persistent storage. The source is responsible for accurately returning the correct number of bytes when fetching critical data. This implies that the source needs to persist the length of the data as well as the data itself. The data provided by CriticalDataService is compressed and contains a CRC32 check, so sources need not duplicate this capability.

Sources are typically added to a BeanContext which will cause them to be autowired into the CriticalDataService. Sources will be checked as they are added, or when they become ready if they implement Ready. If a source is not able to access hardware at this point, the source needs to notify the CriticalDataService when it is ready by calling criticalDataService.ready(source). Even if critical data has been discovered, the source must still notify the service that it is ready in order to ensure that critical data is accurately replicated back to the source.

Version:
2024-06-24

  • Method Details

    • getCriticalData

      byte[] getCriticalData() throws Exception
      Return any available critical data. If the source is not yet ready to access hardware, return null;
      Returns:
      map of critical data or null
      Throws:
      Exception

    • setCriticalData

      boolean setCriticalData(byte[] bytes) throws Exception
      Store the critical data to the source.
      Parameters:
      bytes - the data to store
      Returns:
      true if the write was successful
      Throws:
      Exception

    • getSourceMaxLength

      int getSourceMaxLength()
      Return the max number of bytes of critical data that the source can store. If the source is too small to store the actual critical data, it will only be used to store the signature of the data. This allows the source to continue to participate in the voting algorithm without actually having all the data.

    • getSourceWeight

      default double getSourceWeight()
      Return the weight that this source has. Weights are used to determine which data is correct when we have to resolve ambiguity. The higher the weight, the more we trust this particular source. Any weight over 1.0 should be fractional to avoid ties in the voting algorithm. For example, a weight of 2.0 from a single source would tie two 1.0 sources that agree. In this example, a weight of 1.5 may be more appropriate as there won't be a tie and two sources that agree is probably more trustworthy than a single source that has no other matching sources.
      Returns:
      the weight of this source

    • getCriticalDataReady

      ReadyIndicator getCriticalDataReady()
      Return the ReadyIndicator for the source. If the source is always accessible, return null. If the source is only accessible after some hardware initialization, return the ReadyIndicator that indicates the source is usable.
      Returns:
      ReadyIndicator for the source or null if source is always ready

    • isCriticalDataReady

      default boolean isCriticalDataReady()
      Return true if the source is ready. This will return true if getCriticalDataReady() returns null or if the indicator is ready.