jakarta.enterprise.concurrent.ManagedThreadFactoryDefinition Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jakarta.enterprise.concurrent-api Show documentation
Jakarta Concurrency provides a specification for using concurrency from application components without compromising container integrity while still preserving the Jakarta EE platform’s fundamental benefits.
There is a newer version: 3.1.1
Show newest version
/*
 * 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 ManagedThreadFactory}
 * 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 @}ManagedThreadFactoryDefinition(
 *     name = "java:global/concurrent/MyThreadFactory",
 *     context = "java:global/concurrent/MyThreadFactoryContext",
 *     priority = 4)
 * {@literal @}ContextServiceDefinition(
 *     name = "java:global/concurrent/MyThreadFactoryContext",
 *     propagated = APPLICATION)
 *  public class MyServlet extends HttpServlet {
 *    {@literal @}Resource(lookup = "java:global/concurrent/MyThreadFactory",
 *               name = "java:module/concurrent/env/MyThreadFactoryRef")
 *     ManagedThreadFactory myThreadFactory;
 * 
 *
 * 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.
 *
 * @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();

    /**
     * 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 threads created by this thread factory.
     *
     * The default is {@link java.lang.Thread#NORM_PRIORITY}.
     *
     * @return the priority for new threads.
     */
    int priority() default Thread.NORM_PRIORITY;

    /**
     * Enables multiple ManagedThreadFactoryDefinition
     * annotations on the same type.
     */
    @Retention(RUNTIME)
    @Target(TYPE)
    public @interface List {
        ManagedThreadFactoryDefinition[] value();
    }
}