DelegatingNavigationHandlerProxy (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.web.jsf

## Class DelegatingNavigationHandlerProxy

- java.lang.Object
- - javax.faces.application.NavigationHandler
  - - org.springframework.web.jsf.DelegatingNavigationHandlerProxy

-     public class DelegatingNavigationHandlerProxy
      extends NavigationHandler

  JSF NavigationHandler implementation that delegates to a NavigationHandler bean obtained from the Spring root WebApplicationContext.

  Configure this handler proxy in your `faces-config.xml` file as follows:

       <application>
         ...
         <navigation-handler>
                 org.springframework.web.jsf.DelegatingNavigationHandlerProxy
         </navigation-handler>
         ...
       </application>

  By default, the Spring ApplicationContext will be searched for the NavigationHandler under the bean name "jsfNavigationHandler". In the simplest case, this is a plain Spring bean definition like the following. However, all of Spring's bean configuration power can be applied to such a bean, in particular all flavors of dependency injection.

       <bean name="jsfNavigationHandler" class="mypackage.MyNavigationHandler">
         <property name="myProperty" ref="myOtherBean"/>
       </bean>

  The target NavigationHandler bean will typically extend the standard JSF NavigationHandler class. However, note that decorating the original NavigationHandler (the JSF provider's default handler) is not supported in such a scenario, since we can't inject the original handler in standard JSF style (that is, as constructor argument).

  For decorating the original NavigationHandler, make sure that your target bean extends Spring's DecoratingNavigationHandler class. This allows to pass in the original handler as method argument, which this proxy automatically detects. Note that a DecoratingNavigationHandler subclass will still work as standard JSF NavigationHandler as well!

  This proxy may be subclassed to change the bean name used to search for the navigation handler, change the strategy used to obtain the target handler, or change the strategy used to access the ApplicationContext (normally obtained via `FacesContextUtils.getWebApplicationContext(FacesContext)`).

  Since:
    1.2.7
  Author:
    Juergen Hoeller, Colin Sampaleanu
  See Also:
    `DecoratingNavigationHandler`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `DEFAULT_TARGET_BEAN_NAME` Default name of the target bean in the Spring application context: "jsfNavigationHandler"

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DelegatingNavigationHandlerProxy()` Create a new DelegatingNavigationHandlerProxy.
    `DelegatingNavigationHandlerProxy(NavigationHandler originalNavigationHandler)` Create a new DelegatingNavigationHandlerProxy.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected BeanFactory` | `getBeanFactory(FacesContext facesContext)` Retrieve the Spring BeanFactory to delegate bean name resolution to.
    `protected NavigationHandler` | `getDelegate(FacesContext facesContext)` Return the target NavigationHandler to delegate to.
    `protected String` | `getTargetBeanName(FacesContext facesContext)` Return the name of the target NavigationHandler bean in the BeanFactory.
    `protected WebApplicationContext` | `getWebApplicationContext(FacesContext facesContext)` Retrieve the web application context to delegate bean name resolution to.
    `void` | `handleNavigation(FacesContext facesContext, String fromAction, String outcome)` Handle the navigation request implied by the specified parameters, through delegating to the target bean in the Spring application context.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_TARGET_BEAN_NAME

          public static final String DEFAULT_TARGET_BEAN_NAME

      Default name of the target bean in the Spring application context: "jsfNavigationHandler"
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DelegatingNavigationHandlerProxy

          public DelegatingNavigationHandlerProxy()

      Create a new DelegatingNavigationHandlerProxy.

    - #### DelegatingNavigationHandlerProxy

          public DelegatingNavigationHandlerProxy(NavigationHandler originalNavigationHandler)

      Create a new DelegatingNavigationHandlerProxy.
      Parameters:
        `originalNavigationHandler` - the original NavigationHandler

  - ### Method Detail

    - #### handleNavigation

          public void handleNavigation(FacesContext facesContext,
                              String fromAction,
                              String outcome)

      Handle the navigation request implied by the specified parameters, through delegating to the target bean in the Spring application context.

      The target bean needs to extend the JSF NavigationHandler class. If it extends Spring's DecoratingNavigationHandler, the overloaded `handleNavigation` method with the original NavigationHandler as argument will be used. Else, the standard `handleNavigation` method will be called.

      Specified by:
        `handleNavigation` in class `NavigationHandler`

    - #### getDelegate

          protected NavigationHandler getDelegate(FacesContext facesContext)

      Return the target NavigationHandler to delegate to.

      By default, a bean with the name "jsfNavigationHandler" is obtained from the Spring root WebApplicationContext, for every invocation.

      Parameters:
        `facesContext` - the current JSF context
      Returns:
        the target NavigationHandler to delegate to
      See Also:
        `getTargetBeanName(javax.faces.context.FacesContext)`, `getBeanFactory(javax.faces.context.FacesContext)`

    - #### getTargetBeanName

          protected String getTargetBeanName(FacesContext facesContext)

      Return the name of the target NavigationHandler bean in the BeanFactory. Default is "jsfNavigationHandler".
      Parameters:
        `facesContext` - the current JSF context
      Returns:
        the name of the target bean

    - #### getBeanFactory

          protected BeanFactory getBeanFactory(FacesContext facesContext)

      Retrieve the Spring BeanFactory to delegate bean name resolution to.

      Default implementation delegates to `getWebApplicationContext`. Can be overridden to provide an arbitrary BeanFactory reference to resolve against; usually, this will be a full Spring ApplicationContext.

      Parameters:
        `facesContext` - the current JSF context
      Returns:
        the Spring BeanFactory (never `null`)
      See Also:
        `getWebApplicationContext(javax.faces.context.FacesContext)`

    - #### getWebApplicationContext

          protected WebApplicationContext getWebApplicationContext(FacesContext facesContext)

      Retrieve the web application context to delegate bean name resolution to.

      Default implementation delegates to FacesContextUtils.

      Parameters:
        `facesContext` - the current JSF context
      Returns:
        the Spring web application context (never `null`)
      See Also:
        `FacesContextUtils.getRequiredWebApplicationContext(javax.faces.context.FacesContext)`