Merge pull request #1943 from jakartaee/issue_1833_unify_NavigationHa…

…ndler_and_ConfigurableNavigationHandler

Fix #1833: unify NavigationHandler and ConfigurableNavigationHandler

api/src/main/java/jakarta/faces/application/ConfigurableNavigationHandler.java

@@ -31,7 +31,9 @@
  * </p>
  *
  * @since 2.0
+ * @deprecated Use {@link NavigationHandler} instead. The methods have been merged.
  */
+@Deprecated(since = "5.0", forRemoval = true)
 public abstract class ConfigurableNavigationHandler extends NavigationHandler {
 
     /**

api/src/main/java/jakarta/faces/application/ConfigurableNavigationHandlerWrapper.java

@@ -37,7 +37,9 @@
  * </p>
  *
  * @since 2.2
+ * @deprecated Use {@link NavigationHandlerWrapper} instead. The methods have been merged.
  */
+@Deprecated(since = "5.0", forRemoval = true)
 public abstract class ConfigurableNavigationHandlerWrapper extends ConfigurableNavigationHandler implements FacesWrapper<ConfigurableNavigationHandler> {
 
     private ConfigurableNavigationHandler wrapped;

api/src/main/java/jakarta/faces/application/NavigationHandler.java

@@ -16,7 +16,11 @@
 
 package jakarta.faces.application;
 
+import java.util.Map;
+import java.util.Set;
+
 import jakarta.faces.context.FacesContext;
+import jakarta.faces.flow.Flow;
 
 /**
  * <p>
@@ -89,4 +93,101 @@ public void handleNavigation(FacesContext context, String fromAction, String out
         this.handleNavigation(context, fromAction, outcome);
     }
 
+    /**
+     * <p class="changed_added_5_0">
+     * Return the {@link NavigationCase} representing the navigation that would be taken had
+     * {@link NavigationHandler#handleNavigation} been called with the same arguments or <code>null</code> if there is no
+     * such case.
+     * </p>
+     * <p>
+     * Historically this method was declared in {@code ConfigurableNavigationHandler} since 2.0.
+     * </p>
+     *
+     * @param context The {@link FacesContext} for the current request
+     * @param fromAction The action binding expression that was evaluated to retrieve the specified outcome, or
+     * <code>null</code> if the outcome was acquired by some other means
+     * @param outcome The logical outcome returned by a previous invoked application action (which may be <code>null</code>)
+     * @return the navigation case, or <code>null</code>.
+     * @throws NullPointerException if <code>context</code> is <code>null</code>
+     * @since 5.0
+     */
+    public abstract NavigationCase getNavigationCase(FacesContext context, String fromAction, String outcome);
+
+    /**
+     * <p class="changed_added_5_0">
+     * Return the {@link NavigationCase} representing the navigation that would be taken had
+     * {@link NavigationHandler#handleNavigation} been called with the same arguments or <code>null</code> 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.
+     * </p>
+     * <p>
+     * Historically this method was declared in {@code ConfigurableNavigationHandler} since 2.2. 
+     * </p>
+     *
+     * @param context The {@link FacesContext} for the current request
+     * @param fromAction The action binding expression that was evaluated to retrieve the specified outcome, or
+     * <code>null</code> if the outcome was acquired by some other means
+     * @param outcome The logical outcome returned by a previous invoked application action (which may be <code>null</code>)
+     * @param toFlowDocumentId The value of the <code>toFlowDocumentId</code> property for the navigation case (which may be
+     * <code>null</code>)
+     * @return the navigation case, or <code>null</code>.
+     * @throws NullPointerException if <code>context</code> is <code>null</code>
+     * @since 5.0
+     */
+    public NavigationCase getNavigationCase(FacesContext context, String fromAction, String outcome, String toFlowDocumentId) {
+        return getNavigationCase(context, fromAction, outcome);
+    }
+
+    /**
+     * <p class="changed_added_5_0">
+     * Return a <code>Map&lt;String,
+     * Set&lt;NavigationCase&gt;&gt;</code> where the keys are <code>&lt;from-view-id&gt;</code> values and the values are
+     * <code>Set&lt;NavigationCase&gt;</code> where each element in the Set is a <code>NavigationCase</code> that applies to
+     * that <code>&lt;from-view-id&gt;</code>. The implementation must support live modifications to this <code>Map</code>.
+     * </p>
+     * <p>
+     * Historically this method was declared in {@code ConfigurableNavigationHandler} since 2.0. 
+     * </p>
+     *
+     * @return a map with navigation cases.
+     * @since 5.0
+     */
+    public abstract Map<String, Set<NavigationCase>> getNavigationCases();
+
+    /**
+     * <p class="changed_added_5_0">
+     * 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.
+     * </p>
+     * <p>
+     * Historically this method was declared in {@code ConfigurableNavigationHandler} since 2.0. 
+     * </p>
+     *
+     * @param outcome the provided outcome.
+     * @throws IllegalStateException if this method is called after this instance has been released
+     * @since 5.0
+     */
+    public void performNavigation(String outcome) {
+        this.handleNavigation(FacesContext.getCurrentInstance(), null, outcome);
+    }
+
+    /**
+     * <p class="changed_added_5_0">
+     * 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.
+     * </p>
+     * <p>
+     * Historically this method was declared in {@code ConfigurableNavigationHandler} since 2.2. 
+     * </p>
+     *
+     * @param context the Faces context.
+     * @param flow the flow.
+     * @since 5.0
+     */
+    public void inspectFlow(FacesContext context, Flow flow) {
+    }
 }

api/src/main/java/jakarta/faces/application/NavigationHandlerWrapper.java

@@ -16,8 +16,12 @@
 
 package jakarta.faces.application;
 
+import java.util.Map;
+import java.util.Set;
+
 import jakarta.faces.FacesWrapper;
 import jakarta.faces.context.FacesContext;
+import jakarta.faces.flow.Flow;
 
 /**
  * <p class="changed_added_2_2">
@@ -74,4 +78,28 @@ public void handleNavigation(FacesContext context, String fromAction, String out
         getWrapped().handleNavigation(context, fromAction, outcome, toFlowDocumentId);
     }
 
+    @Override
+    public NavigationCase getNavigationCase(FacesContext context, String fromAction, String outcome) {
+        return getWrapped().getNavigationCase(context, fromAction, outcome);
+    }
+
+    @Override
+    public Map<String, Set<NavigationCase>> getNavigationCases() {
+        return getWrapped().getNavigationCases();
+    }
+
+    @Override
+    public NavigationCase getNavigationCase(FacesContext context, String fromAction, String outcome, String toFlowDocumentId) {
+        return getWrapped().getNavigationCase(context, fromAction, outcome, toFlowDocumentId);
+    }
+
+    @Override
+    public void performNavigation(String outcome) {
+        getWrapped().performNavigation(outcome);
+    }
+
+    @Override
+    public void inspectFlow(FacesContext context, Flow flow) {
+        getWrapped().inspectFlow(context, flow);
+    }
 }