jakarta.faces.view.StateManagementStrategy Maven / Gradle / Ivy

Go to download
/*
 * Copyright (c) 1997, 2021 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.view;

import jakarta.faces.component.UIViewRoot;
import jakarta.faces.context.FacesContext;

/**
 * 
 * Encapsulate the saving and restoring of the view to enable the VDL to take
 * over the responsibility for handling this feature.
 * 
 *
 * 
 * Implementations must call {@link jakarta.faces.component.UIComponent#visitTree} on the
 * {@link jakarta.faces.component.UIViewRoot} to perform the saving and restoring of the view in the {@link #saveView}
 * and {@link #restoreView} methods, respectively.
 * 
 *
 * @since 2.0
 */
public abstract class StateManagementStrategy {

    /**
     * 
     * Return the state of the current view in an Object that
     * implements Serializable and can be passed to
     * java.io.ObjectOutputStream.writeObject() without causing a java.io.NotSerializableException
     * to be thrown. The default implementation must perform the following algorithm or its semantic equivalent,
     * explicitly performing all the steps listed here.
     * 
     *
     * 
     *
     * 
     *
     * 
     * 
     * If the UIViewRoot of the current view is marked transient, return null
     * immediately.
     * 
     * 
     *
     * 
     * 
     * Traverse the view and verify that each of the client ids are unique. Throw IllegalStateException if more
     * than one client id are the same.
     * 
     * 
     *
     * 
     * 
     * Visit the tree using {@link jakarta.faces.component.UIComponent#visitTree}. For each node, call
     * {@link jakarta.faces.component.UIComponent#saveState}, saving the returned Object in a way such that it
     * can be restored given only its client id. Special care must be taken to handle the case of components that were added
     * or deleted programmatically during this lifecycle traversal, rather than by the VDL.
     * 
     * 
     *
     * 
     *
     * 
     * The implementation must ensure that the {@link jakarta.faces.component.UIComponent#saveState} method is called for
     * each node in the tree.
     * 
     *
     * 
     * The data structure used to save the state obtained by executing the above algorithm must be
     * Serializable, and all of the elements within the data structure must also be Serializable.
     * 
     *
     * 
     *
     * @param context the FacesContext for this request.
     *
     * @since 2.0
     *
     * @return the saved view state
     */
    public abstract Object saveView(FacesContext context);

    /**
     * 
     * Restore the state of the view with information in the request. The default
     * implementation must perform the following algorithm or its semantic equivalent.
     * 
     *
     * 
     *
     * 
     *
     * 
     *
     * 
     * As in the case of restore view on an initial request, the view metadata must be restored and properly handled as
     * well. Obtain the {@link ViewMetadata} for the current viewId, and from that call
     * {@link ViewMetadata#createMetadataView}. Store the resultant {@link UIViewRoot} in the {@link FacesContext}. Obtain
     * the state of the UIViewRoot from the state Object returned from
     * {@link jakarta.faces.render.ResponseStateManager#getState} and pass that to {@link UIViewRoot#restoreViewScopeState}.
     * 
     *
     *
     * 
     * Build the view from the markup. For all components in the view that do not have an explicitly assigned id in the
     * markup, the values of those ids must be the same as on an initial request for this view. This view will not contain
     * any components programmatically added during the previous lifecycle run, and it will contain components that
     * were programmatically deleted on the previous lifecycle run. Both of these cases must be handled.
     * 
     *
     *
     * 
     *
     * 
     * 
     * Call {@link jakarta.faces.render.ResponseStateManager#getState} to obtain the data structure returned from the
     * previous call to {@link #saveView}.
     * 
     * 
     *
     * 
     * 
     * Visit the tree using {@link jakarta.faces.component.UIComponent#visitTree}. For each node, call
     * {@link jakarta.faces.component.UIComponent#restoreState}, passing the state saved corresponding to the current client
     * id.
     * 
     * 
     *
     * 
     * 
     * Ensure that any programmatically deleted components are removed.
     * 
     * 
     *
     * 
     * 
     * Ensure any programmatically added components are added.
     * 
     * 
     *
     * 
     *
     * 
     * The implementation must ensure that the {@link jakarta.faces.component.UIComponent#restoreState} method is called for
     * each node in the tree, except for those that were programmatically deleted on the previous run through the lifecycle.
     * 
     *
     * 
     *
     * @param context the FacesContext for this request
     *
     * @param viewId the view identifier for which the state should be restored
     *
     * @param renderKitId the render kit id for this state.
     *
     * @since 2.0
     *
     * @return the root of the restored view
     */
    public abstract UIViewRoot restoreView(FacesContext context, String viewId, String renderKitId);

}