Package com.tccc.kos.core.service.hardware

Interface IfaceAware<T extends BinaryMsgIface>

All Known Subinterfaces:
IfaceAwareBoard<T>, IfaceAwareNode<T>, IfaceAwareService<T>
public interface IfaceAware<T extends BinaryMsgIface>
Interface that indicates the associated instance has a BinaryMsgIface available. This is commonly used with IfaceAwareFactory which can create instances. It is common that a Board class in KOS is linked to physical hardware using an adapter. The Board class then needs to get access to the BinaryMsgSession to the adapter in order to create an instance of the iface used to communicate to the board.

To simplify this process, an adapter can implement the board iface. This allows HardwareService to automatically detect when the adapter is started, fetch the board details, and link the physical board to the logical board without any additional code. However, this doesn't solve the problem of creating the custom iface instance to interact with the board.

A board that implements IfaceAware that leverages the board detection logic mentioned above, will automatically call createIface() when the board is linked and make the iface available via getIface(). This eliminates the need to override the link callbacks just to add / remove a custom iface instance.

Version:
2025-06-19

  • Method Details

    • getIface

      T getIface()
      Return the associated iface. This may return null if no iface is available.

    • setIface

      void setIface(T iface)
      Set the iface.

    • withIface

      default void withIface(IfaceAware.IfaceCallback<T> callback)
      Run the specified code only if the iface is connected. The current iface will be passed to the callback. This value will never change while the callback is running, unlike the value of getIface() which can be changed at any time in reaction to a disconnect event.

      Any exception thrown by the callback will be thrown by this method.

    • withIface

      default void withIface(IfaceAware.IfaceCallback<T> callback, Runnable orElse)
      Run the specified callback if the iface is connected, or else run the runnable if not connected. The current iface will be passed to the callback. This value will never change while the callback is running, unlike the value of getIface() which can be changed at any time in reaction to a disconnect event.

      Any exception thrown by the callback will be thrown by this method.

      Parameters:
      callback - callback to run if iface exists
      orElse - optional runnable to call if iface is null

    • withIfaceOrThrow

      default void withIfaceOrThrow(IfaceAware.IfaceCallback<T> callback)
      Run the specified code only if the iface is connected. If not connected, throw NotLinkedException .

      The current iface will be passed to the callback. This value will never change while the callback is running, unlike the value of getIface() which can be changed at any time in reaction to a disconnect event.

      Any exception thrown by the callback will be thrown by this method.

    • withIfaceCatch

      default Exception withIfaceCatch(IfaceAware.IfaceCallback<T> callback)
      Run the specified code only if the iface is connected. This will catch any exception in the callback and return it as the return value of this method.
      Parameters:
      callback - callback to run if iface exists

    • withIfaceCatch

      default Exception withIfaceCatch(IfaceAware.IfaceCallback<T> callback, IfaceAware.IfaceExceptionHandler handler)
      Run the specified callback if the iface is connected, or else run the specified runnable. This will catch any exception in the callback and return it as the return value of this method. Any exception thrown by the runnable will be thrown by this method.
      Parameters:
      callback - callback to run if iface exists
      handler - optional handler to process exception thrown by callback

    • withIfaceCatch

      default Exception withIfaceCatch(IfaceAware.IfaceCallback<T> callback, Runnable orElse)
      Run the specified callback if the iface is connected. This will catch any exception in the callback and pass it to the optional handler as well as return it from this method.
      Parameters:
      callback - callback to run if iface exists
      orElse - optional runnable if iface is null

    • withIfaceCatch

      default Exception withIfaceCatch(IfaceAware.IfaceCallback<T> callback, Runnable orElse, IfaceAware.IfaceExceptionHandler handler)
      Run the specified callback if the iface is connected, or else run the specified runnable. This will catch any exception in the callback and pass it to the optional handler as well as return it from this method. Any exception thrown by the runnable will be thrown by this method.
      Parameters:
      callback - callback to run if iface exists
      orElse - optional runnable if iface is null
      handler - optional handler to process exception thrown by callback