jakarta.enterprise.context.package-info Maven / Gradle / Ivy
/*
* JBoss, Home of Professional Open Source
* Copyright 2010, Red Hat, Inc., and individual contributors
* by the @authors tag. See the copyright.txt in the distribution for a
* full listing of individual contributors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* Annotations and interfaces relating to scopes and contexts.
*
* A scope type is a Java annotation annotated
* {@link jakarta.inject.Scope @Scope} or
* {@link jakarta.enterprise.context.NormalScope @NormalScope}.
* The scope of a bean determines the lifecycle and visibility of
* its instances. In particular, the scope determines:
*
*
* - When a new instance of the bean is created
* - When an existing instance of the bean is destroyed
* - Which injected references refer to any instance of the
* bean
*
*
* Built-in scopes
*
* The following built-in scopes are provided:
* {@link jakarta.enterprise.context.Dependent @Dependent},
* {@link jakarta.enterprise.context.RequestScoped @RequestScoped},
* {@link jakarta.enterprise.context.ConversationScoped @ConversationScoped},
* {@link jakarta.enterprise.context.SessionScoped @SessionScoped},
* {@link jakarta.enterprise.context.ApplicationScoped @ApplicationScoped},
* {@link jakarta.inject.Singleton @Singleton}.
*
* The container provides an implementation of the Context
* interface for each of the built-in scopes. The built-in request,
* session, and application contexts support servlet, web service
* and EJB invocations. The built-in conversation context supports
* JSF requests.
*
* For other kinds of invocations, a portable extension may define a
* custom {@linkplain jakarta.enterprise.context.spi.Context context object}
* for any or all of the built-in scopes. For example, a third-party web
* application framework might provide a conversation context object for
* the built-in conversation scope.
*
* The context associated with a built-in scope propagates across
* local, synchronous Java method calls, including invocation of EJB
* local business methods. The context does not propagate across remote
* method invocations or to asynchronous processes such as JMS message
* listeners or EJB timer service timeouts.
*
* Normal scopes and pseudo-scopes
*
* Most scopes are normal scopes. Normal scopes are declared
* using {@link jakarta.enterprise.context.NormalScope @NormalScope}.
* If a bean has a normal scope, every client executing in a certain
* thread sees the same contextual instance of the bean. This instance is
* called the current instance of the bean. The operation
* {@link jakarta.enterprise.context.spi.Context#get(Contextual)} of the
* context object for a normal scope type always returns the current
* instance of the given bean.
*
* Any scope that is not a normal scope is called a pseudo-scope.
* Pseudo-scopes are declared using {@link jakarta.inject.Scope @Scope}.
* The concept of a current instance is not well-defined in the case of
* a pseudo-scope. Different clients executing in the same thread may
* see different instances of the bean. In the extreme case of the
* {@link jakarta.enterprise.context.Dependent @Dependent} pseudo-scope,
* every client has its own private instance of the bean.
*
* All built-in scopes are normal scopes, except for the
* {@link jakarta.enterprise.context.Dependent @Dependent} and
* {@link jakarta.inject.Singleton @Singleton} pseudo-scopes.
*
* Contextual and injected reference validity
*
* A reference to a bean obtained from the container via {@linkplain
* jakarta.enterprise.inject.Instance programmatic lookup} is called a
* contextual reference. A contextual reference for a bean with a normal
* scope refers to the current instance of the bean. A contextual
* reference for a bean are valid only for a certain period of time. The
* application should not invoke a method of an invalid reference.
*
* The validity of a contextual reference for a bean depends upon
* whether the scope of the bean is a normal scope or a pseudo-scope:
*
*
* - Any reference to a bean with a normal scope is valid as long as
* the application maintains a hard reference to it. However, it may
* only be invoked when the context associated with the normal scope is
* active. If it is invoked when the context is inactive, a
* {@link jakarta.enterprise.context.ContextNotActiveException} is thrown
* by the container.
* - Any reference to a bean with a pseudo-scope is valid until the
* bean instance to which it refers is destroyed. It may be invoked
* even if the context associated with the pseudo-scope is not active.
* If the application invokes a method of a reference to an instance
* that has already been destroyed, the behavior is undefined.
*
*
* A reference to a bean obtained from the container via {@linkplain
* jakarta.inject.Inject dependency injection} is a special kind of
* contextual reference, called an injected reference. Additional
* restrictions apply to the validity of an injected reference:
*
*
* - A reference to a bean injected into a field, bean constructor or
* initializer method is only valid until the object into which it was
* injected is destroyed.
* - A reference to a bean injected into a producer method is only
* valid until the producer method bean instance that is being produced
* is destroyed.
-
*
- A reference to a bean injected into a disposer method or observer
* method is only valid until the invocation of the method completes.
*
*
* @see jakarta.enterprise.inject
*
*/
package jakarta.enterprise.context;
import jakarta.enterprise.context.spi.Contextual;