Module javafx.graphics
Package javafx.concurrent

# Class Service<V>

java.lang.Object
javafx.concurrent.Service<V>

Type Parameters:
  `V` - the type of object returned by the Service

All Implemented Interfaces:
  `Worker<V>`, `EventTarget`

Direct Known Subclasses:
  `ScheduledService`

    public abstract class Service<V>
    extends Object
    implements Worker<V>, EventTarget

A Service is a non-visual component encapsulating the information required to perform some work on one or more background threads. As part of the JavaFX UI library, the Service knows about the JavaFX Application thread and is designed to relieve the application developer from the burden of managing multithreaded code that interacts with the user interface. As such, all of the methods and state on the Service are intended to be invoked exclusively from the JavaFX Application thread. The only exception to this, is when initially configuring a Service, which may safely be done from any thread, and initially starting a Service, which may also safely be done from any thread. However, once the Service has been initialized and started, it may only thereafter be used from the FX thread.

A Service creates and manages a `Task` that performs the work on the background thread. Service implements `Worker`. As such, you can observe the state of the background task and optionally cancel it. Service is a reusable Worker, meaning that it can be reset and restarted. Due to this, a Service can be constructed declaratively and restarted on demand. Once a Service is started, it will schedule its Task and listen for changes to the state of the Task. A Task does not hold a reference to the Service that started it, meaning that a running Task will not prevent the Service from being garbage collected.

If an `Executor` is specified on the Service, then it will be used to actually execute the service. Otherwise, a daemon thread will be created and executed. If you wish to create non-daemon threads, then specify a custom Executor (for example, you could use a `ThreadPoolExecutor` with a custom `ThreadFactory`).

Because a Service is intended to simplify declarative use cases, subclasses should expose as properties the input parameters to the work to be done. For example, suppose I wanted to write a Service which read the first line from any URL and returned it as a String. Such a Service might be defined, such that it had a single property, `url`. It might be implemented as:

         public static class FirstLineService extends Service<String> {
             private StringProperty url = new SimpleStringProperty(this, "url");
             public final void setUrl(String value) { url.set(value); }
             public final String getUrl() { return url.get(); }
             public final StringProperty urlProperty() { return url; }

             protected Task createTask() {
                 final String _url = getUrl();
                 return new Task<String>() {
                     protected String call() throws Exception {
                         URL u = new URL(_url);
                         BufferedReader in = new BufferedReader(
                                 new InputStreamReader(u.openStream()));
                         String result = in.readLine();
                         in.close();
                         return result;
                     }
                 };
             }
         }

The Service by default uses a thread pool Executor with some unspecified default or maximum thread pool size. This is done so that naive code will not completely swamp the system by creating thousands of Threads.

Since:
  JavaFX 2.0

- ## Property Summary

  Properties
  Type | Property | Description
  --- | --- | ---
  `ObjectProperty<Executor>` | `executor` | The executor to use for running this Service.
  `ObjectProperty<EventHandler<WorkerStateEvent>>` | `onCancelled` | The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
  `ObjectProperty<EventHandler<WorkerStateEvent>>` | `onFailed` | The onFailed event handler is called whenever the Task state transitions to the FAILED state.
  `ObjectProperty<EventHandler<WorkerStateEvent>>` | `onReady` | The onReady event handler is called whenever the Task state transitions to the READY state.
  `ObjectProperty<EventHandler<WorkerStateEvent>>` | `onRunning` | The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
  `ObjectProperty<EventHandler<WorkerStateEvent>>` | `onScheduled` | The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
  `ObjectProperty<EventHandler<WorkerStateEvent>>` | `onSucceeded` | The onSucceeded event handler is called whenever the Task state transitions to the SUCCEEDED state.

  ### Properties declared in interface javafx.concurrent.Worker

  `exception, message, progress, running, state, title, totalWork, value, workDone`

- ## Nested Class Summary

  ## Nested classes/interfaces declared in interface javafx.concurrent.Worker

  `Worker.State`

- ## Constructor Summary

  Constructors
  Modifier | Constructor | Description
  --- | --- | ---
  `protected` | `Service()` | Create a new Service.

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `<T extends Event> void` | `addEventFilter​(EventType<T> eventType, EventHandler<? super T> eventFilter)` | Registers an event filter to this task.
  `<T extends Event> void` | `addEventHandler​(EventType<T> eventType, EventHandler<? super T> eventHandler)` | Registers an event handler to this task.
  `boolean` | `cancel()` | Cancels any currently running Task, if any.
  `protected void` | `cancelled()` | A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the CANCELLED state.
  `protected abstract Task<V>` | `createTask()` | Invoked after the Service is started on the JavaFX Application Thread.
  `protected void` | `executeTask​(Task<V> task)` | Uses the `executor` defined on this Service to execute the given task.
  `ObjectProperty<Executor>` | `executorProperty()` | The executor to use for running this Service.
  `protected void` | `failed()` | A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the FAILED state.
  `protected void` | `fireEvent​(Event event)` | Fires the specified event.
  `Executor` | `getExecutor()` | Gets the value of the property executor.
  `EventHandler<WorkerStateEvent>` | `getOnCancelled()` | The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
  `EventHandler<WorkerStateEvent>` | `getOnFailed()` | The onFailed event handler is called whenever the Task state transitions to the FAILED state.
  `EventHandler<WorkerStateEvent>` | `getOnReady()` | The onReady event handler is called whenever the Task state transitions to the READY state.
  `EventHandler<WorkerStateEvent>` | `getOnRunning()` | The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
  `EventHandler<WorkerStateEvent>` | `getOnScheduled()` | The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
  `EventHandler<WorkerStateEvent>` | `getOnSucceeded()` | The onSucceeded event handler is called whenever the Task state transitions to the SUCCEEDED state.
  `ObjectProperty<EventHandler<WorkerStateEvent>>` | `onCancelledProperty()` | The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
  `ObjectProperty<EventHandler<WorkerStateEvent>>` | `onFailedProperty()` | The onFailed event handler is called whenever the Task state transitions to the FAILED state.
  `ObjectProperty<EventHandler<WorkerStateEvent>>` | `onReadyProperty()` | The onReady event handler is called whenever the Task state transitions to the READY state.
  `ObjectProperty<EventHandler<WorkerStateEvent>>` | `onRunningProperty()` | The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
  `ObjectProperty<EventHandler<WorkerStateEvent>>` | `onScheduledProperty()` | The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
  `ObjectProperty<EventHandler<WorkerStateEvent>>` | `onSucceededProperty()` | The onSucceeded event handler is called whenever the Task state transitions to the SUCCEEDED state.
  `protected void` | `ready()` | A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the READY state.
  `<T extends Event> void` | `removeEventFilter​(EventType<T> eventType, EventHandler<? super T> eventFilter)` | Unregisters a previously registered event filter from this task.
  `<T extends Event> void` | `removeEventHandler​(EventType<T> eventType, EventHandler<? super T> eventHandler)` | Unregisters a previously registered event handler from this task.
  `void` | `reset()` | Resets the Service.
  `void` | `restart()` | Cancels any currently running Task, if any, and restarts this Service.
  `protected void` | `running()` | A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the RUNNING state.
  `protected void` | `scheduled()` | A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the SCHEDULED state.
  `protected <T extends Event> void` | `setEventHandler​(EventType<T> eventType, EventHandler<? super T> eventHandler)` | Sets the handler to use for this event type.
  `void` | `setExecutor​(Executor value)` | Sets the value of the property executor.
  `void` | `setOnCancelled​(EventHandler<WorkerStateEvent> value)` | The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
  `void` | `setOnFailed​(EventHandler<WorkerStateEvent> value)` | The onFailed event handler is called whenever the Task state transitions to the FAILED state.
  `void` | `setOnReady​(EventHandler<WorkerStateEvent> value)` | The onReady event handler is called whenever the Task state transitions to the READY state.
  `void` | `setOnRunning​(EventHandler<WorkerStateEvent> value)` | The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
  `void` | `setOnScheduled​(EventHandler<WorkerStateEvent> value)` | The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
  `void` | `setOnSucceeded​(EventHandler<WorkerStateEvent> value)` | The onSucceeded event handler is called whenever the Task state transitions to the SUCCEEDED state.
  `void` | `start()` | Starts this Service.
  `protected void` | `succeeded()` | A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the SUCCEEDED state.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods declared in interface javafx.event.EventTarget

  `buildEventDispatchChain`

  ### Methods declared in interface javafx.concurrent.Worker

  `exceptionProperty, getException, getMessage, getProgress, getState, getTitle, getTotalWork, getValue, getWorkDone, isRunning, messageProperty, progressProperty, runningProperty, stateProperty, titleProperty, totalWorkProperty, valueProperty, workDoneProperty`

- ## Property Details

  - ### executor

    public final ObjectProperty<Executor> executorProperty
    The executor to use for running this Service. If no executor is specified, then a new daemon thread will be created and used for running the Service using some default executor.
    See Also:
      `getExecutor()`, `setExecutor(Executor)`

  - ### onReady

    public final ObjectProperty<EventHandler<WorkerStateEvent>> onReadyProperty
    The onReady event handler is called whenever the Task state transitions to the READY state.
    Since:
      JavaFX 2.1
    See Also:
      `getOnReady()`, `setOnReady(EventHandler)`

  - ### onScheduled

    public final ObjectProperty<EventHandler<WorkerStateEvent>> onScheduledProperty
    The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
    Since:
      JavaFX 2.1
    See Also:
      `getOnScheduled()`, `setOnScheduled(EventHandler)`

  - ### onRunning

    public final ObjectProperty<EventHandler<WorkerStateEvent>> onRunningProperty
    The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
    Since:
      JavaFX 2.1
    See Also:
      `getOnRunning()`, `setOnRunning(EventHandler)`

  - ### onSucceeded

    public final ObjectProperty<EventHandler<WorkerStateEvent>> onSucceededProperty
    The onSucceeded event handler is called whenever the Task state transitions to the SUCCEEDED state.
    Since:
      JavaFX 2.1
    See Also:
      `getOnSucceeded()`, `setOnSucceeded(EventHandler)`

  - ### onCancelled

    public final ObjectProperty<EventHandler<WorkerStateEvent>> onCancelledProperty
    The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
    Since:
      JavaFX 2.1
    See Also:
      `getOnCancelled()`, `setOnCancelled(EventHandler)`

  - ### onFailed

    public final ObjectProperty<EventHandler<WorkerStateEvent>> onFailedProperty
    The onFailed event handler is called whenever the Task state transitions to the FAILED state.
    Since:
      JavaFX 2.1
    See Also:
      `getOnFailed()`, `setOnFailed(EventHandler)`

- ## Constructor Details

  - ### Service

    protected Service()
    Create a new Service.

- ## Method Details

  - ### setExecutor

    public final void setExecutor​(Executor value)
    Sets the value of the property executor.
    Property description:
      The executor to use for running this Service. If no executor is specified, then a new daemon thread will be created and used for running the Service using some default executor.

  - ### getExecutor

    public final Executor getExecutor()
    Gets the value of the property executor.
    Property description:
      The executor to use for running this Service. If no executor is specified, then a new daemon thread will be created and used for running the Service using some default executor.

  - ### executorProperty

    public final ObjectProperty<Executor> executorProperty()
    The executor to use for running this Service. If no executor is specified, then a new daemon thread will be created and used for running the Service using some default executor.
    See Also:
      `getExecutor()`, `setExecutor(Executor)`

  - ### onReadyProperty

    public final ObjectProperty<EventHandler<WorkerStateEvent>> onReadyProperty()
    The onReady event handler is called whenever the Task state transitions to the READY state.
    Since:
      JavaFX 2.1
    See Also:
      `getOnReady()`, `setOnReady(EventHandler)`

  - ### getOnReady

    public final EventHandler<WorkerStateEvent> getOnReady()
    The onReady event handler is called whenever the Task state transitions to the READY state.
    Returns:
      the onReady event handler, if any
    Since:
      JavaFX 2.1

  - ### setOnReady

    public final void setOnReady​(EventHandler<WorkerStateEvent> value)
    The onReady event handler is called whenever the Task state transitions to the READY state.
    Parameters:
      `value` - the event handler, can be null to clear it
    Since:
      JavaFX 2.1

  - ### ready

    protected void ready()
    A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the READY state. This method is invoked after the Service has been fully transitioned to the new state.
    Since:
      JavaFX 2.1

  - ### onScheduledProperty

    public final ObjectProperty<EventHandler<WorkerStateEvent>> onScheduledProperty()
    The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
    Since:
      JavaFX 2.1
    See Also:
      `getOnScheduled()`, `setOnScheduled(EventHandler)`

  - ### getOnScheduled

    public final EventHandler<WorkerStateEvent> getOnScheduled()
    The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
    Returns:
      the onScheduled event handler, if any
    Since:
      JavaFX 2.1

  - ### setOnScheduled

    public final void setOnScheduled​(EventHandler<WorkerStateEvent> value)
    The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
    Parameters:
      `value` - the event handler, can be null to clear it
    Since:
      JavaFX 2.1

  - ### scheduled

    protected void scheduled()
    A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the SCHEDULED state. This method is invoked after the Service has been fully transitioned to the new state.
    Since:
      JavaFX 2.1

  - ### onRunningProperty

    public final ObjectProperty<EventHandler<WorkerStateEvent>> onRunningProperty()
    The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
    Since:
      JavaFX 2.1
    See Also:
      `getOnRunning()`, `setOnRunning(EventHandler)`

  - ### getOnRunning

    public final EventHandler<WorkerStateEvent> getOnRunning()
    The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
    Returns:
      the onRunning event handler, if any
    Since:
      JavaFX 2.1

  - ### setOnRunning

    public final void setOnRunning​(EventHandler<WorkerStateEvent> value)
    The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
    Parameters:
      `value` - the event handler, can be null to clear it
    Since:
      JavaFX 2.1

  - ### running

    protected void running()
    A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the RUNNING state. This method is invoked after the Service has been fully transitioned to the new state.
    Since:
      JavaFX 2.1

  - ### onSucceededProperty

    public final ObjectProperty<EventHandler<WorkerStateEvent>> onSucceededProperty()
    The onSucceeded event handler is called whenever the Task state transitions to the SUCCEEDED state.
    Since:
      JavaFX 2.1
    See Also:
      `getOnSucceeded()`, `setOnSucceeded(EventHandler)`

  - ### getOnSucceeded

    public final EventHandler<WorkerStateEvent> getOnSucceeded()
    The onSucceeded event handler is called whenever the Task state transitions to the SUCCEEDED state.
    Returns:
      the onSucceeded event handler, if any
    Since:
      JavaFX 2.1

  - ### setOnSucceeded

    public final void setOnSucceeded​(EventHandler<WorkerStateEvent> value)
    The onSucceeded event handler is called whenever the Task state transitions to the SUCCEEDED state.
    Parameters:
      `value` - the event handler, can be null to clear it
    Since:
      JavaFX 2.1

  - ### succeeded

    protected void succeeded()
    A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the SUCCEEDED state. This method is invoked after the Service has been fully transitioned to the new state.
    Since:
      JavaFX 2.1

  - ### onCancelledProperty

    public final ObjectProperty<EventHandler<WorkerStateEvent>> onCancelledProperty()
    The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
    Since:
      JavaFX 2.1
    See Also:
      `getOnCancelled()`, `setOnCancelled(EventHandler)`

  - ### getOnCancelled

    public final EventHandler<WorkerStateEvent> getOnCancelled()
    The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
    Returns:
      the onCancelled event handler, if any
    Since:
      JavaFX 2.1

  - ### setOnCancelled

    public final void setOnCancelled​(EventHandler<WorkerStateEvent> value)
    The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
    Parameters:
      `value` - the event handler, can be null to clear it
    Since:
      JavaFX 2.1

  - ### cancelled

    protected void cancelled()
    A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the CANCELLED state. This method is invoked after the Service has been fully transitioned to the new state.
    Since:
      JavaFX 2.1

  - ### onFailedProperty

    public final ObjectProperty<EventHandler<WorkerStateEvent>> onFailedProperty()
    The onFailed event handler is called whenever the Task state transitions to the FAILED state.
    Since:
      JavaFX 2.1
    See Also:
      `getOnFailed()`, `setOnFailed(EventHandler)`

  - ### getOnFailed

    public final EventHandler<WorkerStateEvent> getOnFailed()
    The onFailed event handler is called whenever the Task state transitions to the FAILED state.
    Returns:
      the onFailed event handler, if any
    Since:
      JavaFX 2.1

  - ### setOnFailed

    public final void setOnFailed​(EventHandler<WorkerStateEvent> value)
    The onFailed event handler is called whenever the Task state transitions to the FAILED state.
    Parameters:
      `value` - the event handler, can be null to clear it
    Since:
      JavaFX 2.1

  - ### failed

    protected void failed()
    A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the FAILED state. This method is invoked after the Service has been fully transitioned to the new state.
    Since:
      JavaFX 2.1

  - ### cancel

    public boolean cancel()
    Cancels any currently running Task, if any. The state will be set to CANCELLED.
    Specified by:
      `cancel` in interface `Worker<V>`
    Returns:
      returns true if the cancel was successful

  - ### restart

    public void restart()
    Cancels any currently running Task, if any, and restarts this Service. The state will be reset to READY prior to execution. This method should only be called on the FX application thread.

  - ### reset

    public void reset()
    Resets the Service. May only be called while in one of the finish states, that is, SUCCEEDED, FAILED, or CANCELLED, or when READY. This method should only be called on the FX application thread.

  - ### start

    public void start()
    Starts this Service. The Service must be in the READY state to succeed in this call. This method should only be called on the FX application thread.

  - ### executeTask

    protected void executeTask​(Task<V> task)

    Uses the `executor` defined on this Service to execute the given task. If the `executor` is null, then a default executor is used which will create a new daemon thread on which to execute this task.

    This method is intended only to be called by the Service implementation.

    Parameters:
      `task` - a non-null task to execute
    Since:
      JavaFX 2.1

  - ### addEventHandler

    public final <T extends Event> void addEventHandler​(EventType<T> eventType, EventHandler<? super T> eventHandler)
    Registers an event handler to this task. Any event filters are first processed, then the specified onFoo event handlers, and finally any event handlers registered by this method. As with other events in the scene graph, if an event is consumed, it will not continue dispatching.
    Type Parameters:
      `T` - the specific event class of the handler
    Parameters:
      `eventType` - the type of the events to receive by the handler
      `eventHandler` - the handler to register
    Throws:
      `NullPointerException` - if the event type or handler is null
    Since:
      JavaFX 2.1

  - ### removeEventHandler

    public final <T extends Event> void removeEventHandler​(EventType<T> eventType, EventHandler<? super T> eventHandler)
    Unregisters a previously registered event handler from this task. One handler might have been registered for different event types, so the caller needs to specify the particular event type from which to unregister the handler.
    Type Parameters:
      `T` - the specific event class of the handler
    Parameters:
      `eventType` - the event type from which to unregister
      `eventHandler` - the handler to unregister
    Throws:
      `NullPointerException` - if the event type or handler is null
    Since:
      JavaFX 2.1

  - ### addEventFilter

    public final <T extends Event> void addEventFilter​(EventType<T> eventType, EventHandler<? super T> eventFilter)
    Registers an event filter to this task. Registered event filters get an event before any associated event handlers.
    Type Parameters:
      `T` - the specific event class of the filter
    Parameters:
      `eventType` - the type of the events to receive by the filter
      `eventFilter` - the filter to register
    Throws:
      `NullPointerException` - if the event type or filter is null
    Since:
      JavaFX 2.1

  - ### removeEventFilter

    public final <T extends Event> void removeEventFilter​(EventType<T> eventType, EventHandler<? super T> eventFilter)
    Unregisters a previously registered event filter from this task. One filter might have been registered for different event types, so the caller needs to specify the particular event type from which to unregister the filter.
    Type Parameters:
      `T` - the specific event class of the filter
    Parameters:
      `eventType` - the event type from which to unregister
      `eventFilter` - the filter to unregister
    Throws:
      `NullPointerException` - if the event type or filter is null
    Since:
      JavaFX 2.1

  - ### setEventHandler

    protected final <T extends Event> void setEventHandler​(EventType<T> eventType, EventHandler<? super T> eventHandler)
    Sets the handler to use for this event type. There can only be one such handler specified at a time. This handler is guaranteed to be called first. This is used for registering the user-defined onFoo event handlers.
    Type Parameters:
      `T` - the specific event class of the handler
    Parameters:
      `eventType` - the event type to associate with the given eventHandler
      `eventHandler` - the handler to register, or null to unregister
    Throws:
      `NullPointerException` - if the event type is null
    Since:
      JavaFX 2.1

  - ### fireEvent

    protected final void fireEvent​(Event event)
    Fires the specified event. Any event filter encountered will be notified and can consume the event. If not consumed by the filters, the event handlers on this task are notified. If these don't consume the event either, then all event handlers are called and can consume the event.

    This method must be called on the FX user thread.

    Parameters:
      `event` - the event to fire
    Since:
      JavaFX 2.1

  - ### createTask

    protected abstract Task<V> createTask()
    Invoked after the Service is started on the JavaFX Application Thread. Implementations should save off any state into final variables prior to creating the Task, since accessing properties defined on the Service within the background thread code of the Task will result in exceptions. For example:

             protected Task createTask() {
                 final String url = myService.getUrl();
                 return new Task<String>() {
                     protected String call() {
                         URL u = new URL("http://www.oracle.com");
                         BufferedReader in = new BufferedReader(
                                 new InputStreamReader(u.openStream()));
                         String result = in.readLine();
                         in.close();
                         return result;
                     }
                 }
             }

    If the Task is a pre-defined class (as opposed to being an anonymous class), and if it followed the recommended best-practice, then there is no need to save off state prior to constructing the Task since its state is completely provided in its constructor.

             protected Task createTask() {
                 // This is safe because getUrl is called on the FX Application
                 // Thread and the FirstLineReaderTasks stores it as an
                 // immutable property
                 return new FirstLineReaderTask(myService.getUrl());
             }

    Returns:
      the Task to execute