Package org.openhab.core.thing.binding.firmware

Interface ProgressCallback

@NonNullByDefault public interface ProgressCallback
The ProgressCallback is injected into the FirmwareUpdateHandler.updateFirmware(Firmware, ProgressCallback) operation in order to post progress information about the firmware update process. The progress of a firmware update can be defined by a sequence of ProgressSteps, a percentage progress or both. In order to use a sequence of ProgressSteps to indicate the update progress, it is necessary to first define a sequence using the method defineSequence(ProgressStep...). To indicate that the next progress step is going to be executed the method next() has to be used. For updates which are based on a percentage progress it is optional to define a sequence of ProgressSteps and to use the next() method. In order to indicate that the percentage progress has changed, the method update(progress) has to be used. It allows to update the percentage progress to a value between 0 and 100.
Author:
Thomas Höfer - Initial contribution, Christop Knauf - Added canceled, pending and update

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    canceled()
    Callback operation to indicate that the firmware update was canceled.
    void
    defineSequence(ProgressStep... sequence)
    Callback operation to define the ProgressSteps for the sequence of the firmware update.
    void
    failed(String errorMessageKey, Object... arguments)
    Callback operation to indicate that the firmware update has failed.
    void
    next()
    Callback operation to indicate that the next progress step is going to be executed.
    void
    pending()
    Callback operation to indicate that the firmware update is pending.
    void
    success()
    Callback operation to indicate that the firmware update was successful.
    void
    update(int progress)
    Callback operation to update the percentage progress of the firmware update.

  • Method Details

    • defineSequence

      void defineSequence(ProgressStep... sequence)
      Callback operation to define the ProgressSteps for the sequence of the firmware update. So if the operation is invoked with the following progress steps then this will mean that the firmware update implementation will initially download the firmware, then it will transfer the firmware to the actual device and in a final step it will trigger the update.
      Parameters:
      sequence - the progress steps describing the sequence of the firmware update process (must not be null or empty)
      Throws:
      IllegalArgumentException - if given sequence is null or empty

    • next

      void next()
      Callback operation to indicate that the next progress step is going to be executed. Following the example of the defineSequence(ProgressStep...) operation then the first invocation of this operation will indicate that firmware update handler is going to download the firmware, the second invocation will indicate that the handler is going to transfer the firmware to the device and consequently the third invocation will indicate that the handler is going to trigger the update. If the update is pending calling next indicates that the update is continued.
      Throws:
      IllegalStateException - if
      • update is not pending and there is no further step to be executed
      • if no sequence was defined

    • failed

      void failed(String errorMessageKey, Object... arguments)
      Callback operation to indicate that the firmware update has failed.
      Parameters:
      errorMessageKey - the key of the error message to be internationalized (must not be null or empty)
      arguments - the arguments to be injected into the internationalized error message (can be null)
      Throws:
      IllegalArgumentException - if given error message key is null or empty
      IllegalStateException - if update is already finished

    • success

      void success()
      Callback operation to indicate that the firmware update was successful.
      Throws:
      IllegalStateException - if update is finished

    • pending

      void pending()
      Callback operation to indicate that the firmware update is pending.
      Throws:
      IllegalStateException - if update is finished

    • canceled

      void canceled()
      Callback operation to indicate that the firmware update was canceled.
      Throws:
      IllegalStateException - if update is finished

    • update

      void update(int progress)
      Callback operation to update the percentage progress of the firmware update. This method can be used to provide detailed progress information additional to the sequence or even without a previous defined sequence.
      Parameters:
      progress - the progress between 0 and 100
      Throws:
      IllegalArgumentException - if given progress is < 0 or > 100 or if given progress is smaller than old progress
      IllegalStateException - if update is finished