com.holonplatform.vaadin.flow.navigator

## Interface Navigator

- All Superinterfaces:
    Serializable

      public interface Navigator
      extends Serializable

  Handles the navigation between the available UI routes, relying on the UI `Router` to implement the actual routing.

  A route is decalred using the `Route` annotation and bound to a navigation path. See the `Router` documentation for more information about route definitions and routing layouts.

  The `Navigator` supports navigation parameters declaration and mapping, performing the parameters value serialization to translate the Java type values into the `String` type URL parameter values.

  It provides the `navigateBack()` method to navigate back in the browser history.

  The `get()` static method can be used to obtain the `Navigator` reference for the current UI.

  Since:
    5.2.0
  See Also:
    `QueryParameter`, `NavigationParameterMapper`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `Navigator.NavigationBuilder` A builder to create a navigation location and trigger the navigation action.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CONTEXT_KEY` Default `Context` resource key.
    `static String` | `DEFAULT_NAVIGATION_FAILED_MESSAGE` Default navigation failed error message.
    `static String` | `DEFAULT_NAVIGATION_FAILED_MESSAGE_CODE` Default navigation failed error message localization code.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `com.holonplatform.core.Registration` | `addNavigationChangeListener(NavigationChangeListener navigationChangeListener)` Add a `NavigationChangeListener` to listen to navigation target/location changes.
    `static Navigator` | `create(com.vaadin.flow.component.UI ui)` Create a new `Navigator` bound to given UI.
    `static Navigator` | `get()` Get the `Navigator` bound to the current UI.
    `<T,C extends com.vaadin.flow.component.Component & com.vaadin.flow.router.HasUrlParameter<T>> String` | `getUrl(Class<? extends C> navigationTarget, List<T> parameters)` Get the registered URL for given navigation target class, including the given `parameters` in the url.
    `default <T,C extends com.vaadin.flow.component.Component & com.vaadin.flow.router.HasUrlParameter<T>> String` | `getUrl(Class<? extends C> navigationTarget, T... parameters)` Get the registered URL for given navigation target class, including the given `parameters` in the url.
    `default <T,C extends com.vaadin.flow.component.Component & com.vaadin.flow.router.HasUrlParameter<T>> String` | `getUrl(Class<? extends C> navigationTarget, T parameter)` Get the registered URL for given navigation target class, including the given `parameter` in the url.
    `String` | `getUrl(Class<? extends com.vaadin.flow.component.Component> navigationTarget)` Get the registered URL for given navigation target class.
    `void` | `navigateBack()` Navigates back.
    `default <T,C extends com.vaadin.flow.component.Component & com.vaadin.flow.router.HasUrlParameter<T>> void` | `navigateTo(Class<? extends C> navigationTarget, List<T> pathParameters)` Navigate to the given navigation target and provide the given `pathParameters` in the URL.
    `default <T,C extends com.vaadin.flow.component.Component & com.vaadin.flow.router.HasUrlParameter<T>> void` | `navigateTo(Class<? extends C> navigationTarget, List<T> pathParameters, Map<String,Object> queryParameters)` Navigate to the given navigation target, providing the given `pathParameters` in the URL and the given query parameters.
    `default <T,C extends com.vaadin.flow.component.Component & com.vaadin.flow.router.HasUrlParameter<T>> void` | `navigateTo(Class<? extends C> navigationTarget, T pathParameter)` Navigate to the given navigation target and provide the given `pathParameter` in the URL.
    `default <T,C extends com.vaadin.flow.component.Component & com.vaadin.flow.router.HasUrlParameter<T>> void` | `navigateTo(Class<? extends C> navigationTarget, T pathParameter, Map<String,Object> queryParameters)` Navigate to the given navigation target, providing the given `pathParameter` in the URL and the given query parameters.
    `default void` | `navigateTo(Class<? extends com.vaadin.flow.component.Component> navigationTarget)` Navigate to the given navigation target.
    `default void` | `navigateTo(Class<? extends com.vaadin.flow.component.Component> navigationTarget, Map<String,Object> queryParameters)` Navigate to the given navigation target, using the provided query parameters.
    `default void` | `navigateTo(String path)` Navigate to the given path.
    `void` | `navigateTo(String path, Map<String,Object> queryParameters)` Navigate to the given path, using the provided query parameters.
    `void` | `navigateToDefault()` Navigates to the default navigation target, i.e. navigates to the empty `""` route path.
    `void` | `navigateToLocation(String location)` Navigate to the given location.
    `default Navigator.NavigationBuilder` | `navigation(Class<? extends com.vaadin.flow.component.Component> navigationTarget)` Gets a `Navigator.NavigationBuilder` to fluently build a navigation location for the given `navigationTarget`, including any URL query parameter.
    `default Navigator.NavigationBuilder` | `navigation(String path)` Gets a `Navigator.NavigationBuilder` to fluently build a navigation location for the given `path`, including any URL query parameter.

- - ### Field Detail

    - #### DEFAULT_NAVIGATION_FAILED_MESSAGE

          static final String DEFAULT_NAVIGATION_FAILED_MESSAGE

      Default navigation failed error message.
      See Also:
        Constant Field Values

    - #### DEFAULT_NAVIGATION_FAILED_MESSAGE_CODE

          static final String DEFAULT_NAVIGATION_FAILED_MESSAGE_CODE

      Default navigation failed error message localization code.
      See Also:
        Constant Field Values

    - #### CONTEXT_KEY

          static final String CONTEXT_KEY

      Default `Context` resource key.

  - ### Method Detail

    - #### navigateToLocation

          void navigateToLocation(String location)

      Navigate to the given location.

      The location may include a set of query path parameters, using the default `?` separator.

      Parameters:
        `location` - The location to navigate to. If `null`, the default (`""`) location will be used

    - #### navigateTo

          default void navigateTo(String path)

      Navigate to the given path.
      Parameters:
        `path` - The path to navigate to. If `null`, the default (`""`) path will be used

    - #### navigateTo

          void navigateTo(String path,
                          Map<String,Object> queryParameters)

      Navigate to the given path, using the provided query parameters.

      The query parameter values will be serialized to be included in the navigation location URL, using a `NavigationParameterMapper`. See the `QueryParameter` annotation to learn about the supported query parameter value types.

      Parameters:
        `path` - The path to navigate to. If `null`, the default (`""`) path will be used
        `queryParameters` - A map of query parameters, which associates the parameter names to their values

    - #### navigateTo

          default void navigateTo(Class<? extends com.vaadin.flow.component.Component> navigationTarget,
                                  Map<String,Object> queryParameters)

      Navigate to the given navigation target, using the provided query parameters.

      The query parameter values will be serialized to be included in the navigation location URL, using a `NavigationParameterMapper`. See the `QueryParameter` annotation to learn about the supported query parameter value types.

      The navigation target must be declared as a route, for example using the `Route` annotation.

      Parameters:
        `navigationTarget` - The navigation target to navigate to (not null)
        `queryParameters` - A map of query parameters, which associates the parameter names to their values

    - #### navigateTo

          default void navigateTo(Class<? extends com.vaadin.flow.component.Component> navigationTarget)

      Navigate to the given navigation target.

      The navigation target must be declared as a route, for example using the `Route` annotation.

      Parameters:
        `navigationTarget` - The navigation target to navigate to (not null)

    - #### navigateTo

          default <T,C extends com.vaadin.flow.component.Component & com.vaadin.flow.router.HasUrlParameter<T>> void navigateTo(Class<? extends C> navigationTarget,
                                                                                                                                T pathParameter)

      Navigate to the given navigation target and provide the given `pathParameter` in the URL.

      The navigation target must be declared as a route and implement the `HasUrlParameter` interface.

      Type Parameters:
        `T` - Path parameter type
        `C` - Navigation target type
      Parameters:
        `navigationTarget` - The navigation target to navigate to (not null)
        `pathParameter` - The parameter to include into the navigation url

    - #### navigateTo

          default <T,C extends com.vaadin.flow.component.Component & com.vaadin.flow.router.HasUrlParameter<T>> void navigateTo(Class<? extends C> navigationTarget,
                                                                                                                                List<T> pathParameters)

      Navigate to the given navigation target and provide the given `pathParameters` in the URL.

      The navigation target must be declared as a route and implement the `HasUrlParameter` interface.

      Type Parameters:
        `T` - Path parameter type
        `C` - Navigation target type
      Parameters:
        `navigationTarget` - The navigation target to navigate to (not null)
        `pathParameters` - The parameters to include into the navigation url

    - #### navigateTo

          default <T,C extends com.vaadin.flow.component.Component & com.vaadin.flow.router.HasUrlParameter<T>> void navigateTo(Class<? extends C> navigationTarget,
                                                                                                                                T pathParameter,
                                                                                                                                Map<String,Object> queryParameters)

      Navigate to the given navigation target, providing the given `pathParameter` in the URL and the given query parameters.

      The navigation target must be declared as a route and implement the `HasUrlParameter` interface.

      Type Parameters:
        `T` - Path parameter type
        `C` - Navigation target type
      Parameters:
        `navigationTarget` - The navigation target to navigate to (not null)
        `pathParameter` - The parameter to include into the navigation url (not null)
        `queryParameters` - A map of query parameters, which associates the parameter names to their values

    - #### navigateTo

          default <T,C extends com.vaadin.flow.component.Component & com.vaadin.flow.router.HasUrlParameter<T>> void navigateTo(Class<? extends C> navigationTarget,
                                                                                                                                List<T> pathParameters,
                                                                                                                                Map<String,Object> queryParameters)

      Navigate to the given navigation target, providing the given `pathParameters` in the URL and the given query parameters.

      The navigation target must be declared as a route and implement the `HasUrlParameter` interface.

      Type Parameters:
        `T` - Path parameter type
        `C` - Navigation target type
      Parameters:
        `navigationTarget` - The navigation target to navigate to (not null)
        `pathParameters` - The parameters to include into the navigation url (not null)
        `queryParameters` - A map of query parameters, which associates the parameter names to their values

    - #### navigateToDefault

          void navigateToDefault()

      Navigates to the default navigation target, i.e. navigates to the empty `""` route path.

    - #### navigateBack

          void navigateBack()

      Navigates back.

      This has the same effect as if the user would press the back button in the browser.

    - #### navigation

          default Navigator.NavigationBuilder navigation(String path)

      Gets a `Navigator.NavigationBuilder` to fluently build a navigation location for the given `path`, including any URL query parameter.

      The `Navigator.NavigationBuilder.navigate()` can be used to trigger the actual navigation. Otherwise, the navigation location can be obtained as a `Location`, using `Navigator.NavigationBuilder.asLocation()` or as a URL, using `Navigator.NavigationBuilder.asLocationURL()`.

      Parameters:
        `path` - The path to navigate to. If `null`, the default (`""`) path will be used
      Returns:
        A new `Navigator.NavigationBuilder`

    - #### navigation

          default Navigator.NavigationBuilder navigation(Class<? extends com.vaadin.flow.component.Component> navigationTarget)

      Gets a `Navigator.NavigationBuilder` to fluently build a navigation location for the given `navigationTarget`, including any URL query parameter.

      The `Navigator.NavigationBuilder.navigate()` can be used to trigger the actual navigation. Otherwise, the navigation location can be obtained as a `Location`, using `Navigator.NavigationBuilder.asLocation()` or as a URL, using `Navigator.NavigationBuilder.asLocationURL()`.

      Parameters:
        `navigationTarget` - The navigation target to navigate to (not null)
      Returns:
        A new `Navigator.NavigationBuilder`

    - #### getUrl

          String getUrl(Class<? extends com.vaadin.flow.component.Component> navigationTarget)

      Get the registered URL for given navigation target class.

      This method ignores any declared URL parameter, and always returns the navigation target base URL. To obtain the URL for a navigation target with required URL parameters, use `getUrl(Class, List)` or `getUrl(Class, Object)`.

      Parameters:
        `navigationTarget` - The navigation target to get URL for (not null)
      Returns:
        The URL for the given navigation target

    - #### getUrl

          default <T,C extends com.vaadin.flow.component.Component & com.vaadin.flow.router.HasUrlParameter<T>> String getUrl(Class<? extends C> navigationTarget,
                                                                                                                              T parameter)

      Get the registered URL for given navigation target class, including the given `parameter` in the url.
      Type Parameters:
        `T` - URL parameter type
        `C` - Navigation target type
      Parameters:
        `navigationTarget` - The navigation target to get url for (not null)
        `parameter` - The parameter to include in the generated URL (not null)
      Returns:
        The URL for the given navigation target, including the given URL parameter

    - #### getUrl

          default <T,C extends com.vaadin.flow.component.Component & com.vaadin.flow.router.HasUrlParameter<T>> String getUrl(Class<? extends C> navigationTarget,
                                                                                                                              T... parameters)

      Get the registered URL for given navigation target class, including the given `parameters` in the url.
      Type Parameters:
        `T` - URL parameters type
        `C` - Navigation target type
      Parameters:
        `navigationTarget` - The navigation target to get url for (not null)
        `parameters` - The parameters to include in the generated URL (not null)
      Returns:
        The URL for the given navigation target, including the given URL parameters

    - #### getUrl

          <T,C extends com.vaadin.flow.component.Component & com.vaadin.flow.router.HasUrlParameter<T>> String getUrl(Class<? extends C> navigationTarget,
                                                                                                                      List<T> parameters)

      Get the registered URL for given navigation target class, including the given `parameters` in the url.
      Type Parameters:
        `T` - URL parameters type
        `C` - Navigation target type
      Parameters:
        `navigationTarget` - The navigation target to get url for (not null)
        `parameters` - The parameters to include in the generated URL (not null)
      Returns:
        The URL for the given navigation target, including the given URL parameters

    - #### addNavigationChangeListener

          com.holonplatform.core.Registration addNavigationChangeListener(NavigationChangeListener navigationChangeListener)

      Add a `NavigationChangeListener` to listen to navigation target/location changes.
      Parameters:
        `navigationChangeListener` - The listener to add (not null)
      Returns:
        The registration handler

    - #### get

          static Navigator get()

      Get the `Navigator` bound to the current UI.

      If a `Navigator` is available as a `Context` resource using the `CONTEXT_KEY` resource key, that instance is returned.

      Otherwise, if a `Navigator` session registry is available, it is used to obtain the `Navigator` bound the current UI, or a new `Navigator` instance is created and returned is the session registry is missing.

      When a `Navigator` is not available as a `Context` resource, the `UI.getCurrent()` method is used to obtain the current UI and if it is not available an `IllegalStateException` is thrown.

      Returns:
        The `Navigator` bound to the current UI
      Throws:
        `IllegalStateException` - If a `Navigator` is not available from `Context` and the current UI is not available through `UI.getCurrent()`

    - #### create

          static Navigator create(com.vaadin.flow.component.UI ui)

      Create a new `Navigator` bound to given UI.

      The recomended way to obtain a `Navigator` reference is to use the `get()` method.

      Parameters:
        `ui` - The `UI` to which the navigator is bound (not null)
      Returns:
        A new `Navigator` instance

Copyright © 2019 The Holon Platform. All rights reserved.