JavaFX 25 · javafx.concurrent.Service · APIdia, the JavaDoc alternative

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 java.util.concurrent.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 java.util.concurrent.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.

Field Summary

Modifier and Type	Field and Description
private EventHelper	eventHelper
private final ObjectProperty<Throwable>	exception
private static final ThreadPoolExecutor	EXECUTOR
private final ObjectProperty<Executor>	executor The executor to use for running this Service.
private static final BlockingQueue<Runnable>	IO_QUEUE Because the ThreadPoolExecutor works completely backwards from what we want (ie: it doesn't increase thread count beyond the core pool size unless the queue is full), our queue has to be smart in that it will REJECT an item in the queue unless the thread size in the EXECUTOR is > 32, in which case we will queue up.
private static final PlatformLogger	LOG Logger used in the case of some uncaught exceptions
private final StringProperty	message
private final DoubleProperty	progress
private final BooleanProperty	running
private volatile boolean	startedOnce This boolean is set to true once the Service has been initially started.
private final ObjectProperty<Worker.State>	state
private Task<V>	task A reference to the last task that was executed.
private static final ThreadFactory	THREAD_FACTORY
private static final ThreadGroup	THREAD_GROUP
private static final int	THREAD_POOL_SIZE
private static final long	THREAD_TIME_OUT
private final StringProperty	title
private final DoubleProperty	totalWorkToBeDone
private static final Thread.UncaughtExceptionHandler	UNCAUGHT_HANDLER
private final ObjectProperty<V>	value
private final DoubleProperty	workDone

Constructor Summary

Access	Constructor and Description
protected	Service() Create a new Service.

Method Summary

Modifier and Type	Method and Description
public final <T extends Event> void	addEventFilter(final EventType<T> eventType, final EventHandler<? super T> eventFilter) Overrides default javafx.event.EventTarget.addEventFilter. Registers an event filter for this target.
public final <T extends Event> void	addEventHandler(final EventType<T> eventType, final EventHandler<? super T> eventHandler) Overrides default javafx.event.EventTarget.addEventHandler. Registers an event handler for this target.
public EventDispatchChain	buildEventDispatchChain(EventDispatchChain tail) Implements javafx.event.EventTarget.buildEventDispatchChain. Construct an event dispatch chain for this target.
public boolean	Returns: returns true if the cancel was successful cancel() Implements javafx.concurrent.Worker.cancel. Cancels any currently running Task, if any.
pack-priv void	cancelFromReadyState() This is used by ScheduledService to cancel a Service that is in the READY state.
protected void	cancelled() A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the CANCELLED state.
pack-priv void	checkThread()
protected abstract Task<V>	Returns: the Task to execute createTask() Invoked after the Service is started on the JavaFX Application Thread.
public final ReadOnlyObjectProperty<Throwable>	exceptionProperty() Implements javafx.concurrent.Worker.exceptionProperty. Gets the ReadOnlyObjectProperty representing any exception which occurred.
protected void	executeTask(final Task<V> a non-null task to execute task) Uses the `executor` defined on this Service to execute the given task.
public final ObjectProperty<Executor>	executorProperty()
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 the event to fire event) Fires the specified event.
private EventHelper	getEventHelper()
public final Throwable	getException() Implements javafx.concurrent.Worker.getException. Indicates the exception which occurred while the Worker was running, if any.
public final Executor	getExecutor()
public final String	getMessage() Implements javafx.concurrent.Worker.getMessage. Gets a message associated with the current state of this Worker.
public final EventHandler<WorkerStateEvent>	Returns: the onCancelled event handler, if any getOnCancelled() The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
public final EventHandler<WorkerStateEvent>	Returns: the onFailed event handler, if any getOnFailed() The onFailed event handler is called whenever the Task state transitions to the FAILED state.
public final EventHandler<WorkerStateEvent>	Returns: the onReady event handler, if any getOnReady() The onReady event handler is called whenever the Task state transitions to the READY state.
public final EventHandler<WorkerStateEvent>	Returns: the onRunning event handler, if any getOnRunning() The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
public final EventHandler<WorkerStateEvent>	Returns: the onScheduled event handler, if any getOnScheduled() The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
public final EventHandler<WorkerStateEvent>	Returns: the onSucceeded event handler, if any getOnSucceeded() The onSucceeded event handler is called whenever the Task state transitions to the SUCCEEDED state.
public final double	getProgress() Implements javafx.concurrent.Worker.getProgress. Indicates the current progress of this Worker in terms of percent complete.
public final Worker.State	getState() Implements javafx.concurrent.Worker.getState. Specifies the current state of this Worker.
public final String	getTitle() Implements javafx.concurrent.Worker.getTitle. An optional title that should be associated with this Worker.
public final double	getTotalWork() Implements javafx.concurrent.Worker.getTotalWork. Indicates a maximum value for the `workDoneProperty` property.
public final V	getValue() Implements javafx.concurrent.Worker.getValue. Specifies the value, or result, of this Worker.
public final double	getWorkDone() Implements javafx.concurrent.Worker.getWorkDone. Indicates the current amount of work that has been completed.
pack-priv boolean	isFxApplicationThread()
public final boolean	isRunning() Implements javafx.concurrent.Worker.isRunning. True if the state is either SCHEDULED or RUNNING.
public final ReadOnlyStringProperty	messageProperty() Implements javafx.concurrent.Worker.messageProperty. Gets the ReadOnlyStringProperty representing the message.
public final ObjectProperty<EventHandler<WorkerStateEvent>>	Returns: the onCancelled event handler property onCancelledProperty() The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
public final ObjectProperty<EventHandler<WorkerStateEvent>>	Returns: the onFailed event handler property onFailedProperty() The onFailed event handler is called whenever the Task state transitions to the FAILED state.
public final ObjectProperty<EventHandler<WorkerStateEvent>>	Returns: the onReady event handler property onReadyProperty() The onReady event handler is called whenever the Task state transitions to the READY state.
public final ObjectProperty<EventHandler<WorkerStateEvent>>	Returns: the onRunning event handler property onRunningProperty() The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
public final ObjectProperty<EventHandler<WorkerStateEvent>>	Returns: the onScheduled event handler property onScheduledProperty() The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
public final ObjectProperty<EventHandler<WorkerStateEvent>>	Returns: the onSucceeded event handler property onSucceededProperty() The onSucceeded event handler is called whenever the Task state transitions to the SUCCEEDED state.
public final ReadOnlyDoubleProperty	progressProperty() Implements javafx.concurrent.Worker.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.
public final <T extends Event> void	removeEventFilter(final EventType<T> eventType, final EventHandler<? super T> eventFilter) Overrides default javafx.event.EventTarget.removeEventFilter. Unregisters a previously registered event filter from this target.
public final <T extends Event> void	removeEventHandler(final EventType<T> eventType, final EventHandler<? super T> eventHandler) Overrides default javafx.event.EventTarget.removeEventHandler. Unregisters a previously registered event handler from this target.
public void	reset() Resets the Service.
public void	restart() Cancels any currently running Task, if any, and restarts this Service.
pack-priv void	runLater(Runnable r)
protected void	running() A protected convenience method for subclasses, called whenever the state of the Service has transitioned to the RUNNING state.
public final ReadOnlyBooleanProperty	runningProperty() Implements javafx.concurrent.Worker.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 < the specific event class of the handler T extends Event> void	setEventHandler(final EventType<T> the event type to associate with the given eventHandler eventType, final EventHandler<? super T> the handler to register, or null to unregister eventHandler) Sets the handler to use for this event type.
public final void	setExecutor(Executor value)
public final void	setOnCancelled(EventHandler<WorkerStateEvent> the event handler, can be null to clear it value) The onCancelled event handler is called whenever the Task state transitions to the CANCELLED state.
public final void	setOnFailed(EventHandler<WorkerStateEvent> the event handler, can be null to clear it value) The onFailed event handler is called whenever the Task state transitions to the FAILED state.
public final void	setOnReady(EventHandler<WorkerStateEvent> the event handler, can be null to clear it value) The onReady event handler is called whenever the Task state transitions to the READY state.
public final void	setOnRunning(EventHandler<WorkerStateEvent> the event handler, can be null to clear it value) The onRunning event handler is called whenever the Task state transitions to the RUNNING state.
public final void	setOnScheduled(EventHandler<WorkerStateEvent> the event handler, can be null to clear it value) The onSchedule event handler is called whenever the Task state transitions to the SCHEDULED state.
public final void	setOnSucceeded(EventHandler<WorkerStateEvent> the event handler, can be null to clear it value) The onSucceeded event handler is called whenever the Task state transitions to the SUCCEEDED state.
public void	start() Starts this Service.
public final ReadOnlyObjectProperty<Worker.State>	stateProperty() Implements javafx.concurrent.Worker.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.
public final ReadOnlyStringProperty	titleProperty() Implements javafx.concurrent.Worker.titleProperty. Gets the ReadOnlyStringProperty representing the title.
public final ReadOnlyDoubleProperty	totalWorkProperty() Implements javafx.concurrent.Worker.totalWorkProperty. Gets the ReadOnlyDoubleProperty representing the maximum amount of work that needs to be done.
public final ReadOnlyObjectProperty<V>	valueProperty() Implements javafx.concurrent.Worker.valueProperty. Gets the ReadOnlyObjectProperty representing the value.
public final ReadOnlyDoubleProperty	workDoneProperty() Implements javafx.concurrent.Worker.workDoneProperty. Gets the ReadOnlyDoubleProperty representing the current progress.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

eventHelper	back to summary
private EventHelper eventHelper

exception	back to summary
private final ObjectProperty<Throwable> exception

EXECUTOR	back to summary
private static final ThreadPoolExecutor EXECUTOR

executor	back to summary
private final ObjectProperty<Executor> executor 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.

IO_QUEUE	back to summary
private static final BlockingQueue<Runnable> IO_QUEUE Because the ThreadPoolExecutor works completely backwards from what we want (ie: it doesn't increase thread count beyond the core pool size unless the queue is full), our queue has to be smart in that it will REJECT an item in the queue unless the thread size in the EXECUTOR is > 32, in which case we will queue up.

LOG	back to summary
private static final PlatformLogger LOG Logger used in the case of some uncaught exceptions

message	back to summary
private final StringProperty message

progress	back to summary
private final DoubleProperty progress

running	back to summary
private final BooleanProperty running

startedOnce	back to summary
private volatile boolean startedOnce This boolean is set to true once the Service has been initially started. You can initialize the Service from any thread, and you can initially start it from any thread. But any subsequent usage of the service's methods must occur on the FX application thread.

state	back to summary
private final ObjectProperty<Worker.State> state

task	back to summary
private Task<V> task A reference to the last task that was executed. I need this reference so that in the restart method I can cancel the currently running task, and so the cancel method can cancel the currently running task.

THREAD_FACTORY	back to summary
private static final ThreadFactory THREAD_FACTORY

THREAD_GROUP	back to summary
private static final ThreadGroup THREAD_GROUP

THREAD_POOL_SIZE	back to summary
private static final int THREAD_POOL_SIZE

THREAD_TIME_OUT	back to summary
private static final long THREAD_TIME_OUT

title	back to summary
private final StringProperty title

totalWorkToBeDone	back to summary
private final DoubleProperty totalWorkToBeDone

UNCAUGHT_HANDLER	back to summary
private static final Thread.UncaughtExceptionHandler UNCAUGHT_HANDLER

value	back to summary
private final ObjectProperty<V> value

workDone	back to summary
private final DoubleProperty workDone

Constructor Detail

Service	back to summary
protected Service() Create a new Service.

Method Detail

addEventFilter back to summary

addEventFilter	back to summary
public final <T extends Event> void addEventFilter(final EventType<T> eventType, final EventHandler<? super T> eventFilter) Overrides default javafx.event.EventTarget.addEventFilter. Doc from javafx.event.EventTarget.addEventFilter. 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. Annotations @Override Since JavaFX 2.1

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

Overrides default javafx.event.EventTarget.addEventFilter.

Doc from javafx.event.EventTarget.addEventFilter.

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.

Annotations

@Override

Since

JavaFX 2.1

addEventHandler back to summary

addEventHandler	back to summary
public final <T extends Event> void addEventHandler(final EventType<T> eventType, final EventHandler<? super T> eventHandler) Overrides default javafx.event.EventTarget.addEventHandler. Doc from javafx.event.EventTarget.addEventHandler. 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. Annotations @Override Since JavaFX 2.1

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

Overrides default javafx.event.EventTarget.addEventHandler.

Doc from javafx.event.EventTarget.addEventHandler.

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.

Annotations

@Override

Since

JavaFX 2.1

buildEventDispatchChain back to summary

buildEventDispatchChain	back to summary
public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail) Implements javafx.event.EventTarget.buildEventDispatchChain. Doc from javafx.event.EventTarget.buildEventDispatchChain. 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. Annotations @Override

public EventDispatchChain buildEventDispatchChain(EventDispatchChain tail)

Implements javafx.event.EventTarget.buildEventDispatchChain.

Doc from javafx.event.EventTarget.buildEventDispatchChain.

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.

Annotations

@Override

cancel	back to summary
public boolean cancel() Implements javafx.concurrent.Worker.cancel. Cancels any currently running Task, if any. The state will be set to CANCELLED. Returns:boolean returns true if the cancel was successful Annotations @Override

cancel

public abstract Class Service<V>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail