JSF Navigation Tutorial - Programmatic Navigation

Check also:
The three golden rules of use
JSF Navigation Tutorial - Implicit Navigation
JSF Navigation Tutorial - Declarative Navigation
JSF Navigation Tutorial - Conditional Navigation
JSF Navigation Tutorial - Preemptive Navigation
JSF VS Series: Implicit Navigation VS Declarative (explicit) Navigation

Programmatic navigation is useful when you need to control navigation directly from the application.

JSF provides the NavigationHandler and ConfigurableNavigationHandler APIs that can be used for tasks such as accessing navigation cases, customizing navigation handlers, conditional navigations, and so on. It is good to know that, programmatically speaking, we can do the following:

1. Obtain access to navigation handler (NavigationHandler) using the following code:

FacesContext context = FacesContext.getCurrentInstance();

Application application = context.getApplication();

NavigationHandler nh = application.getNavigationHandler();

2. Invoke navigation case using NavigationHandler as follows:

nh.handleNavigation(context, fromAction, outcome);

nh.handleNavigation(context, fromAction, outcome, toFlowDocumentId);

3. Access the ConfigurableNavigationHandler API using the following code:

ConfigurableNavigationHandler cnh = (ConfigurableNavigationHandler) FacesContext.

getCurrentInstance().getApplication().getNavigationHandler();

4. Invoke navigation case using ConfigurableNavigationHandler as follows:

cnh.handleNavigation(context, fromAction, outcome);

cnh.handleNavigation(context, fromAction, outcome, toFlowDocumentId);

5. Retrieve one NavigationCase object by the action expression signature and outcome as shown in the following code:

NavigationCase case = cnh.getNavigationCase(context, fromAction, outcome);

NavigationCase case = cnh.getNavigationCase(context, fromAction, outcome, toFlowDocumentId);

6. Access all navigation rules into Map<String, Set<NavigationCase>>, where the keys are the <from-view-id/> values as follows:

Map<String, Set<NavigationCase>> cases = cnh.getNavigationCases();

Starting with JSF 2.2, we have wrappers for many classes that provide basic implementations and help developers to extend those classes and override only the necessary methods. Among them, we have a wrapper class for NavigationHandler, named NavigationHandlerWrapper, one for ConfigurableNavigationHandler, named ConfigurableNavigationHandlerWrapper, and one for NavigationCase, named NavigationCaseWrapper.