javax.enterprise.concurrent.ManagedScheduledExecutorService Maven / Gradle / Ivy
Show all versions of javax.enterprise.concurrent-api Show documentation
/**
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2010-2011 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.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 Java™ EE environment.
* Implementations of the ManagedScheduledExecutorService are
* provided by a Java™ 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 Concurrency Utilities for Java™ EE 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 Java™ 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 javax.transaction.UserTransaction} instance. A UserTransaction instance is
* available in JNDI using the name: "java:comp/UserTransaction" or by
* requesting an injection of a {@link javax.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.)
*
*
* 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.
*
* @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);
}