com.holonplatform.vaadin.flow.navigator

## Interface Navigator

- All Superinterfaces:
    Serializable
  All Known Implementing Classes:
    DefaultNavigator

      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.
    `void` | `navigateToLocation(String location)` Navigate to the given location.
    `void` | `navigateToPrevious()` Navigates to the previous route, if available.
    `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.

    - #### navigateToPrevious

          void navigateToPrevious()

      Navigates to the previous route, if available. If a previous route is not available, navigates to the default route.

      This method can be used to navigate back in the route targets sequence handled by the UI Router or Navigator, it has not the same effect and purpose of the `navigateBack()` method, which can be used to navigate back in the browser history.

      See Also:
        `navigateToDefault()`

    - #### 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 © 2020 The Holon Platform. All rights reserved.