/**
* 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);
}