Module org.omnifaces

Package org.omnifaces.cdi

Annotation Type Eager

@Documented
@Retention(RUNTIME)
@Target({TYPE,METHOD})
public @interface Eager

The CDI annotation @Eager specifies that a scoped bean is to be eagerly instantiated.

Faces native managed beans have been deprecated in favor of CDI managed beans. One feature that those Faces native managed beans had that's not directly available for CDI managed beans is the ability to eagerly instantiate application scoped beans.

OmniFaces fills this void and even goes one step further by introducing the @Eager annotation that can be applied to @RequestScoped, @ViewScoped, @SessionScoped and @ApplicationScoped beans. This causes these beans to be instantiated automatically at the start of each such scope instead of on demand when a bean is first referenced.

In case of @RequestScoped and @ViewScoped beans instantiation happens per request URI / view and an extra attribute is required for specifying this.

Supported scopes

Currently supported scopes:

1. CDI RequestScoped
2. CDI ViewScoped
3. OmniFaces ViewScoped
4. CDI SessionScoped
5. CDI ApplicationScoped

Usage

E.g. The following bean will be instantiated during application's startup:

 @Eager
 @ApplicationScoped
 public class MyEagerApplicationScopedBean {

     @PostConstruct
     public void init() {
         System.out.println("Application scoped init!");
     }
 }
 

Note: you can also use the stereotype @Startup for this instead.

The following bean will be instantiated whenever a session is created:

 @Eager
 @SessionScoped
 public class MyEagerSessionScopedBean implements Serializable {

     private static final long serialVersionUID = 1L;

     @PostConstruct
     public void init() {
         System.out.println("Session scoped init!");
     }
 }
 

The following bean will be instantiated whenever the URI /components/cache (relatively to the application root) is requested, i.e. when an app is deployed to /myapp at localhost this will correspond to a URL like https://example.com/myapp/components/cache:

 @Eager(requestURI = "/components/cache")
 @RequestScoped
 public class MyEagerRequestScopedBean {

     @PostConstruct
     public void init() {
         System.out.println("/components/cache requested");
     }
 }
 

FacesContext in @PostConstruct

When using @Eager or @Eager(requestURI), be aware that the FacesContext is not available in the @PostConstruct. Reason is, the FacesServlet isn't invoked yet at the moment @Eager bean is constructed. Only in @Eager(viewId), the FacesContext is available in the @PostConstruct.

In case you need information from HttpServletRequest, HttpSession and/or ServletContext, then you can just @Inject it right away. Also, all other CDI managed beans are available the usual way via @Inject, as long as they do also not depend on FacesContext in their @PostConstruct.

Since:

1.8

Author:

Arjan Tijms

See Also:

EagerExtension, EagerBeansRepository, EagerBeansPhaseListener, EagerBeansWebListener

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	requestURI	(Required when combined with RequestScoped) The URI (relative to the root of the web app) for which a request scoped bean should be instantiated.
String	viewId	(Required when combined with RequestScoped or ViewScoped) The id of the view for which a request or view scoped bean should be instantiated.

Element Detail

requestURI

String requestURI

(Required when combined with RequestScoped) The URI (relative to the root of the web app) for which a request scoped bean should be instantiated. When this attribute is specified the bean will be instantiated very early during request processing, namely just before the first Servlet Filter is invoked, but after a SAM.

Faces services will not be available (yet) when the bean is instantiated this way.

If both this attribute and viewId() is specified, this attribute takes precedence for RequestScoped. This attribute can not be used for ViewScoped beans.

Returns:

The request URI relative to the context root.

Default:

""

viewId

String viewId

(Required when combined with RequestScoped or ViewScoped) The id of the view for which a request or view scoped bean should be instantiated. When this attribute is specified the bean will be instantiated during invocation of the FacesServlet, namely right after the RESTORE_VIEW phase (see PhaseId.RESTORE_VIEW).

Faces services are available when the bean is instantiated this way.

If both this attribute and requestURI() is specified and the scope is RequestScoped, the requestURI attribute takes precedence. If the scope is ViewScoped requestURI is ignored and only this attribute is considered.

Returns:

The view ID.

Default:

""