/**
  * Pop the top of the stack.
  *
  * @post new.getSize() == getSize() - 1;
  * @throws FatalFacesException isEmpty();
  */
 public final void pop() throws FatalFacesException {
   if (LOG.isDebugEnabled()) {
     LOG.debug("popping navigation stack (top is " + getTop() + ")");
   }
   try {
     $stack.removeLast();
   } catch (NoSuchElementException nseExc) {
     RobustCurrent.fatalProblem("stack was empty; cannot pop", LOG);
   }
 }
 /**
  * Navigate back to the previous user state. The old {@link #getTop()} is the page the user is
  * viewing currently. The {@link NavigationInstance} immediately below the top describes the state
  * the user wants to return to. This will become the new current state. However, by re-rendering
  * this state, a new entry for this state will be pushed to this stack. This means that we need to
  * remove the 2 entries at the top, and navigate to the second one.
  *
  * @post new.getSize() = getSize() - 2;
  * @post pop(); getTop().goBack();
  * @throws FacesException getSize() < 2;
  * @throws FacesException pop(); getTop().goBack();
  */
 public final void goBack() throws FacesException {
   if (getSize() < 2) {
     RobustCurrent.fatalProblem("cannot go back: no previous state in NavigationStack", LOG);
   }
   pop();
   NavigationInstance previous = getTop();
   pop();
   LOG.debug("navigating back to previous state (" + previous + ")");
   previous.navigateHere();
 }
 /**
  * Add a {@link NavigationInstance} to the top of the stack. First, we ask the old top of the
  * stack to {@link NavigationInstance#absorb(NavigationInstance) absorb} the new {@link
  * NavigationInstance} <code>ni</code>. If this succeeds, and {@link
  * NavigationInstance#absorb(NavigationInstance)} has a result that is not <code>null</code>, the
  * current top is replaced by that result. If this does return <code>null</code>, <code>ni</code>
  * is added to the stack and becomes the new {@link #getTop()}. Pushing <code>null</code> results
  * in an exception.
  *
  * @post (isEmpty() || (getTop().absorb(ni) == null)) ? new.getSize() == getSize() + 1 :
  *     new.getSize() == getSize();
  * @post (isEmpty() || (getTop().absorb(ni) == null)) ? new.getTop() == ni : new.getTop() ==
  *     getTop().absorb(ni);
  * @throws FatalFacesException ni == null;
  */
 public final void push(NavigationInstance ni) throws FatalFacesException {
   LOG.debug("pushing on stack: " + ni);
   if (ni == null) {
     RobustCurrent.fatalProblem("tried to add null to navigation stack", LOG);
   }
   NavigationInstance toPush = ni;
   if (!isEmpty()) {
     NavigationInstance joined = getTop().absorb(ni); // NullPointerException cannot happen
     if (joined != null) {
       pop(); // exception cannot happen
       toPush = joined;
     }
   }
   $stack.add(toPush);
 }