Annotations and interfaces relating to scopes and contexts.
A scope type is a Java annotation annotated
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
The following built-in scopes are provided:
The container provides an implementation of the
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
For other kinds of invocations, a portable extension may define a custom 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
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
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
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
every client has its own private instance of the bean.
All built-in scopes are normal scopes, except for the
Contextual and injected reference validity
A reference to a bean obtained from the container via 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
ContextNotActiveExceptionis 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 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 Also:
Interface Summary Interface Description ConversationAllows the application to manage the conversation context by marking the current conversation as transient or long-running, specifying a conversation identifier, or setting the conversation timeout.
Class Summary Class Description ApplicationScoped.LiteralSupports inline instantiation of the
BeforeDestroyed.LiteralSupports inline instantiation of the
ConversationScoped.LiteralSupports inline instantiation of the
Dependent.LiteralSupports inline instantiation of the
Destroyed.LiteralSupports inline instantiation of the
Initialized.LiteralSupports inline instantiation of the
RequestScoped.LiteralSupports inline instantiation of the
SessionScoped.LiteralSupports inline instantiation of the
Exception Summary Exception Description BusyConversationExceptionIndicates that the container has rejected a request because a concurrent request is associated with the same conversation context. ContextExceptionIndicates a problem relating to context management. ContextNotActiveExceptionIndicates that a context is not active. NonexistentConversationExceptionIndicates that the conversation context could not be restored.
Annotation Types Summary Annotation Type Description ApplicationScopedSpecifies that a bean is application scoped. BeforeDestroyedAn event with this qualifier is fired when a context is about to be destroyed, i.e. ConversationScopedSpecifies that a bean is conversation scoped. DependentSpecifies that a bean belongs to the dependent pseudo-scope. DestroyedAn event with this qualifier is fired when a context is destroyed, i.e. InitializedAn event with this qualifier is fired when a context is initialized, i.e. NormalScopeSpecifies that an annotation type is a normal scope type. RequestScopedSpecifies that a bean is request scoped. SessionScopedSpecifies that a bean is session scoped.