jakarta.enterprise.concurrent.ManagedThreadFactoryDefinition Maven / Gradle / Ivy
Show all versions of jakarta.enterprise.concurrent-api Show documentation
/*
* Copyright (c) 2021,2024 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;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.inject.spi.Producer;
import jakarta.inject.Qualifier;
/**
* Defines {@link ManagedThreadFactory} instances
* to be injected into
* {@link ManagedThreadFactory} injection points
* including any required {@link Qualifier} annotations specified by {@link #qualifiers()}
* and 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 @}ManagedThreadFactoryDefinition(
* name = "java:global/concurrent/MyThreadFactory",
* qualifiers = MyQualifier.class,
* context = "java:global/concurrent/MyThreadFactoryContext",
* priority = 4)
* {@literal @}ContextServiceDefinition(
* name = "java:global/concurrent/MyThreadFactoryContext",
* propagated = APPLICATION)
* public class MyServlet extends HttpServlet {
* {@literal @}Inject
* {@literal @}MyQualifier
* ManagedThreadFactory myThreadFactory1;
*
* {@literal @}Resource(lookup = "java:global/concurrent/MyThreadFactory",
* name = "java:module/concurrent/env/MyThreadFactoryRef")
* ManagedThreadFactory myThreadFactory2;
* ...
*
* {@literal @}Qualifier
* {@literal @}Retention(RetentionPolicy.RUNTIME)
* {@literal @}Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE })
* public {@literal @}interface MyQualifier {}
*
*
* Resource environment references in a deployment descriptor
* can similarly specify the lookup-name,
*
*
* <resource-env-ref>
* <resource-env-ref-name>java:module/env/concurrent/MyThreadFactoryRef</resource-env-ref-name>
* <resource-env-ref-type>jakarta.enterprise.concurrent.ManagedThreadFactory</resource-env-ref-type>
* <lookup-name>java:global/concurrent/MyThreadFactory</lookup-name>
* </resource-env-ref>
*
*
* You can also define a {@code ManagedThreadFactory} with the
* {@code } deployment descriptor element.
* For example,
*
*
* <managed-thread-factory>
* <name>java:global/concurrent/MyThreadFactory</name>
* <context-service-ref>java:global/concurrent/MyThreadFactoryContext</context-service-ref>
* <priority>4</priority>
* </managed-thread-factory>
*
*
* If a {@code managed-thread-factory} and {@code ManagedThreadFactoryDefinition}
* have the same name, their attributes are merged to define a single
* {@code ManagedThreadFactory} definition, with each attribute that is specified
* in the {@code managed-thread-factory} deployment descriptor entry taking
* precedence over the corresponding attribute of the annotation.
* If any qualifier elements are specified, the set of qualifier elements
* replaces the qualifiers attribute of the annotation.
*
* @since 3.0
*/
@Repeatable(ManagedThreadFactoryDefinition.List.class)
@Retention(RUNTIME)
@Target(TYPE)
public @interface ManagedThreadFactoryDefinition {
/**
* JNDI name of the {@link ManagedThreadFactory} instance.
* The JNDI name must be in a valid Jakarta EE namespace,
* such as,
*
* - java:comp
* - java:module
* - java:app
* - java:global
*
*
* @return ManagedThreadFactory JNDI name.
*/
String name();
/**
* List of required {@link Qualifier qualifier annotations}.
*
* A {@link ManagedThreadFactory} injection point
* with these qualifier annotations injects a bean that is
* produced by this {@code ManagedThreadFactoryDefinition}.
*
* The default value is an empty list, indicating that this
* {@code ManagedThreadFactoryDefinition} does not automatically produce
* bean instances for any injection points.
*
* When the qualifiers list is non-empty, the container creates
* a {@link ManagedThreadFactory} instance and registers
* an {@link ApplicationScoped} bean for it with the specified
* required qualifiers and required type of {@code ManagedThreadFactory}.
* The life cycle of the bean aligns with the life cycle of the application
* and the bean is not accessible from outside of the application.
* Applications must not configure a {@code java:global} {@link #name() name}
* if also configuring a non-empty list of qualifiers.
*
* Applications can define their own {@link Producer Producers}
* for {@link ManagedThreadFactory} injection points as long as the
* qualifier annotations on the producer do not conflict with the
* non-empty {@link #qualifiers()} list of a
* {@code ManagedThreadFactoryDefinition}.
*
* @return list of qualifiers.
* @since 3.1
*/
Class[] qualifiers() default {};
/**
* Determines how context is applied to threads from this
* thread factory.
*
* 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 ManagedThreadFactoryDefinition}. For example,
* if this {@code ManagedThreadFactoryDefinition} 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 instructions for capturing and propagating or clearing context.
*/
String context() default "java:comp/DefaultContextService";
/**
*
Priority for platform threads created by this thread factory.
* Virtual threads always have the priority {@link java.lang.Thread#NORM_PRIORITY}
* regardless of this setting.
*
* The default is {@link java.lang.Thread#NORM_PRIORITY}.
*
* @return the priority for new threads.
*/
int priority() default Thread.NORM_PRIORITY;
// TODO switch the link below back to
// {@link Thread#isVirtual() virtual} threads
// instead of
// virtual {@link Thread threads}
// once this project compiles against Java SE 21 again.
/**
* Indicates whether this thread factory is requested to
* create virtual {@link Thread threads}.
* Virtual threads are discussed in the {@link Thread} JavaDoc
* under the section that is titled Virtual threads.
*
* When {@code true}, the thread factory can create
* virtual threads if it is capable of doing so
* and if the request is not overridden by vendor-specific
* configuration that restricts the use of virtual threads.
*
* The default is {@code false}, indicating that the
* thread factory must not create virtual threads.
* When {@code false}, the thread factory always creates
* platform threads.
*
* When running on Java SE 17, the {@code true} value
* behaves the same as the {@code false} value and results in
* platform threads being created rather than virtual threads.
*
*
* @return {@code true} if the thread factory is requested to
* create virtual threads, otherwise {@code false}.
* @since 3.1
*/
boolean virtual() default false;
/**
* Enables multiple ManagedThreadFactoryDefinition
* annotations on the same type.
*/
@Retention(RUNTIME)
@Target(TYPE)
public @interface List {
ManagedThreadFactoryDefinition[] value();
}
}