jakarta.faces.application.ConfigurableNavigationHandler Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jakarta.faces Show documentation
EE4J Compatible Implementation for Jakarta Faces API
The newest version!
/*
 * Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package jakarta.faces.application;

import java.util.Map;
import java.util.Set;

import jakarta.faces.context.FacesContext;
import jakarta.faces.flow.Flow;

/**
 * 
 * ConfigurableNavigationHandler extends the contract of
 * {@link NavigationHandler} to allow runtime inspection of the {@link NavigationCase}s that make up the rule-base for
 * navigation. An implementation compliant with the version of the specification in which this class was introduced (or
 * a later version) must make it so that its NavigationHandler is an extension of this class.
 * 
 *
 * @since 2.0
 */
public abstract class ConfigurableNavigationHandler extends NavigationHandler {

    /**
     * 
     * Return the {@link NavigationCase} representing the navigation that would be taken had
     * {@link NavigationHandler#handleNavigation} been called with the same arguments or null if there is no
     * such case.
     * 
     *
     * @param context The {@link FacesContext} for the current request
     * @param fromAction The action binding expression that was evaluated to retrieve the specified outcome, or
     * null if the outcome was acquired by some other means
     * @param outcome The logical outcome returned by a previous invoked application action (which may be null)
     * @return the navigation case, or null.
     * @throws NullPointerException if context is null
     * @since 2.0
     */
    public abstract NavigationCase getNavigationCase(FacesContext context, String fromAction, String outcome);

    /**
     * 
     * Return the {@link NavigationCase} representing the navigation that would be taken had
     * {@link NavigationHandler#handleNavigation} been called with the same arguments or null if there is no
     * such case. Implementations that comply the version of the specification in which this method was introduced must
     * override this method. For compatibility with decorated implementations that comply with an earlier version of the
     * specification, an implementation is provided that simply calls through to
     * {@link #getNavigationCase(jakarta.faces.context.FacesContext, java.lang.String, java.lang.String)}, ignoring the
     * {@code toFlowDocumentId} parameter.
     * 
     *
     * @param context The {@link FacesContext} for the current request
     * @param fromAction The action binding expression that was evaluated to retrieve the specified outcome, or
     * null if the outcome was acquired by some other means
     * @param outcome The logical outcome returned by a previous invoked application action (which may be null)
     * @param toFlowDocumentId The value of the toFlowDocumentId property for the navigation case (which may be
     * null)
     * @return the navigation case, or null.
     * @throws NullPointerException if context is null
     * @since 2.2
     */
    public NavigationCase getNavigationCase(FacesContext context, String fromAction, String outcome, String toFlowDocumentId) {
        return getNavigationCase(context, fromAction, outcome);
    }

    /**
     * 
     * Return a Map<String,
     * Set<NavigationCase>> where the keys are <from-view-id> values and the values are
     * Set<NavigationCase> where each element in the Set is a NavigationCase that applies to
     * that <from-view-id>. The implementation must support live modifications to this Map.
     * 
     *
     * @return a map with navigation cases.
     * @since 2.0
     */
    public abstract Map> getNavigationCases();

    /**
     * 
     * A convenience method to signal the Jakarta Faces implementation to perform navigation with the provided
     * outcome. When the NavigationHandler is invoked, the current viewId is treated as the "from viewId" and the "from
     * action" is null.
     * 
     *
     * @param outcome the provided outcome.
     * @throws IllegalStateException if this method is called after this instance has been released
     */
    public void performNavigation(String outcome) {
        this.handleNavigation(FacesContext.getCurrentInstance(), null, outcome);
    }

    /**
     * 
     * Called by the flow system to cause the flow to be inspected for navigation rules. For backward compatibility with
     * earlier implementations, an empty method is provided.
     * 
     *
     * @param context the Faces context.
     * @param flow the flow.
     * @since 2.2
     */
    public void inspectFlow(FacesContext context, Flow flow) {
    }
}