Scopes

Faces beans are CDI beans (see Backing Beans and CDI). In CDI a scope is a context: a store of bean instances with a lifecycle. The container creates an instance the first time a bean of that scope is used in the context, hands the same instance to everybody that uses the bean in that context, and destroys it, calling its @PreDestroy method, when the context ends. Four ideas explain most of what follows.

Faces takes @RequestScoped, @SessionScoped, @ApplicationScoped, @ConversationScoped and @Dependent from CDI (jakarta.enterprise.context) and defines three scopes of its own: @ViewScoped in jakarta.faces.view, @FlowScoped in jakarta.faces.flow and @ClientWindowScoped in jakarta.faces.lifecycle. The Jakarta EE Tutorial lists the first group under "Using Scopes" in the CDI chapter and the Faces group under "Using Managed Bean Scopes". The CDI specification puts the request and application scopes into CDI Lite and the session and conversation scopes into CDI Full, the profile of a Jakarta EE server; Weld on Tomcat, as used here, provides them as well (see Tomcat and Weld).

Source: Jakarta EE Tutorial: Using Scopes, Jakarta EE Tutorial: Using Managed Bean Scopes and Jakarta CDI 4.1 specification, 6.3 Normal scopes and pseudo-scopes

The figure follows one HTTP session through eight requests. The first browser tab makes requests 1 to 5 and 8, a second tab makes requests 6 and 7, and the session ends after request 8. Each lane is one scope, and a bar is the lifetime of one instance of that scope.

Read the lanes from the bottom. A request-scoped bean lives for exactly one request, so there is a new bar every time. A view-scoped bean spans the postbacks of one view: view A lives through requests 1 to 3 and is destroyed when request 4 navigates to another view, which creates view B. A view that is left by a redirect or abandoned with a new GET is not destroyed at that moment; the dashed bar after B shows an instance that stays in the session until the implementation evicts it or the session ends. The client window lane has two bars, one per tab: the second tab sees nothing the first tab put into its window scope, but both see the same session bean. The conversation lane shows the difference between a transient conversation (one short bar per request) and a long-running one (one bar from begin() to end() that survives requests and view changes). The flow lane lives for the stretch between entering and leaving a flow. The session and application bars are the longest.

The timeline is drawn from observation, not from the specification alone. The sections below show the code that produced each behaviour.

The quickest way to understand a scope is to watch it. The probe below is a base class that gets an instance number when it is constructed, counts clicks, and writes a line to an application-scoped log in its @PostConstruct and @PreDestroy methods. Seven tiny subclasses differ only in their scope annotation. The flow scope needs a flow definition and has its own example in @FlowScoped.

Source: Jakarta CDI 4.1 specification: Lifecycle of contextual instances and Jakarta EE Tutorial: Using Scopes

Each probe bean is a class of three lines with @Named and one scope annotation; the table gives the imports.

Two of them do a little more. The view probe injects a dependent probe, to show who owns a dependent object, and the conversation probe exposes the Conversation that CDI provides, so that the page can begin and end it.

Source: Jakarta Faces 4.1 API: ViewScoped, Jakarta Faces 4.1 API: ClientWindowScoped and Jakarta CDI 4.1 API: Conversation

The page has no web.xml of its own beyond the client window setting that @ClientWindowScoped explains, and beans.xml uses bean-discovery-mode="annotated", so the scope annotations are what make the classes beans. The same page, driven through one session in one browser window, gave these results on both Mojarra and MyFaces; the numbers are the instance numbers the probe printed, and "new" means that a new instance was created.

The log.xhtml page shows the rest. In the sequence above, the view probe that a navigation outcome without a redirect replaced was destroyed at once, while the ones left behind by a redirect or by a new GET were not destroyed at that moment; Limits of the View Scope shows when they are.

A request-scoped bean lives for one HTTP request: the first time an expression or injection point touches it, the container creates it, and it is destroyed after the response is complete. A Faces postback is a single request: values are applied, the action runs and the response is rendered, all with the same instance. With the Post/Redirect/Get pattern the redirected GET is a second, separate request with a separate instance. An Ajax request is also a request: a request-scoped bean behind an f:ajax field is rebuilt for every Ajax call.

That makes @RequestScoped the right scope for things that are really about the request: the search text and the results of a search, the parameters of a filter form, a bean that only reads data and renders it. It is also the cheapest scope, because nothing is kept after the response. The Bookshelf search page keeps the query and the result list in a request-scoped bean:

Source: Jakarta CDI 4.1 API: RequestScoped and Jakarta EE Tutorial: Using Managed Bean Scopes

The bean also uses the BookService and SearchStatistics beans from the application scope, and the IsbnFormatter from the dependent pseudo-scope; both appear below. Searching for "java" returned the two matching books and counted one search, and an empty query returned all four books and counted a second one. The result list does not need to survive the request, because the page that shows it is the response to the same request. That is the limit of this scope. A request-scoped bean cannot remember what was selected in row 3 once the postback has ended; the values it receives in the postback are written to it in the Update Model Values phase, and they are gone after Render Response. The consequences for a table that re-queries its list in every request are in Row Actions and the lifecycle context is in the phases of the lifecycle.

A request-scoped bean is also the only safe home for a bean referenced by a component’s binding attribute: component instances belong to one view and one request, and must not be shared (see the binding pitfall).

@ViewScoped is the scope that fits a Faces page best, and the reason Faces needs scopes of its own. The user opens a page, types, clicks a button that validates, an Ajax request refreshes a field, another button saves: all of that is a series of postbacks of one view, and the page expects its backing bean to be the same object throughout. A request-scoped bean forgets the draft between clicks. A session-scoped bean would keep the draft but would also share it with every tab and keep it until the session ends. A view-scoped bean is created the first time it is used on a view, survives every postback and Ajax request of that view, and is destroyed when the user leaves the view.

The annotation to import is jakarta.faces.view.ViewScoped. Do not confuse it with two classes of the same name: the old javax.faces.bean.ViewScoped of the native managed bean facility, which was removed from the platform in Faces 4.0 together with @ManagedBean, and org.omnifaces.cdi.ViewScoped, which is OmniFaces' own CDI view scope (see OmniFaces' View Scope). Like every other scope it is combined with @Named to make the bean reachable from EL. The API documentation says that the bean must be stored in the map returned by UIViewRoot.getViewMap(), that its @PostConstruct and @PreDestroy methods run when the scope begins and ends, and that the bean must be serialisable and proxyable.

The Bookshelf review page is the classic case. A reader writes a review, a counter shows how many characters are left (an f:ajax request on every key), a Preview button toggles a preview, and Save refuses an empty review with a message. All of that state lives in one view-scoped bean:

Source: Jakarta Faces 4.1 API: ViewScoped and Jakarta EE Tutorial: Using Managed Bean Scopes

In the run on both implementations the Preview button counted 1 and then, after a rejected Save, counted 2 on the same instance; the draft text was still in the field after the failed save; an Ajax keyup request for the text field abcde returned a partial response that rendered remaining=275 from the same instance; and a fresh GET of review.xhtml after leaving the page showed previews=0 again, a new instance. The bean injects FacesContext, a client proxy for the current request that is safe to keep in a passivating bean (see Serialisation, Passivation and Memory), instead of calling FacesContext.getCurrentInstance(). The view map is also visible from EL as #{viewScope}, which is the implicit object for facesContext.getViewRoot().getViewMap() in the specification; listing its keys on a page that used viewProbe returned [viewProbe] on both implementations, so in that run the bean was stored under its EL name.

A session-scoped bean lives as long as the user’s HttpSession: from the first request that touches it until invalidate() or the session timeout. Every request of that user shares the instance, in every tab. It is a passivating scope, so the class must implement Serializable and everything injected into it must be passivation capable (Serialisation, Passivation and Memory). The session context is part of CDI Full; Weld on Tomcat provides it.

Use it for state that really belongs to the user and not to a page: language and layout preferences, a login-related object that the container’s security does not already provide, and a shopping basket that must be the same in every tab. In Bookshelf the page size and colour theme of the signed-in reader are preferences:

Source: Jakarta CDI 4.1 API: SessionScoped and Jakarta CDI 4.1 specification, 17.6.1 Session context lifecycle

Submitting size 25 and theme dark kept both values on the following requests of the same session, and a second session (a second cookie jar) started with the defaults, 10 and light. Because the scope outlives any one view, three habits matter.

ExternalContext.invalidateSession() ends the session at the end of the request and destroys the session context; the Bookshelf logout action calls it and redirects. In the run, invalidating the session called @PreDestroy on the session probe and on the view probes of that session on both implementations, and on the client window probes on MyFaces only (Mojarra and MyFaces Compared). After a login, renew the session identifier to prevent session fixation; the security page covers it.

An application-scoped bean has exactly one instance for the whole web application. Every user and every thread shares it, so it must be thread-safe, and it is the right home for things that are expensive to build and the same for everybody: a service, a repository, a cache, configuration, counters. The scope is not passivating, so the class does not have to be Serializable: a class without implements Serializable deployed without complaint, where the same class in session or view scope stopped the deployment (Serialisation, Passivation and Memory). The instance is created lazily, the first time the bean is used. The Bookshelf BookService is an application-scoped bean over an immutable list, and the statistics bean counts searches with a LongAdder, a counter that is safe for concurrent increments:

Source: Jakarta CDI 4.1 API: ApplicationScoped and Jakarta CDI 4.1 specification, 6.6 Context management for built-in scopes

The onStart method observes the @Initialized(ApplicationScoped.class) event, which the container fires when the application context starts. Because the observer method belongs to the bean, the container has to create the bean to call it. In the run, the log of the application contained SearchStatistics created and application context initialized straight after the deployment, before the first request, on Mojarra and on MyFaces; the probe beans, which have no such observer, were created on first use. OmniFaces offers @Eager for the same purpose, for request, view, session and application scoped beans.

Three habits matter here. Never keep per-user data in an application-scoped field, because it is the data of whoever called last. Do not inject FacesContext or other request-bound objects and use them from the startup observer; there is no request at that point, and the backing beans page shows the ContextNotActiveException that results. And remember that the instance lives as long as the deployment, so a cache that never evicts is a memory leak with a long fuse.

Source: OmniFaces 5.5.5 API: Eager

A conversation is a scope whose boundaries the application chooses. Every servlet request has exactly one conversation. By default it is transient: it exists for that request and is destroyed at the end of it, which makes a @ConversationScoped bean behave like a request-scoped bean (in the probe, the conversation instance changed on every request until begin() was called). Calling Conversation.begin() makes the conversation long-running: it gets an identifier, survives requests, and is kept until end() or until its timeout. The conversation scope is part of CDI Full, it is passivating, and a long-running conversation is tied to one HTTP session; it cannot cross session boundaries. Weld’s default timeout was 600000 milliseconds (ten minutes) in the run, and setTimeout() changes it.

The Bookshelf loan wizard borrows a book in two steps: choose the book, then enter the borrower. The state of the first step has to survive the move to the second page, and a long-running conversation provides it without putting anything in the session for good:

Source: Jakarta CDI 4.1 API: ConversationScoped and Weld reference: Conversation propagation

How the run behaved:

Conversations are explicit, which is both their strength and their cost: forgetting end() keeps the instance until the timeout, and a long-running conversation per user is memory per user. Faces Flows (@FlowScoped) solve the same problem with the boundaries declared in the flow definition, and @ClientWindowScoped (@ClientWindowScoped) with the browser tab as the boundary. A conversation is the lowest-level of the three and the only one that does not depend on Faces at all.

@ClientWindowScoped, introduced in Faces 4.0, gives a bean the lifetime of a browser window or tab. It answers a problem that the scopes above cannot solve: an application where the user opens the same page in two tabs and edits two different books, and each tab has to keep its own state, but the state must survive when the tab navigates from one page to another. The view scope would be lost at the first navigation, and the session scope would be shared between the tabs.

The scope is built on the ClientWindow feature of Faces 2.2, which has to be switched on. The context parameter jakarta.faces.CLIENT_WINDOW_MODE takes none, which is the default and means that no ClientWindow exists, or url, which the specification requires every implementation to support, and MyFaces documents two more modes, url-redirect and client.

Source: Jakarta Faces 4.1 API: ClientWindowScoped and Jakarta Faces 4.1 API: ClientWindow

What the run showed:

The lifetime of the scope is "as long as the window remains open or the session expires", in the words of the ClientWindow documentation, but the server cannot see a tab being closed, so in practice it ends by eviction or at the end of the session. Do not put the id in a place that confers authority: it separates the state of tabs, it is not authentication. The multiple windows page covers the ClientWindow API (getId(), custom modes, disabling the id for a link; see also its section on @ClientWindowScoped), and the view state of several tabs.

@FlowScoped (jakarta.faces.flow, since 2.2) ties a bean to a Faces flow, a set of views that the user enters and leaves as a unit. The annotation takes the flow id: @FlowScoped("borrow") means that the bean is created, lazily, once the user has entered the flow borrow, and released when the user leaves it through a return node. The Faces implementation supplies the CDI extension that implements the scope, and the scope is passivating. Flows are defined by a directory convention (a folder with a start view), by a *-flow.xml file or by a @FlowDefinition producer, and have call, switch, method-call and return nodes; the Faces Flows page covers all of that, and this section only shows what the scope does.

The Bookshelf borrow request is a flow. Its state is a request for one book and a number of days:

Source: Jakarta Faces 4.1 API: FlowScoped and Jakarta EE Tutorial: Using Faces Flows

The borrow directory holds the start view borrow.xhtml, so the directory name is the flow id and the outcome borrow enters it. The run entered the flow from index.xhtml, set the days to 14 in a postback inside the flow (the bean kept 14), left through the return node done to /index, and entered again: the days were back at the default of 7, a new instance. The flow id is also available to the bean through @Inject Flow (new in Faces 4.1): the page showed flow=borrow on both implementations. The #{flowScope} implicit object is the map of the current flow’s values. A flow-scoped bean is the right size for a wizard that must not leak into the rest of the session and must start fresh when entered again. Outside the flow the scope is not active: a page shown after the return node that still reads the bean fails with WELD-001303, as the flows page shows in Reading a Flow Bean After the Flow; the client window feature that flows depend on is described in The Client Window Mode.

@Dependent is not a context at all. It is the default scope for a bean that has no scope annotation (when it is a bean in the first place, see the discovery section of the backing beans page) and it means "a new instance for each place that asks". The instance is bound to whatever it was created for: injected into a field, it lives and dies with the object that owns the field. Referenced from an EL expression through its @Named name, one instance serves one evaluation of the expression, and the API documentation says that it is reused if the name appears several times inside that one expression but never when the expression is evaluated again or when another expression is evaluated.

The run shows both rules. The probe page referenced the same @Dependent bean in two value expressions, and the two numbers differed; clicking the + button on the dependent row always left the count at 0, because the action ran on a new instance that was thrown away. The IsbnFormatter of the search page, a helper with no state, is the intended use: cheap, stateless, created where it is needed.

Source: Jakarta CDI 4.1 API: Dependent and Jakarta CDI 4.1 specification, 6.4 Dependent pseudo-scope

When a @Dependent bean is injected into a scoped bean, it is the scoped bean’s dependent object and follows its lifecycle. The view probe injects a DependentProbe: in the run the probe page showed the same dependent number as long as the view probe was the same, and a new one with each new view probe. A dependent object injected into a passivating bean must be passivation capable itself (Serialisation, Passivation and Memory). What happens when the owner is destroyed differs between the implementations:

So a @Dependent helper that holds a resource and relies on @PreDestroy to release it is a problem inside a Mojarra view-scoped bean. Release resources in the owner’s own @PreDestroy, or make the helper @ApplicationScoped or a normal-scoped bean, or use Instance<T> and destroy it explicitly.

CDI defines three lifecycle events for a scope: an event with the qualifier @Initialized(Scope.class) when its context starts, @BeforeDestroyed(Scope.class) just before it ends and @Destroyed(Scope.class) after it ended, each observable with an ordinary @Observes method. The container fires them for the scopes it owns (request, session, application and conversation). Faces 4.1 extends the requirement to the scopes that Faces implements: the Javadoc of @ViewScoped and of @FlowScoped both say that events with these qualifiers "must fire for this built-in scope", and the 4.1 change log lists the requirement as issue 1739. The Javadoc of @ClientWindowScoped has no such sentence, so do not rely on events for that scope. The event payload is not the bean: for the view scope it is the UIViewRoot and for the flow scope it is the Flow. An observer is a good place for work that belongs to the lifetime of a page and not to one bean: counting open views, logging how long a wizard lasted, or releasing something that was acquired for a view:

Source: Jakarta Faces 4.1 API: ViewScoped, FlowScoped and Jakarta Faces 4.1 specification, B.1 Changes between 4.1 and 4.0

The observer above was run with a page that had a view-scoped bean, a button that navigated to another view and a button that entered a one-view flow; the payload types are what the two implementations delivered (the typed parameters matched):

@Initialized(FlowScoped.class) fired when the flow was entered on both implementations, with the Flow (id trip) as payload. The destruction events of the flow scope did not appear in the run, and ending the session with invalidate() printed none of the view-scope events on either implementation, so an observer is not a substitute for @PreDestroy when a session expires. Portable code observes @Initialized and @Destroyed only, and does not depend on @BeforeDestroyed for the view scope.

Five of the eight scopes are passivating: session, conversation, view, client window and flow. A bean in a passivating scope must be passivation capable, and so must everything injected into it. The reason is that the state of such a bean may leave the JVM: a servlet container writes sessions to disk when it stops, or replicates them to another node of a cluster. The CDI specification defines the rule in four steps and the container checks it at deployment, which is much better than a failure in production when a node restarts.

The scratch application confirmed each rule, on Weld 6.0.4 with both implementations:

Source: Jakarta CDI 4.1 specification, 17.5 Passivation and passivating scopes and 17.5.5 Validation of passivation capable beans and dependencies

Being Serializable is a necessary condition, not a good design. The usual ways to keep a passivating bean light are these.

The cost of each scope is memory in proportion to the number of live instances, and that depends on what creates them.

A bean that is Serializable is not yet a bean that a cluster replicates. A servlet container copies a session to the other nodes when the session changes, and Tomcat’s documentation defines a change as a call of setAttribute or removeAttribute. Weld stores the session-scoped beans as session attributes (the implementations keep the view maps in the session as well), and in the bytecode of Weld 6.0.4 AttributeBeanStore the setAttribute call is made when a bean instance is added to the store, not when the bean is used. So a session-scoped or view-scoped bean that is changed in place after it was created, such as a list that a method adds to, is not replicated: a run with two Tomcat nodes and the session replicated showed the other node reading the size of such a list as 0 after three additions, on Mojarra and on MyFaces, and the same bean held as an immutable value replaced with setAttribute was replicated. The deployment and clustering page has the experiment and the replication-safe variants, @ViewScoped in a cluster the consequence for view beans, and the replication section session replication versus sticky sessions and the view state.

Pick the smallest scope that still holds what the page needs. The question is not "which scope is convenient" but "how long must this value live, and who may see it?" The answers below follow from the sections above.

Four questions decide most cases, in this order.

The most common wrong answer is to use @SessionScoped for the second question because it "just works" in a demo. In a real application the page state leaks between tabs, survives for the whole session and multiplies by the number of users. If a session-scoped bean’s fields are the values of a form, it is a candidate for @ViewScoped or @ClientWindowScoped.

Because normal scopes are injected as client proxies, a bean can be injected into a bean of a longer scope, or a shorter one. The scratch application had an @ApplicationScoped bean that injected a @SessionScoped and a @RequestScoped probe:

Source: Jakarta CDI 4.1 specification, 6.3 Normal scopes and pseudo-scopes

Two sessions requesting the page that used it got two different session numbers, and every request got a new request number; the injected object’s class was SessionProbe$Proxy$_$$_WeldClientProxy, a Weld client proxy. The table "Allowable Connections between Scoped Objects" in the Jakarta EE Tutorial, which says that an application-scoped bean may reference only none and application, belongs to the sections on configuring managed beans, the part that Faces 4.0 removed; with CDI it does not apply to normal scopes. What does apply is that the proxy needs an active context at the moment of the call. A request-scoped bean that is called from a thread with no request, a session-scoped bean from a startup observer, or a view-scoped bean from a plain servlet filter fails with ContextNotActiveException.

Source: Jakarta EE Tutorial: Allowable Connections between Scoped Objects

The expression language gives direct access to the maps behind the standard scopes, which are useful for attributes that are not beans: #{requestScope}, #{viewScope}, #{sessionScope}, #{applicationScope} and #{flowScope} are the implicit objects for ExternalContext.getRequestMap(), UIViewRoot.getViewMap(), ExternalContext.getSessionMap(), ExternalContext.getApplicationMap() and the current flow scope map. The expression language page lists all implicit objects. In a bean, the matching CDI qualifiers @ViewMap, @SessionMap, @ApplicationMap, @RequestMap and @FlowMap of jakarta.faces.annotation inject the same maps (see Injecting Faces Objects). Beans of the normal scopes are better reached through injection and @Named than through these maps, but the view scope stores its beans in the view map, and #{viewScope} showed [viewProbe] in the run.

Source: Jakarta Faces 4.1 specification, 5.6.2.1 Implicit Objects for Facelets and Programmatic Access and the implicit objects of this section

Both implementations run on the same CDI container, so everything that CDI decides is identical: the scopes of the CDI group, the passivation rules and their error messages, conversation propagation and its errors, client proxies. The differences are in the scopes that Faces implements itself, and they come from the extensions and managers of each implementation. They were observed in the same Bookshelf application on Tomcat 11.0.26 and Weld 6.0.4.

Source: Mojarra 4.1 source: ClientWindowScopeContextManager, Mojarra 4.1 source: ViewScopeContextManager and Apache MyFaces Core 4.1: configuration tables

The Mojarra lines about @PreDestroy come from a source reading that matches the run: the client window manager’s sessionDestroyed only clears the map, and the view scope manager creates a fresh CreationalContext for the destruction. If a bean releases resources in @PreDestroy, test the scope on the implementation you deploy. The servers page lists which implementation each server bundles.

Source: Jakarta Faces 4.1 specification, B.2 Changes between 4.0 and 3.0, B.1 Changes between 4.1 and 4.0 and the Javadoc "Since" tags of ClientWindowScoped, ViewScoped and FlowScoped