Improve Callback/Promise APIs

[sbordet]

Target Jetty version(s) 12

Enhancement Description Callback (and Promise) APIs currently have only 2 methods: succeeded() and failed(Throwable).

These methods are used by both code that acts on the callback received from some other code (by calling the methods), and by code that implements the methods and passes the callback around.

This model does not allow to verify, for example, whether a callback has been called at all, or whether it has been called multiple times, possibly for different methods (i.e. both succeeded and failed -- see #7086 for one such bug).

The proposal is to have:

class Callback {
  // Command
  [final] void succeed() {
    // atomically flip some state
    if (flipState()) {
      onSucceeded();
    }
  }

  // Event handler
  protected void onSucceeded() {
    // Implement this
  }

  // Similar for failures
}

By dumping callbacks via dump(), for example, we would know whether they have been called or not.

We can even have the command methods to call a single method:

class Callback {
  void handle(Throwable failure) {
    if (failure == null) {
      onSuccess();
    } else {
      onFailure(failure);
    }
  }
}

This would simplify wrapping callbacks with "complete" actions that must always be executed before or after the event, whatever the event is, and it will also play nicely with CompletableFuture.handle/whenComplete.

[gregw]

I see this more as a utility implementation of Callback (like CompletableFututre is a utility implementation of Future).

It might also be good to have an abstract version where the state being switched is something useful. Eg in my jetty-12 with I'm already using this pattern over and over again... but the state switched is an atomic reference to another object that is being used.

So i can see an abstract version with the state mechanism externalized and a concrete version that uses an AtomicBoolean as the state.

I also like the single method alternative... But should be called complete(Throwable).... maybe it is on a wrapper or a static utility method?

[sbordet]

I see this more as a utility implementation of Callback (like CompletableFututre is a utility implementation of Future).

Sure, although eventually nobody uses Future or CompletionStage when it can use CompletableFuture... I'm not sure we have the case for being polymorphic on a Callback interface... it can just be a class like CompletableFuture is.

[github-actions[bot]]

This issue has been automatically marked as stale because it has been a full year without activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions[bot]]

This issue has been automatically marked as stale because it has been a full year without activity. It will be closed if no further activity occurs. Thank you for your contributions.