SeamFramework.orgCommunity Documentation

Chapter 4. Scopes and contexts

4.1. Scope types
4.2. Built-in scopes
4.3. The conversation scope
4.3.1. Conversation demarcation
4.3.2. Conversation propagation
4.3.3. Conversation timeout
4.4. The dependent pseudo-scope
4.4.1. The @New annotation

So far, we've seen a few examples of scope type annotations. The scope of a Web Bean determines the lifecycle of instances of the Web Bean. The scope also determines which clients refer to which instances of the Web Bean. According to the Web Beans specification, a scope determines:

  • When a new instance of any Web Bean with that scope is created

  • When an existing instance of any Web Bean with that scope is destroyed

  • Which injected references refer to any instance of a Web Bean with that scope

For example, if we have a session scoped Web Bean, CurrentUser, all Web Beans that are called in the context of the same HttpSession will see the same instance of CurrentUser. This instance will be automatically created the first time a CurrentUser is needed in that session, and automatically destroyed when the session ends.

Web Beans features an extensible context model. It is possible to define new scopes by creating a new scope type annotation:

@Retention(RUNTIME)
@Target({TYPE, METHOD})
@ScopeType
public @interface ClusterScoped {}

Of course, that's the easy part of the job. For this scope type to be useful, we will also need to define a Context object that implements the scope! Implementing a Context is usually a very technical task, intended for framework development only.

We can apply a scope type annotation to a Web Bean implementation class to specify the scope of the Web Bean:

@ClusterScoped
public class SecondLevelCache { ... }

Usually, you'll use one of Web Beans' built-in scopes.

Web Beans defines four built-in scopes:

For a web application that uses Web Beans:

The request and application scopes are also active:

If the application tries to invoke a Web Bean with a scope that does not have an active context, a ContextNotActiveException is thrown by the Web Bean manager at runtime.

Three of the four built-in scopes should be extremely familiar to every Java EE developer, so let's not waste time discussing them here. One of the scopes, however, is new.

The Web Beans conversation scope is a bit like the traditional session scope in that it holds state associated with a user of the system, and spans multiple requests to the server. However, unlike the session scope, the conversation scope:

A conversation represents a task, a unit of work from the point of view of the user. The conversation context holds state associated with what the user is currently working on. If the user is doing multiple things at the same time, there are multiple conversations.

The conversation context is active during any JSF request. However, most conversations are destroyed at the end of the request. If a conversation should hold state across multiple requests, it must be explicitly promoted to a long-running conversation.

In addition to the four built-in scopes, Web Beans features the so-called dependent pseudo-scope. This is the default scope for a Web Bean which does not explicitly declare a scope type.

For example, this Web Bean has the scope type @Dependent:

public class Calculator { ... }

When an injection point of a Web Bean resolves to a dependent Web Bean, a new instance of the dependent Web Bean is created every time the first Web Bean is instantiated. Instances of dependent Web Beans are never shared between different Web Beans or different injection points. They are dependent objects of some other Web Bean instance.

Dependent Web Bean instances are destroyed when the instance they depend upon is destroyed.

Web Beans makes it easy to obtain a dependent instance of a Java class or EJB bean, even if the class or EJB bean is already declared as a Web Bean with some other scope type.