Module com.dlsc.gemsfx
Package com.dlsc.gemsfx.util

Class ServiceInvocation<T>

java.lang.Object
com.dlsc.gemsfx.util.ServiceInvocation<T>
Type Parameters:
T - the type of the result object wrapped inside the retrofit response
All Implemented Interfaces:
javafx.concurrent.Worker<T>
public final class ServiceInvocation<T> extends Object implements javafx.concurrent.Worker<T>
A utility class used to invoke backend services via Retrofit on a separate thread and to handle the response on the UI thread. This class makes it extremely easy to do this and using it results in very compact and nicely structured code (also thanks to a fluent API).

Example 1:

In this example we assume that "myService.loadData()" is a Retrofit call. Executing it returns a Retrofit "Response" object. Hence, this lambda implements the "ServiceSupplier" interface required by the service invocation. 
         ServiceInvocation.create("Load data ...", () -> myService.loadData().execute())
              .onSuccess(data -> listView.getItems().setAll(data)).execute();

One can see that in this fluent API the last call goes to the service invocation's execute() method. However, it is advised to execute service invocations in a central place within the application's user interface codebase. This makes it easier to register default error handlers and to provide feedback to the user regarding the status of the execution of a service invocation. Example 2 shows how this is done.

Example 2:

         ui.execute(ServiceInvocation.create("Load data ...", () -> myService.loadData().execute())
              .onSuccess(data -> listView.getItems().setAll(data)));

Various consumers can be registered with a service invocation before it gets executed. Some of these consumers have a second version with the postfix "default" to their name, e.g. "onFailure" and "onFailureDefault". The idea behind this is that an application might provide a central place where service invocations are being executed (e.g. Window.execute(si) or Workbench.execute(si)) and wants to set "default" handlers in that location. At the same time each specific occurrence of a service invocation might require its own / more specific handlers.

  • Property Details

    • state

      public javafx.beans.property.ReadOnlyObjectProperty<javafx.concurrent.Worker.State> stateProperty
      Returns a read-only property for observing the state of the service invocation.
      Specified by:
      stateProperty in interface javafx.concurrent.Worker<T>
      See Also:

    • value

      public javafx.beans.property.ReadOnlyObjectProperty<T> valueProperty
      Specified by:
      valueProperty in interface javafx.concurrent.Worker<T>
      See Also:

    • exception

      public javafx.beans.property.ReadOnlyObjectProperty<Throwable> exceptionProperty
      Specified by:
      exceptionProperty in interface javafx.concurrent.Worker<T>
      See Also:

    • workDone

      public javafx.beans.property.ReadOnlyDoubleProperty workDoneProperty
      Specified by:
      workDoneProperty in interface javafx.concurrent.Worker<T>
      See Also:

    • totalWork

      public javafx.beans.property.ReadOnlyDoubleProperty totalWorkProperty
      Specified by:
      totalWorkProperty in interface javafx.concurrent.Worker<T>
      See Also:

    • progress

      public javafx.beans.property.ReadOnlyDoubleProperty progressProperty
      Specified by:
      progressProperty in interface javafx.concurrent.Worker<T>
      See Also:

    • running

      public javafx.beans.property.ReadOnlyBooleanProperty runningProperty
      Specified by:
      runningProperty in interface javafx.concurrent.Worker<T>
      See Also:

    • message

      public javafx.beans.property.ReadOnlyStringProperty messageProperty
      Specified by:
      messageProperty in interface javafx.concurrent.Worker<T>
      See Also:

    • title

      public javafx.beans.property.ReadOnlyStringProperty titleProperty
      Specified by:
      titleProperty in interface javafx.concurrent.Worker<T>
      See Also:

  • Method Details

    • create

      public static <T> ServiceInvocation<T> create(String name, ServiceInvocation.ServiceSupplier<T> supplier)
      Creates a new service invocation instance.
      Type Parameters:
      T - the type of the response object
      Parameters:
      name - the name of this invocation
      supplier - the supplier returning the service for invocation
      Returns:
      a service invocation

    • execute

      public CompletableFuture<Void> execute()
      Executes the service invocation with the default executor.
      Returns:
      a completable future object usable for chaining

    • execute

      public CompletableFuture<Void> execute(Executor executor)
      Executes the service invocation with the given executor.
      Returns:
      a completable future object usable for chaining

    • getName

      public String getName()
      Returns the name of the service invocation.
      Returns:
      the name

    • withDelay

      public ServiceInvocation<T> withDelay(long delay)
      Introduces an artificial delay for the invocation. The call to the backend will happen after the delay time has passed.
      Parameters:
      delay - the delay in milliseconds
      Returns:
      the service invocation

    • withSimulatingFailure

      public ServiceInvocation<T> withSimulatingFailure(boolean failure)
      An easy way to explicitly make the service invocation fail in order to test the handling of failures by the application.
      Parameters:
      failure - enables / disables the failure
      Returns:
      the service invocation

    • isSimulatingFailure

      public boolean isSimulatingFailure()
      Returns true if the service invocation will intentionally fail (see also withSimulatingFailure(boolean)).
      Returns:
      true if the invocation will fail

    • onStart

      public ServiceInvocation<T> onStart(Consumer<String> onStart)
      A consumer that will be invoked first when the execute() method gets invoked.
      Parameters:
      onStart - the "on start" handler.
      Returns:
      the service invocation

    • onSuccess

      public ServiceInvocation<T> onSuccess(Consumer<T> onSuccess)
      A consumer that will be invoked when the backend service invocation was successful. The consumer will receive the expected result object.
      Parameters:
      onSuccess - the "on success" handler.
      Returns:
      the service invocation

    • onSuccessDetailed

      public ServiceInvocation<T> onSuccessDetailed(Consumer<retrofit2.Response<T>> onSuccessDetailed)
      A consumer that will be invoked when the backend service invocation was successful. The consumer will receive the response object wrapping the expected result object.
      Parameters:
      onSuccessDetailed - the "on success detailed" handler.
      Returns:
      the service invocation

    • onFailure

      public ServiceInvocation<T> onFailure(BiConsumer<String,String> onFailure)
      A consumer that will be invoked when the backend service invocation was not successful. The consumer will receive the name of the service invocation and an error message.
      Parameters:
      onFailure - the "on failure" handler.
      Returns:
      the service invocation

    • onFailureDefault

      public ServiceInvocation<T> onFailureDefault(BiConsumer<String,String> onFailureDefault)
      A default consumer that will be invoked when the backend service invocation was not successful. The consumer will receive the name of the service invocation and an error message.
      Parameters:
      onFailureDefault - the "on failure default" handler.
      Returns:
      the service invocation

    • onFailureDetailed

      public ServiceInvocation<T> onFailureDetailed(BiConsumer<String,retrofit2.Response> onFailureDetailed)
      A consumer that will be invoked when the backend service invocation was not successful. The consumer will receive the name of the service invocation and the full response object.
      Parameters:
      onFailureDetailed - the "on failure detailed" handler.
      Returns:
      the service invocation

    • onFailureDetailedDefault

      public ServiceInvocation<T> onFailureDetailedDefault(BiConsumer<String,retrofit2.Response> onFailureDetailedDefault)
      A default consumer that will be invoked when the backend service invocation was not successful. The consumer will receive the name of the service invocation and the full response object.
      Parameters:
      onFailureDetailedDefault - the "on failure detailed default" handler.
      Returns:
      the service invocation

    • onStatusCode

      public ServiceInvocation<T> onStatusCode(HttpStatusCode code, BiConsumer<String,String> onStatusCode)
      A consumer that will be invoked when the backend returns the given HTTP status code. The consumer receives the name of the service invocation and the status message.
      Parameters:
      code - the status code for which the consumer will be registered
      onStatusCode - the "on status code" handler.
      Returns:
      the service invocation

    • onStatusCodeDefault

      public ServiceInvocation<T> onStatusCodeDefault(HttpStatusCode code, BiConsumer<String,String> onStatusCodeDefault)
      A default consumer that will be invoked when the backend returns the given HTTP status code. The consumer receives the name of the service invocation and the status message.
      Parameters:
      code - the status code for which the consumer will be registered
      onStatusCodeDefault - the "on status code" handler.
      Returns:
      the service invocation

    • onException

      public ServiceInvocation<T> onException(BiConsumer<String,Exception> onException)
      A consumer that will be invoked in case of an exception during the execution of the service invocation. The consumer will receive the name of the service invocation and the exception object.
      Parameters:
      onException - the consumer
      Returns:
      the service invocation

    • onExceptionDefault

      public ServiceInvocation<T> onExceptionDefault(BiConsumer<String,Exception> onExceptionDefault)
      A default consumer that will be invoked in case of an exception during the execution of the service invocation. The consumer will receive the name of the service invocation and the exception object.
      Parameters:
      onExceptionDefault - the consumer
      Returns:
      the service invocation

    • onFinally

      public ServiceInvocation<T> onFinally(Runnable onFinally)
      A runnable that will be invoked after the service invocation has completed. No matter if an exception occurred or not.
      Parameters:
      onFinally - the runnable
      Returns:
      the service invocation

    • getState

      public javafx.concurrent.Worker.State getState()
      Returns the worker state of the service invocation (running, succeeded, ...).
      Specified by:
      getState in interface javafx.concurrent.Worker<T>
      Returns:
      the state of the service invocation according to the Worker interface

    • stateProperty

      public javafx.beans.property.ReadOnlyObjectProperty<javafx.concurrent.Worker.State> stateProperty()
      Returns a read-only property for observing the state of the service invocation.
      Specified by:
      stateProperty in interface javafx.concurrent.Worker<T>
      Returns:
      the state property
      See Also:

    • getValue

      public T getValue()
      Gets the value of the value property.
      Specified by:
      getValue in interface javafx.concurrent.Worker<T>
      Property description:
      Returns:
      the value of the value property
      See Also:

    • valueProperty

      public javafx.beans.property.ReadOnlyObjectProperty<T> valueProperty()
      Specified by:
      valueProperty in interface javafx.concurrent.Worker<T>
      Returns:
      the value property
      See Also:

    • getException

      public Throwable getException()
      Gets the value of the exception property.
      Specified by:
      getException in interface javafx.concurrent.Worker<T>
      Property description:
      Returns:
      the value of the exception property
      See Also:

    • exceptionProperty

      public javafx.beans.property.ReadOnlyObjectProperty<Throwable> exceptionProperty()
      Specified by:
      exceptionProperty in interface javafx.concurrent.Worker<T>
      Returns:
      the exception property
      See Also:

    • getWorkDone

      public double getWorkDone()
      Gets the value of the workDone property.
      Specified by:
      getWorkDone in interface javafx.concurrent.Worker<T>
      Property description:
      Returns:
      the value of the workDone property
      See Also:

    • workDoneProperty

      public javafx.beans.property.ReadOnlyDoubleProperty workDoneProperty()
      Specified by:
      workDoneProperty in interface javafx.concurrent.Worker<T>
      Returns:
      the workDone property
      See Also:

    • getTotalWork

      public double getTotalWork()
      Gets the value of the totalWork property.
      Specified by:
      getTotalWork in interface javafx.concurrent.Worker<T>
      Property description:
      Returns:
      the value of the totalWork property
      See Also:

    • totalWorkProperty

      public javafx.beans.property.ReadOnlyDoubleProperty totalWorkProperty()
      Specified by:
      totalWorkProperty in interface javafx.concurrent.Worker<T>
      Returns:
      the totalWork property
      See Also:

    • getProgress

      public double getProgress()
      Gets the value of the progress property.
      Specified by:
      getProgress in interface javafx.concurrent.Worker<T>
      Property description:
      Returns:
      the value of the progress property
      See Also:

    • progressProperty

      public javafx.beans.property.ReadOnlyDoubleProperty progressProperty()
      Specified by:
      progressProperty in interface javafx.concurrent.Worker<T>
      Returns:
      the progress property
      See Also:

    • runningProperty

      public javafx.beans.property.ReadOnlyBooleanProperty runningProperty()
      Specified by:
      runningProperty in interface javafx.concurrent.Worker<T>
      Returns:
      the running property
      See Also:

    • isRunning

      public boolean isRunning()
      Gets the value of the running property.
      Specified by:
      isRunning in interface javafx.concurrent.Worker<T>
      Property description:
      Returns:
      the value of the running property
      See Also:

    • getMessage

      public String getMessage()
      Gets the value of the message property.
      Specified by:
      getMessage in interface javafx.concurrent.Worker<T>
      Property description:
      Returns:
      the value of the message property
      See Also:

    • messageProperty

      public javafx.beans.property.ReadOnlyStringProperty messageProperty()
      Specified by:
      messageProperty in interface javafx.concurrent.Worker<T>
      Returns:
      the message property
      See Also:

    • getTitle

      public String getTitle()
      Gets the value of the title property.
      Specified by:
      getTitle in interface javafx.concurrent.Worker<T>
      Property description:
      Returns:
      the value of the title property
      See Also:

    • titleProperty

      public javafx.beans.property.ReadOnlyStringProperty titleProperty()
      Specified by:
      titleProperty in interface javafx.concurrent.Worker<T>
      Returns:
      the title property
      See Also:

    • cancel

      public boolean cancel()
      Specified by:
      cancel in interface javafx.concurrent.Worker<T>