Package ej.navigation

Class Navigator

  • public class Navigator
extends Object
    The navigation controller and entry point of the framework.

    A navigator navigates by page key: the application calls a navigation method with the int key of the page to show, and the navigator resolves the key through its PageFactory. The public API accepts keys only; the application never constructs a Page at a call site.

    The navigator itself is not constructed by the application either: it is a singleton, configured once with initialize(Desktop, PageFactory) and obtained with getInstance(). Every method invoked before initialization throws IllegalStateException.

    The navigator owns a multi-level navigation history and drives the application-supplied MicroUI Desktop it is initialized with: each page's content is mounted on it, and it is shown on the first navigation. The application owns that desktop's stylesheet, render policy, and input handling; the navigator exposes no styling method. Identity is per entry — the same key may appear more than once in the history. Every navigation is animated with a Transition (default Transition.IMMEDIATE).

    The two operations that build a page, navigateTo(int) and replaceWith(int), also come in an argument-carrying form: the argument is forwarded to PageFactory.create(int, Object), which injects it into the page it builds, and the navigator keeps no reference to it. The back navigations have no such form — they re-show the page the history holds, without consulting the factory.

    MicroUI must be started before the first navigation, and every method must be called from the MicroUI thread. A navigation requested reentrantly — from a Page lifecycle hook or a NavigationListener callback fired by an in-progress navigation — is not run inline (which would corrupt the shared transition state); it is deferred with MicroUI.callSerially(Runnable) and runs once the in-progress navigation has finished.

    Since:
    0.2.0

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addNavigationListener​(NavigationListener listener)
      Registers a navigation listener.
      int getActiveKey()
      Returns the key of the active page.
      Page getActivePage()
      Returns the active page, the page on top of the history.
      List<Page> getHistory()
      Returns a copy of the navigation history as pages, ordered from the oldest at index 0 to the active page at the last index.
      int[] getHistoryKeys()
      Returns a copy of the navigation history as keys, in the same order as getHistory().
      static Navigator getInstance()
      Returns the navigator.
      static void initialize​(Desktop desktop, PageFactory factory)
      Initializes the navigator with the desktop it drives and the factory that builds its pages.
      void navigateBack()
      Navigates back, using the default transition.
      void navigateBack​(Transition transition)
      Navigates back: the active entry is popped and the entry beneath it becomes the active page.
      void navigateBackTo​(int key)
      Navigates back to the nearest page with the given key, using the default transition.
      void navigateBackTo​(int key, Transition transition)
      Navigates back to the nearest entry below the active one whose key matches; every entry above it is removed from the history.
      void navigateTo​(int key)
      Navigates to the page identified by the given key, using the default transition and carrying no argument.
      void navigateTo​(int key, Transition transition)
      Navigates to the page identified by the given key, carrying no argument.
      void navigateTo​(int key, Object argument)
      Navigates to the page identified by the given key, carrying the given argument, using the default transition.
      void navigateTo​(int key, Object argument, Transition transition)
      Navigates to the page identified by the given key: it is built by the factory from the key and the given argument, pushed on top of the history, and becomes the active page.
      void removeNavigationListener​(NavigationListener listener)
      Unregisters a previously registered navigation listener.
      void replaceWith​(int key)
      Replaces the active page with the page identified by the given key, using the default transition and carrying no argument.
      void replaceWith​(int key, Transition transition)
      Replaces the active page with the page identified by the given key, carrying no argument.
      void replaceWith​(int key, Object argument)
      Replaces the active page with the page identified by the given key, carrying the given argument, using the default transition.
      void replaceWith​(int key, Object argument, Transition transition)
      Replaces the active page with the page identified by the given key, built by the factory from the key and the given argument, keeping the history depth unchanged.
      void setTransition​(Transition transition)
      Sets the default transition used by the no-transition navigation overloads.

    • Method Detail

      • initialize

        public static void initialize​(Desktop desktop,
                              PageFactory factory)
        Initializes the navigator with the desktop it drives and the factory that builds its pages.

        Mounts the navigator's container on the given desktop and starts the navigator from a clean state: an empty history, no registered NavigationListener, and Transition.IMMEDIATE as the default transition. Calling this method again restarts the navigator from that same clean state, on the newly given desktop and factory.

        The application keeps ownership of the desktop: it applies the stylesheet, the render policy, and the input handling on it. The navigator shows it on the first navigation.

        Parameters:
        desktop - the desktop the navigator drives.
        factory - the factory building the pages the navigator navigates to.

      • navigateTo

        public void navigateTo​(int key)
        Navigates to the page identified by the given key, using the default transition and carrying no argument.
        Parameters:
        key - the key of the page to navigate to.
        Throws:
        IllegalArgumentException - if the factory does not recognize the given key.
        IllegalStateException - if the navigator has not been initialized.

      • navigateTo

        public void navigateTo​(int key,
                       Transition transition)
        Navigates to the page identified by the given key, carrying no argument.
        Parameters:
        key - the key of the page to navigate to.
        transition - the transition to animate the change with.
        Throws:
        NullPointerException - if the given transition is null, or if the factory returns a null page.
        IllegalArgumentException - if the factory does not recognize the given key.
        IllegalStateException - if the navigator has not been initialized.

      • navigateTo

        public void navigateTo​(int key,
                       @Nullable
                       Object argument)
        Navigates to the page identified by the given key, carrying the given argument, using the default transition.
        Parameters:
        key - the key of the page to navigate to.
        argument - the argument to hand the factory, or null to carry none.
        Throws:
        IllegalArgumentException - if the factory does not recognize the given key.
        IllegalStateException - if the navigator has not been initialized.

      • navigateTo

        public void navigateTo​(int key,
                       @Nullable
                       Object argument,
                       Transition transition)
        Navigates to the page identified by the given key: it is built by the factory from the key and the given argument, pushed on top of the history, and becomes the active page.

        The argument is handed to PageFactory.create(int, Object) and nowhere else: the navigator keeps no reference to it, so whatever the page needs from it, it keeps itself.

        Parameters:
        key - the key of the page to navigate to.
        argument - the argument to hand the factory, or null to carry none.
        transition - the transition to animate the change with.
        Throws:
        NullPointerException - if the given transition is null, or if the factory returns a null page.
        IllegalArgumentException - if the factory does not recognize the given key.
        IllegalStateException - if the navigator has not been initialized.

      • navigateBack

        public void navigateBack()
        Navigates back, using the default transition.
        Throws:
        IllegalStateException - if the navigator has not been initialized, or if there is nothing to go back to.

      • navigateBack

        public void navigateBack​(Transition transition)
        Navigates back: the active entry is popped and the entry beneath it becomes the active page. A preceding replaceWith(int) makes no difference — it discarded the page it replaced, so back navigation reveals the entry beneath the replacing one.

        The page returned to is the instance the history holds: the factory is not consulted, so a back navigation carries no argument.

        Parameters:
        transition - the transition to animate the change with.
        Throws:
        NullPointerException - if the given transition is null.
        IllegalStateException - if the navigator has not been initialized, or if there is no entry beneath the active one.

      • navigateBackTo

        public void navigateBackTo​(int key)
        Navigates back to the nearest page with the given key, using the default transition.
        Parameters:
        key - the key of the page to navigate back to.
        Throws:
        IllegalArgumentException - if no entry below the active one has the given key.
        IllegalStateException - if the navigator has not been initialized.

      • navigateBackTo

        public void navigateBackTo​(int key,
                           Transition transition)
        Navigates back to the nearest entry below the active one whose key matches; every entry above it is removed from the history.

        The page returned to is the instance the history holds: the factory is not consulted, so a back navigation carries no argument.

        Parameters:
        key - the key of the page to navigate back to.
        transition - the transition to animate the change with.
        Throws:
        NullPointerException - if the given transition is null.
        IllegalArgumentException - if no entry below the active one has the given key.
        IllegalStateException - if the navigator has not been initialized.

      • replaceWith

        public void replaceWith​(int key)
        Replaces the active page with the page identified by the given key, using the default transition and carrying no argument.
        Parameters:
        key - the key of the page to navigate to.
        Throws:
        IllegalArgumentException - if the factory does not recognize the given key.
        IllegalStateException - if the navigator has not been initialized.

      • replaceWith

        public void replaceWith​(int key,
                        Transition transition)
        Replaces the active page with the page identified by the given key, carrying no argument.
        Parameters:
        key - the key of the page to navigate to.
        transition - the transition to animate the change with.
        Throws:
        NullPointerException - if the given transition is null, or if the factory returns a null page.
        IllegalArgumentException - if the factory does not recognize the given key.
        IllegalStateException - if the navigator has not been initialized.

      • replaceWith

        public void replaceWith​(int key,
                        @Nullable
                        Object argument)
        Replaces the active page with the page identified by the given key, carrying the given argument, using the default transition.
        Parameters:
        key - the key of the page to navigate to.
        argument - the argument to hand the factory, or null to carry none.
        Throws:
        IllegalArgumentException - if the factory does not recognize the given key.
        IllegalStateException - if the navigator has not been initialized.

      • replaceWith

        public void replaceWith​(int key,
                        @Nullable
                        Object argument,
                        Transition transition)
        Replaces the active page with the page identified by the given key, built by the factory from the key and the given argument, keeping the history depth unchanged.

        The replaced page is discarded: the navigator keeps no reference to it, so the next navigateBack() reveals the entry beneath the replacing one. The first navigation via this method establishes its page as the root without an animation.

        The argument is handed to PageFactory.create(int, Object) and nowhere else: the navigator keeps no reference to it, so whatever the page needs from it, it keeps itself.

        Parameters:
        key - the key of the page to navigate to.
        argument - the argument to hand the factory, or null to carry none.
        transition - the transition to animate the change with.
        Throws:
        NullPointerException - if the given transition is null, or if the factory returns a null page.
        IllegalArgumentException - if the factory does not recognize the given key.
        IllegalStateException - if the navigator has not been initialized.

      • getActivePage

        public Page getActivePage()
        Returns the active page, the page on top of the history.
        Returns:
        the active page.
        Throws:
        IllegalStateException - if the navigator has not been initialized, or if the history is empty (no navigation has happened yet).

      • getActiveKey

        public int getActiveKey()
        Returns the key of the active page.
        Returns:
        the active page key.
        Throws:
        IllegalStateException - if the navigator has not been initialized, or if the history is empty (no navigation has happened yet).

      • getHistory

        public List<Page> getHistory()
        Returns a copy of the navigation history as pages, ordered from the oldest at index 0 to the active page at the last index.
        Returns:
        a copy of the history pages; an empty list when the history is empty.
        Throws:
        IllegalStateException - if the navigator has not been initialized.

      • getHistoryKeys

        public int[] getHistoryKeys()
        Returns a copy of the navigation history as keys, in the same order as getHistory(). A key may appear more than once.
        Returns:
        a copy of the history keys; an empty array when the history is empty.
        Throws:
        IllegalStateException - if the navigator has not been initialized.

      • setTransition

        public void setTransition​(Transition transition)
        Sets the default transition used by the no-transition navigation overloads.
        Parameters:
        transition - the default transition to use.
        Throws:
        NullPointerException - if the given transition is null.
        IllegalStateException - if the navigator has not been initialized.

      • addNavigationListener

        public void addNavigationListener​(NavigationListener listener)
        Registers a navigation listener. Registering an already-registered listener is a no-op.

        A listener registered while a navigation is being notified is not notified for that navigation: the listeners notified for a navigation are those registered when its notification pass starts.

        Parameters:
        listener - the listener to register.
        Throws:
        NullPointerException - if the given listener is null.
        IllegalStateException - if the navigator has not been initialized.

      • removeNavigationListener

        public void removeNavigationListener​(NavigationListener listener)
        Unregisters a previously registered navigation listener. Unregistering an unregistered listener is a no-op.

        A listener unregistered while a navigation is being notified is still notified for that navigation, and no longer from the next one on.

        Parameters:
        listener - the listener to unregister.
        Throws:
        IllegalStateException - if the navigator has not been initialized.