jakarta.faces.view.StateManagementStrategy Maven / Gradle / Ivy
Show all versions of jakarta.faces-api Show documentation
/*
* 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.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. Because {@link ViewDeclarationLanguage#getStateManagementStrategy}
* is required to return null for Jakarta Server Pages views and non-null for views authored
* in Facelets for Jakarta Server Faces 2, this specification only applies to Facelets for Jakarta Server Faces 2.
*
*
*
* 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);
}