jakarta.enterprise.concurrent.ManagedScheduledExecutorService Maven / Gradle / Ivy
Show all versions of jakarta.enterprise.concurrent-api Show documentation
/*
* Copyright (c) 2010, 2022 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package jakarta.enterprise.concurrent;
import java.util.concurrent.ScheduledExecutorService;
/**
* A manageable version of a {@link java.util.concurrent.ScheduledExecutorService}.
*
* A ManagedScheduledExecutorService extends the Java™ SE ScheduledExecutorService
* to provide methods for submitting delayed or periodic tasks for execution in
* a Jakarta™ EE environment.
* Implementations of the ManagedScheduledExecutorService are
* provided by a Jakarta EE Product Provider. Application Component Providers
* use the Java Naming and Directory Interface™ (JNDI) to look-up instances of one
* or more ManagedScheduledExecutorService objects using resource environment references.
* ManagedScheduledExecutorService instances can also be injected into application
* components through the use of the {@code Resource} annotation.
*
* The Jakarta Concurrency specification describes several
* behaviors that a ManagedScheduledExecutorService can implement. The Application
* Component Provider and Deployer identify these requirements and map the
* resource environment reference appropriately.
*
* Tasks are run in managed threads provided by the Jakarta™ EE Product Provider
* and are run within the application component context that submitted the task.
* All tasks run without an explicit transaction (they do not enlist in the application
* component's transaction). If a transaction is required, use a
* {@code jakarta.transaction.UserTransaction} instance. A UserTransaction instance is
* available in JNDI using the name: "java:comp/UserTransaction" or by
* requesting an injection of a {@code jakarta.transaction.UserTransaction} object
* using the {@code Resource} annotation.
*
* Example:
*
*
* public run() {
* // Begin of task
* InitialContext ctx = new InitialContext();
* UserTransaction ut = (UserTransaction) ctx.lookup("java:comp/UserTransaction");
* ut.begin();
*
* // Perform transactional business logic
*
* ut.commit();
* }
*
* Tasks can optionally provide an {@link ManagedTaskListener} to receive
* notifications of lifecycle events, through the use of {@link ManagedTask}
* interface.
*
*
* Asynchronous tasks are typically submitted to the ManagedScheduledExecutorService using one
* of the submit or schedulemethods, each of which return a Future
* instance. The Future represents the result of the task and can also be used to
* check if the task is complete or wait for its completion.
*
* If the task is cancelled, the result for the task is a
* CancellationException exception. If the task is unable
* to run due to start due to a reason other than cancellation, the result is a
* {@link AbortedException} exception. If the task is scheduled
* with a {@link Trigger} and the Trigger forces the task to be skipped,
* the result will be a {@link SkippedException} exception.
*
* Tasks can be scheduled to run periodically using the schedule methods that
* take a Trigger as an argument and the scheduleAtFixedRate and
* scheduleWithFixedDelay methods. The result of the Future will
* be represented by the currently scheduled or running instance of the task. Future and past executions
* of the task are not represented by the Future. The state of the Future will therefore change
* and multiple results are expected.
*
* For example, if a task is repeating, the lifecycle of the task would be:
* (Note: See {@link ManagedTaskListener} for task lifecycle management details.)
*
*
* Task Lifecycle
* Sequence
* State
* Action
* Listener
* Next state 1A.
* None
* submit()
* taskSubmitted
* Submitted 2A.
* Submitted
* About to call run()
* taskStarting
* Started 3A.
* Started
* Exit run()
* taskDone
* Reschedule 1B.
* Reschedule
* taskSubmitted
* Submitted 2B.
* Submitted
* About to call run()
* taskStarting
* Started 3B.
* Started
* Exit run()
* taskDone
* Reschedule
*
*
* @since 1.0
*/
public interface ManagedScheduledExecutorService extends
ManagedExecutorService, ScheduledExecutorService {
/**
* Creates and executes a task based on a Trigger. The Trigger determines when the task
* should run and how often.
*
* @param command the task to execute.
* @param trigger the trigger that determines when the task should fire.
*
* @return a Future representing pending completion of the task, and whose get()
* method will return null upon completion.
*
* @throws java.util.concurrent.RejectedExecutionException if task cannot be scheduled for execution.
* @throws java.lang.NullPointerException if command is null.
*/
public java.util.concurrent.ScheduledFuture schedule(java.lang.Runnable command,
Trigger trigger);
/**
* Creates and executes a task based on a Trigger. The Trigger determines when the task should
* run and how often.
*
* @param callable the function to execute.
* @param trigger the trigger that determines when the task should fire.
* @param the return type of the Callable
*
* @return a ScheduledFuture that can be used to extract result or cancel.
*
* @throws java.util.concurrent.RejectedExecutionException if task cannot be scheduled for execution.
* @throws java.lang.NullPointerException if callable is null.
*
*/
public java.util.concurrent.ScheduledFuture schedule(java.util.concurrent.Callable callable,
Trigger trigger);
}