jakarta.enterprise.concurrent.ManagedScheduledExecutorDefinition Maven / Gradle / Ivy
/*
* Copyright (c) 2021 Contributors to the Eclipse Foundation
*
* 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 static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
/**
* Defines a {@link ManagedScheduledExecutorService}
* to be registered in JNDI by the container
* under the JNDI name that is specified in the
* {@link #name()} attribute.
*
* Application components can refer to this JNDI name in the
* {@link jakarta.annotation.Resource#lookup() lookup} attribute of a
* {@link jakarta.annotation.Resource} annotation,
*
*
* {@literal @}ManagedScheduledExecutorDefinition(
* name = "java:comp/concurrent/MyScheduledExecutor",
* context = "java:comp/concurrent/MyScheduledExecutorContext",
* hungTaskThreshold = 30000,
* maxAsync = 3)
* {@literal @}ContextServiceDefinition(
* name = "java:comp/concurrent/MyScheduledExecutorContext",
* propagated = APPLICATION)
* public class MyServlet extends HttpServlet {
* {@literal @}Resource(lookup = "java:comp/concurrent/MyScheduledExecutor",
* name = "java:comp/concurrent/env/MyScheduledExecutorRef")
* ManagedScheduledExecutorService myScheduledExecutor;
*
*
* Resource environment references in a deployment descriptor
* can similarly specify the lookup-name,
*
*
* <resource-env-ref>
* <resource-env-ref-name>java:comp/env/concurrent/MyScheduledExecutorRef</resource-env-ref-name>
* <resource-env-ref-type>jakarta.enterprise.concurrent.ManagedScheduledExecutorService</resource-env-ref-type>
* <lookup-name>java:comp/concurrent/MyScheduledExecutor</lookup-name>
* </resource-env-ref>
*
*
* You can also define a {@code ManagedScheduledExecutorService} with the
* {@code } deployment descriptor element.
* For example,
*
*
* <managed-scheduled-executor>
* <name>java:module/concurrent/MyExecutor</name>
* <context-service-ref>java:module/concurrent/MyExecutorContext</context-service-ref>
* <hung-task-threshold>120000</hung-task-threshold>
* <max-async>5</max-async>
* </managed-scheduled-executor>
*
*
* If a {@code managed-scheduled-executor} and {@code ManagedScheduledExecutorDefinition}
* have the same name, their attributes are merged to define a single
* {@code ManagedScheduledExecutorService} definition, with each attribute that is specified
* in the {@code managed-scheduled-executor} deployment descriptor entry taking
* precedence over the corresponding attribute of the annotation.
*
* @since 3.0
*/
@Repeatable(ManagedScheduledExecutorDefinition.List.class)
@Retention(RUNTIME)
@Target(TYPE)
public @interface ManagedScheduledExecutorDefinition {
/**
* JNDI name of the {@link ManagedScheduledExecutorService} instance.
* The JNDI name must be in a valid Jakarta EE namespace,
* such as,
*
* - java:comp
* - java:module
* - java:app
* - java:global
*
*
* @return ManagedScheduledExecutorService JNDI name.
*/
String name();
/**
* The name of a {@link ContextService} instance which
* determines how context is applied to tasks and actions that
* run on this executor.
*
* The name can be the name of a {@link ContextServiceDefinition} or
* the name of a {@code context-service} deployment descriptor element
* or the JNDI name of the Jakarta EE default {@code ContextService}
* instance, {@code java:comp/DefaultContextService}.
*
* The name of the {@code ContextService} must be no more granular
* than the name of this {@code ManagedScheduledExecutorDefinition}. For example,
* if this {@code ManagedScheduledExecutorDefinition} has a name in {@code java:app},
* the {@code ContextService} can be in {@code java:app} or {@code java:global},
* but not in {@code java:module} which would be ambiguous as to which
* module's {@code ContextService} definition should be used.
*
* The default value, {@code java:comp/DefaultContextService}, is the
* JNDI name of the Jakarta EE default {@code ContextService}.
*
* @return name of the {@code ContextService} for
* capturing and propagating or clearing context.
*/
String context() default "java:comp/DefaultContextService";
/**
*
The amount of time in milliseconds that a task or action
* can execute before it is considered hung.
*
* The default value of -1 indicates unlimited.
*
* @return number of milliseconds after which a task or action
* is considered hung.
*/
long hungTaskThreshold() default -1;
/**
* Upper bound on contextual tasks and actions that this executor
* will simultaneously execute asynchronously. This constraint does
* not apply to tasks and actions that the executor runs inline,
* such as when a thread requests
* {@link java.util.concurrent.CompletableFuture#join()} and the
* action runs inline if it has not yet started.
* This constraint also does not apply to tasks that are scheduled
* via the schedule* methods.
*
* The default value of -1 indicates unbounded,
* although still subject to resource constraints of the system.
*
* @return upper limit on asynchronous execution.
*/
int maxAsync() default -1;
/**
* Enables multiple ManagedScheduledExecutorDefinition
* annotations on the same type.
*/
@Retention(RUNTIME)
@Target(TYPE)
public @interface List {
ManagedScheduledExecutorDefinition[] value();
}
}