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, to write a Service that reads the first line from any URL and returns it as a String, it might be defined with a single property, url, and 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 ThreadPoolExecutor 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

Type	Property	Description
`final ReadOnlyObjectProperty<Throwable>`	`exception`	Gets the ReadOnlyObjectProperty representing any exception which occurred.
`final ObjectProperty<Executor>`	`executor`	The executor to use for running this Service.
`final ReadOnlyStringProperty`	`message`	Gets the ReadOnlyStringProperty representing the message.
`final ObjectProperty<EventHandler<WorkerStateEvent>>`	`onCancelled`	The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
`final ObjectProperty<EventHandler<WorkerStateEvent>>`	`onFailed`	The onFailed event handler is called whenever the Task state transitions to the FAILED state.
`final ObjectProperty<EventHandler<WorkerStateEvent>>`	`onReady`	The onReady event handler is called whenever the Task state transitions to the READY state.
`final ObjectProperty<EventHandler<WorkerStateEvent>>`	`onRunning`	The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
`final ObjectProperty<EventHandler<WorkerStateEvent>>`	`onScheduled`	The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
`final ObjectProperty<EventHandler<WorkerStateEvent>>`	`onSucceeded`	The onSucceeded event handler is called whenever the Task state transitions to the SUCCEEDED state.
`final ReadOnlyDoubleProperty`	`progress`	Gets the ReadOnlyDoubleProperty representing the progress.
`final ReadOnlyBooleanProperty`	`running`	Gets the ReadOnlyBooleanProperty representing whether the Worker is running.
`final ReadOnlyObjectProperty<Worker.State>`	`state`	Gets the ReadOnlyObjectProperty representing the current state.
`final ReadOnlyStringProperty`	`title`	Gets the ReadOnlyStringProperty representing the title.
`final ReadOnlyDoubleProperty`	`totalWork`	Gets the ReadOnlyDoubleProperty representing the maximum amount of work that needs to be done.
`final ReadOnlyObjectProperty<V>`	`value`	Gets the ReadOnlyObjectProperty representing the value.
`final ReadOnlyDoubleProperty`	`workDone`	Gets the ReadOnlyDoubleProperty representing the current progress.

Nested Class Summary

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

Worker.State

Constructor Summary

Service()

Modifier	Constructor	Description
`protected`	Create a new Service.

Method Summary

Modifier and Type	Method	Description
`final <T extends Event> void`	`addEventFilter(EventType<T> eventType, EventHandler<? super T> eventFilter)`	Registers an event filter for this target.
`final <T extends Event> void`	`addEventHandler(EventType<T> eventType, EventHandler<? super T> eventHandler)`	Registers an event handler for this target.
`EventDispatchChain`	`buildEventDispatchChain(EventDispatchChain tail)`	Construct an event dispatch chain for this target.
`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.
`final ReadOnlyObjectProperty<Throwable>`	`exceptionProperty()`	Gets the ReadOnlyObjectProperty representing any exception which occurred.
`protected void`	`executeTask(Task<V> task)`	Uses the `executor` defined on this Service to execute the given task.
`final 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 final void`	`fireEvent(Event event)`	Fires the specified event.
`final Throwable`	`getException()`	Gets the value of the `exception` property.
`final Executor`	`getExecutor()`	Gets the value of the `executor` property.
`final String`	`getMessage()`	Gets the value of the `message` property.
`final EventHandler<WorkerStateEvent>`	`getOnCancelled()`	The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
`final EventHandler<WorkerStateEvent>`	`getOnFailed()`	The onFailed event handler is called whenever the Task state transitions to the FAILED state.
`final EventHandler<WorkerStateEvent>`	`getOnReady()`	The onReady event handler is called whenever the Task state transitions to the READY state.
`final EventHandler<WorkerStateEvent>`	`getOnRunning()`	The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
`final EventHandler<WorkerStateEvent>`	`getOnScheduled()`	The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
`final EventHandler<WorkerStateEvent>`	`getOnSucceeded()`	The onSucceeded event handler is called whenever the Task state transitions to the SUCCEEDED state.
`final double`	`getProgress()`	Gets the value of the `progress` property.
`final Worker.State`	`getState()`	Gets the value of the `state` property.
`final String`	`getTitle()`	Gets the value of the `title` property.
`final double`	`getTotalWork()`	Gets the value of the `totalWork` property.
`final V`	`getValue()`	Gets the value of the `value` property.
`final double`	`getWorkDone()`	Gets the value of the `workDone` property.
`final boolean`	`isRunning()`	Gets the value of the `running` property.
`final ReadOnlyStringProperty`	`messageProperty()`	Gets the ReadOnlyStringProperty representing the message.
`final ObjectProperty<EventHandler<WorkerStateEvent>>`	`onCancelledProperty()`	The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
`final ObjectProperty<EventHandler<WorkerStateEvent>>`	`onFailedProperty()`	The onFailed event handler is called whenever the Task state transitions to the FAILED state.
`final ObjectProperty<EventHandler<WorkerStateEvent>>`	`onReadyProperty()`	The onReady event handler is called whenever the Task state transitions to the READY state.
`final ObjectProperty<EventHandler<WorkerStateEvent>>`	`onRunningProperty()`	The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
`final ObjectProperty<EventHandler<WorkerStateEvent>>`	`onScheduledProperty()`	The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
`final ObjectProperty<EventHandler<WorkerStateEvent>>`	`onSucceededProperty()`	The onSucceeded event handler is called whenever the Task state transitions to the SUCCEEDED state.
`final ReadOnlyDoubleProperty`	`progressProperty()`	Gets the ReadOnlyDoubleProperty representing the progress.
`protected void`	`ready()`	A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the READY state.
`final <T extends Event> void`	`removeEventFilter(EventType<T> eventType, EventHandler<? super T> eventFilter)`	Unregisters a previously registered event filter from this target.
`final <T extends Event> void`	`removeEventHandler(EventType<T> eventType, EventHandler<? super T> eventHandler)`	Unregisters a previously registered event handler from this target.
`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.
`final ReadOnlyBooleanProperty`	`runningProperty()`	Gets the ReadOnlyBooleanProperty representing whether the Worker is running.
`protected void`	`scheduled()`	A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the SCHEDULED state.
`protected final <T extends Event> void`	`setEventHandler(EventType<T> eventType, EventHandler<? super T> eventHandler)`	Sets the handler to use for this event type.
`final void`	`setExecutor(Executor value)`	Sets the value of the `executor` property.
`final void`	`setOnCancelled(EventHandler<WorkerStateEvent> value)`	The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
`final void`	`setOnFailed(EventHandler<WorkerStateEvent> value)`	The onFailed event handler is called whenever the Task state transitions to the FAILED state.
`final void`	`setOnReady(EventHandler<WorkerStateEvent> value)`	The onReady event handler is called whenever the Task state transitions to the READY state.
`final void`	`setOnRunning(EventHandler<WorkerStateEvent> value)`	The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
`final void`	`setOnScheduled(EventHandler<WorkerStateEvent> value)`	The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
`final 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.
`final ReadOnlyObjectProperty<Worker.State>`	`stateProperty()`	Gets the ReadOnlyObjectProperty representing the current state.
`protected void`	`succeeded()`	A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the SUCCEEDED state.
`final ReadOnlyStringProperty`	`titleProperty()`	Gets the ReadOnlyStringProperty representing the title.
`final ReadOnlyDoubleProperty`	`totalWorkProperty()`	Gets the ReadOnlyDoubleProperty representing the maximum amount of work that needs to be done.
`final ReadOnlyObjectProperty<V>`	`valueProperty()`	Gets the ReadOnlyObjectProperty representing the value.
`final ReadOnlyDoubleProperty`	`workDoneProperty()`	Gets the ReadOnlyDoubleProperty representing the current progress.

Methods declared in class java.lang.Object

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

Property Details

state

public final ReadOnlyObjectProperty<Worker.State> stateProperty

Specified by:

stateProperty in interface Worker<V>

Returns:

The property representing the state

See Also:

getState()
stateProperty()

value

public final ReadOnlyObjectProperty<V> valueProperty

Specified by:

valueProperty in interface Worker<V>

Returns:

The property representing the current value

See Also:

getValue()
valueProperty()

exception

public final ReadOnlyObjectProperty<Throwable> exceptionProperty

Specified by:

exceptionProperty in interface Worker<V>

Returns:

the property representing the exception

See Also:

getException()
exceptionProperty()

workDone

public final ReadOnlyDoubleProperty workDoneProperty

Specified by:

workDoneProperty in interface Worker<V>

Returns:

The property representing the amount of work done

See Also:

getWorkDone()
workDoneProperty()

totalWork

public final ReadOnlyDoubleProperty totalWorkProperty

Specified by:

totalWorkProperty in interface Worker<V>

Returns:

the property representing the total work to be done

See Also:

getTotalWork()
totalWorkProperty()

progress

public final ReadOnlyDoubleProperty progressProperty

Specified by:

progressProperty in interface Worker<V>

Returns:

the property representing the progress

See Also:

getProgress()
progressProperty()

running

public final ReadOnlyBooleanProperty runningProperty

Specified by:

runningProperty in interface Worker<V>

Returns:

the property representing whether the worker is running

See Also:

isRunning()
runningProperty()

message

public final ReadOnlyStringProperty messageProperty

Specified by:

messageProperty in interface Worker<V>

Returns:

a property representing the current message

See Also:

getMessage()
messageProperty()

title

public final ReadOnlyStringProperty titleProperty

Specified by:

titleProperty in interface Worker<V>

Returns:

the property representing the current title

See Also:

getTitle()
titleProperty()

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)
executorProperty()

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)
onReadyProperty()

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)
onScheduledProperty()

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)
onRunningProperty()

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)
onSucceededProperty()

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)
onCancelledProperty()

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)
onFailedProperty()

Constructor Details

Service

protected Service()

Create a new Service.

Method Details

getState

public final Worker.State getState()

Gets the value of the state property.

Specified by:

getState in interface Worker<V>

Property description:

Returns:

the value of the state property

See Also:

stateProperty()

stateProperty

public final ReadOnlyObjectProperty<Worker.State> stateProperty()

Description copied from interface: Worker

Gets the ReadOnlyObjectProperty representing the current state.

Specified by:

stateProperty in interface Worker<V>

Returns:

the state property

See Also:

getState()

getValue

public final V getValue()

Gets the value of the value property.

Specified by:

getValue in interface Worker<V>

Property description:

Returns:

the value of the value property

See Also:

valueProperty()

valueProperty

public final ReadOnlyObjectProperty<V> valueProperty()

Description copied from interface: Worker

Gets the ReadOnlyObjectProperty representing the value.

Specified by:

valueProperty in interface Worker<V>

Returns:

the value property

See Also:

getValue()

getException

public final Throwable getException()

Gets the value of the exception property.

Specified by:

getException in interface Worker<V>

Property description:

Returns:

the value of the exception property

See Also:

exceptionProperty()

exceptionProperty

public final ReadOnlyObjectProperty<Throwable> exceptionProperty()

Description copied from interface: Worker

Gets the ReadOnlyObjectProperty representing any exception which occurred.

Specified by:

exceptionProperty in interface Worker<V>

Returns:

the exception property

See Also:

getException()

getWorkDone

public final double getWorkDone()

Gets the value of the workDone property.

Specified by:

getWorkDone in interface Worker<V>

Property description:

Returns:

the value of the workDone property

See Also:

workDoneProperty()

workDoneProperty

public final ReadOnlyDoubleProperty workDoneProperty()

Description copied from interface: Worker

Gets the ReadOnlyDoubleProperty representing the current progress.

Specified by:

workDoneProperty in interface Worker<V>

Returns:

the workDone property

See Also:

getWorkDone()

getTotalWork

public final double getTotalWork()

Gets the value of the totalWork property.

Specified by:

getTotalWork in interface Worker<V>

Property description:

Returns:

the value of the totalWork property

See Also:

totalWorkProperty()

totalWorkProperty

public final ReadOnlyDoubleProperty totalWorkProperty()

Description copied from interface: Worker

Gets the ReadOnlyDoubleProperty representing the maximum amount of work that needs to be done. These "work units" have meaning to the Worker implementation, such as the number of bytes that need to be downloaded or the number of images to process or some other such metric.

Specified by:

totalWorkProperty in interface Worker<V>

Returns:

the totalWork property

See Also:

getTotalWork()

getProgress

public final double getProgress()

Gets the value of the progress property.

Specified by:

getProgress in interface Worker<V>

Property description:

Returns:

the value of the progress property

See Also:

progressProperty()

progressProperty

public final ReadOnlyDoubleProperty progressProperty()

Description copied from interface: Worker

Gets the ReadOnlyDoubleProperty representing the progress.

Specified by:

progressProperty in interface Worker<V>

Returns:

the progress property

See Also:

getProgress()

isRunning

public final boolean isRunning()

Gets the value of the running property.

Specified by:

isRunning in interface Worker<V>

Property description:

Returns:

the value of the running property

See Also:

runningProperty()

runningProperty

public final ReadOnlyBooleanProperty runningProperty()

Description copied from interface: Worker

Gets the ReadOnlyBooleanProperty representing whether the Worker is running.

Specified by:

runningProperty in interface Worker<V>

Returns:

the running property

See Also:

isRunning()

getMessage

public final String getMessage()

Gets the value of the message property.

Specified by:

getMessage in interface Worker<V>

Property description:

Returns:

the value of the message property

See Also:

messageProperty()

messageProperty

public final ReadOnlyStringProperty messageProperty()

Description copied from interface: Worker

Gets the ReadOnlyStringProperty representing the message.

Specified by:

messageProperty in interface Worker<V>

Returns:

the message property

See Also:

getMessage()

getTitle

public final String getTitle()

Gets the value of the title property.

Specified by:

getTitle in interface Worker<V>

Property description:

Returns:

the value of the title property

See Also:

titleProperty()

titleProperty

public final ReadOnlyStringProperty titleProperty()

Description copied from interface: Worker

Gets the ReadOnlyStringProperty representing the title.

Specified by:

titleProperty in interface Worker<V>

Returns:

the title property

See Also:

getTitle()

setExecutor

public final void setExecutor(Executor value)

Sets the value of the executor property.

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.

Parameters:

value - the value for the executor property

See Also:

getExecutor()
executorProperty()

getExecutor

public final Executor getExecutor()

Gets the value of the executor property.

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.

Returns:

the value of the executor property

See Also:

setExecutor(Executor)
executorProperty()

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.

Returns:

the executor property

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.

Returns:

the onReady event handler property

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.

Returns:

the onScheduled event handler property

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.

Returns:

the onRunning event handler property

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.

Returns:

the onSucceeded event handler property

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.

Returns:

the onCancelled event handler property

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.

Returns:

the onFailed event handler property

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 for this target.

The handler is called when the target receives an Event of the specified type during the bubbling phase of event delivery.

Specified by:: addEventHandler in interface EventTarget
Type Parameters:: T - the event class of the handler
Parameters:: eventType - the type of the events received by the handler; eventHandler - the event handler
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 target.

Since it is possible to register a single EventHandler instance for different event types, the caller needs to specify the event type from which the handler should be unregistered.

Specified by:: removeEventHandler in interface EventTarget
Type Parameters:: T - the event class of the handler
Parameters:: eventType - the event type from which to unregister; eventHandler - the event handler
Since:: JavaFX 2.1

addEventFilter

public final <T extends Event> void addEventFilter(EventType<T> eventType, EventHandler<? super T> eventFilter)

Registers an event filter for this target.

The filter is called when the target receives an Event of the specified type during the capturing phase of event delivery.

Specified by:: addEventFilter in interface EventTarget
Type Parameters:: T - the event class of the filter
Parameters:: eventType - the type of the events received by the filter; eventFilter - the event filter
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 target.

Since it is possible to register a single EventHandler instance for different event types, the caller needs to specify the event type from which the filter should be unregistered.

Specified by:: removeEventFilter in interface EventTarget
Type Parameters:: T - the event class of the filter
Parameters:: eventType - the event type from which to unregister; eventFilter - the event filter
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

buildEventDispatchChain

public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail)

Description copied from interface: EventTarget

Construct an event dispatch chain for this target. The event dispatch chain contains event dispatchers which might be interested in processing of events targeted at this EventTarget. This event target is not automatically added to the chain, so if it wants to process events, it needs to add an EventDispatcher for itself to the chain.

In the case the event target is part of some hierarchy, the chain for it is usually built from event dispatchers collected from the root of the hierarchy to the event target.

The event dispatch chain is constructed by modifications to the provided initial event dispatch chain. The returned chain should have the initial chain at its end so the dispatchers should be prepended to the initial chain.

The caller shouldn't assume that the initial chain remains unchanged nor that the returned value will reference a different chain.

Specified by:: buildEventDispatchChain in interface EventTarget
Parameters:: tail - the initial chain to build from
Returns:: the resulting event dispatch chain for this target

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

© 2008, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from JavaFX API Documentation.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Java, JavaFX and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.