| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| package javax.faces.application; |
| |
| /** |
| * Responsible for storing sufficient information about a component tree so that an identical tree |
| * can later be recreated. |
| * <p> |
| * It is up to the concrete implementation to decide whether to use information from the "view template" |
| * that was used to first create the view, or whether to store sufficient information to enable the |
| * view to be restored without any reference to the original template. However as JSF components have |
| * mutable fields that can be set by code, and affected by user input, at least some state does need |
| * to be kept in order to recreate a previously-existing component tree. |
| * <p> |
| * There are two different options defined by the specification: "client" and "server" state. |
| * <p> |
| * When "client" state is configured, all state information required to create the tree is embedded within |
| * the data rendered to the client. Note that because data received from a remote client must always be |
| * treated as "tainted", care must be taken when using such data. Some StateManager implementations may |
| * use encryption to ensure that clients cannot modify the data, and that the data received on postback |
| * is therefore trustworthy. |
| * <p> |
| * When "server" state is configured, the data is saved somewhere "on the back end", and (at most) a |
| * token is embedded in the data rendered to the user. |
| * <p> |
| * This class is usually invoked by a concrete implementation of ViewHandler. |
| * <p> |
| * Note that class ViewHandler isolates JSF components from the details of the request format. This class |
| * isolates JSF components from the details of the response format. Because request and response are usually |
| * tightly coupled, the StateManager and ViewHandler implementations are also usually fairly tightly coupled |
| * (ie the ViewHandler/StateManager implementations come as pairs). |
| * <p> |
| * See the javadoc for this class in the |
| * <a href="http://java.sun.com/j2ee/javaserverfaces/1.1_01/docs/api/index.html">JSF Specification</a> |
| * for more details. |
| * |
| * @author Manfred Geiler (latest modification by $Author$) |
| * @version $Revision$ $Date$ |
| */ |
| public abstract class StateManager |
| { |
| public static final String STATE_SAVING_METHOD_PARAM_NAME = "javax.faces.STATE_SAVING_METHOD"; |
| public static final String STATE_SAVING_METHOD_CLIENT = "client"; |
| public static final String STATE_SAVING_METHOD_SERVER = "server"; |
| private Boolean _savingStateInClient = null; |
| |
| /** |
| * Invokes getTreeStructureToSave and getComponentStateToSave, then return an object that wraps the two |
| * resulting objects. This object can then be passed to method writeState. |
| */ |
| public abstract StateManager.SerializedView saveSerializedView(javax.faces.context.FacesContext context); |
| |
| /** |
| * Return data that is sufficient to recreate the component tree that is the viewroot of the specified |
| * context, but without restoring the state in the components. |
| * <p> |
| * Using this data, a tree of components which has the same "shape" as the original component |
| * tree can be recreated. However the component instances themselves will have only their default |
| * values, ie their member fields will not have been set to the original values. |
| */ |
| protected abstract Object getTreeStructureToSave(javax.faces.context.FacesContext context); |
| |
| /** |
| * Return data that can be applied to a component tree created using the "getTreeStructureToSave" |
| * method. |
| */ |
| protected abstract Object getComponentStateToSave(javax.faces.context.FacesContext context); |
| |
| /** |
| * Associate the provided state object with the current response being generated. |
| * <p> |
| * When client-side state is enabled, it is expected that method writes the data contained in the |
| * state parameter to the response somehow. |
| * <p> |
| * When server-side state is enabled, at most a "token" is expected to be written. |
| */ |
| public abstract void writeState(javax.faces.context.FacesContext context, |
| StateManager.SerializedView state) |
| throws java.io.IOException; |
| |
| public abstract javax.faces.component.UIViewRoot restoreView(javax.faces.context.FacesContext context, |
| String viewId, |
| String renderKitId); |
| |
| protected abstract javax.faces.component.UIViewRoot restoreTreeStructure(javax.faces.context.FacesContext context, |
| String viewId, |
| String renderKitId); |
| |
| protected abstract void restoreComponentState(javax.faces.context.FacesContext context, |
| javax.faces.component.UIViewRoot viewRoot, |
| String renderKitId); |
| |
| public boolean isSavingStateInClient(javax.faces.context.FacesContext context) |
| { |
| if(context == null) throw new NullPointerException("context"); |
| if (_savingStateInClient != null) return _savingStateInClient.booleanValue(); |
| String stateSavingMethod = context.getExternalContext().getInitParameter(STATE_SAVING_METHOD_PARAM_NAME); |
| if (stateSavingMethod == null) |
| { |
| _savingStateInClient = Boolean.FALSE; //Specs 10.1.3: default server saving |
| context.getExternalContext().log("No state saving method defined, assuming default server state saving"); |
| } |
| else if (stateSavingMethod.equals(STATE_SAVING_METHOD_CLIENT)) |
| { |
| _savingStateInClient = Boolean.TRUE; |
| } |
| else if (stateSavingMethod.equals(STATE_SAVING_METHOD_SERVER)) |
| { |
| _savingStateInClient = Boolean.FALSE; |
| } |
| else |
| { |
| _savingStateInClient = Boolean.FALSE; //Specs 10.1.3: default server saving |
| context.getExternalContext().log("Illegal state saving method '" + stateSavingMethod + "', default server state saving will be used"); |
| } |
| return _savingStateInClient.booleanValue(); |
| } |
| |
| |
| public class SerializedView |
| { |
| private Object _structure; |
| private Object _state; |
| |
| public SerializedView(Object structure, Object state) |
| { |
| _structure = structure; |
| _state = state; |
| } |
| |
| public Object getStructure() |
| { |
| return _structure; |
| } |
| |
| public Object getState() |
| { |
| return _state; |
| } |
| } |
| } |