Package org.sensorhub.api.command

Interface IStreamingControlInterface

All Superinterfaces:
IEventProducer
All Known Subinterfaces:
IStreamingControlInterfaceWithResult
public interface IStreamingControlInterface extends IEventProducer

Interface for all taskable components using SWE Common model to describe structure and encoding of commands they accept (e.g. actuators, processes...)

It is the responsibility of the implementation to report task status when commands are processed asynchronously. In particular, special care must be taken to avoid missing status updates in case of disconnections from the actual taskable system.

Since:
Mar 23, 2017

  • Field Details

  • Method Details

    • getParentProducer

      ICommandReceiver getParentProducer()
      Allows by-reference access to parent module
      Returns:
      parent module instance

    • getName

      String getName()
      Gets the interface name.
      Returns:
      name of this control interface

    • isEnabled

      boolean isEnabled()
      Checks if this interface is enabled
      Returns:
      true if interface is enabled, false otherwise

    • getCommandDescription

      DataComponent getCommandDescription()
      Retrieves description of command message Note that this can be a choice of multiple messages
      Returns:
      Data component containing message structure

    • getCommandEncoding

      default DataEncoding getCommandEncoding()
      Returns:
      The recommended encoding for the command parameters

    • validateCommand

      void validateCommand(ICommandData command) throws CommandException
      Validates the command parameters synchronously. This is called before the command is submitted for execution (it is used to avoid persisting invalid commands on the sensor hub).
      Parameters:
      command -
      Throws:
      CommandException - if the command is invalid

    • submitCommand

      CompletableFuture<ICommandStatus> submitCommand(ICommandData command)
      Submit the provided command to the receiving system.

      If a command is executed or rejected immediately, the status report returned by the future will have a final status code such as COMPLETED, REJECTED, or FAILED, and no further status reports are to be expected from the event channel.

      If a command is scheduled to be executed later or takes longer to execute, the initial status report returned by the future will have a non-final status code and must include a task ID. Subsequent reports are then sent via the dedicated event channel, using the same task ID, to provide status updates to the caller.

      The future should only complete exceptionally if there is an unexpected error. All errors associated to the processing of the command by the receiver system should be reported via a status object instead.

      Parameters:
      command - Command data (with ID set)
      Returns:
      A future that will be completed normally when the system is ready to receive the next command. Note that the command may not be fully executed or may not even be accepted at this point. In all cases, a valid status object must be returned by the future.

    • updateCommand

      default CompletableFuture<Void> updateCommand(ICommandData command)
      Update an existing command/task.
      Parameters:
      command - New command (with ID set)
      Returns:
      A future that will complete normally if the update is accepted or exceptionally if the update is rejected early.

    • cancelCommand

      default CompletableFuture<Void> cancelCommand(BigId cmdID)
      Cancels an existing command/task.
      Parameters:
      cmdID - The ID of the command to be canceled (as provided in the initial command submit)
      Returns:
      A future that will complete normally if the cancellation is accepted or exceptionally if the task cannot be canceled.