javax.faces.application.StateManager Maven / Gradle / Ivy
Show all versions of jboss-jsf-api_2.0_spec
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 1997-2011 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.faces.application;
import javax.faces.component.NamingContainer;
import javax.faces.component.UIViewRoot;
import javax.faces.context.FacesContext;
import javax.faces.context.ResponseWriter;
import javax.faces.render.RenderKit;
import javax.faces.render.ResponseStateManager;
import java.io.IOException;
/**
* StateManager directs the
* process of saving and
* restoring the view between requests. An
* implementation
* of this class must be thread-safe. The {@link StateManager}
* instance for an application is retrieved from the {@link Application}
* instance, and thus cannot know any details of the markup language
* created by the {@link RenderKit} being used to render a view. The
* {@link StateManager} utilizes a helper object ({@link
* ResponseStateManager}), that is provided by the {@link RenderKit}
* implementation and is therefore aware of the markup language
* details.
*/
public abstract class StateManager {
// ------------------------------------------------------ Manifest Constants
/**
* The ServletContext init parameter consulted by
* the StateManager to tell where the state should be
* saved. Valid values are given as the values of the constants:
* {@link #STATE_SAVING_METHOD_CLIENT} or {@link
* #STATE_SAVING_METHOD_SERVER}.
*
* If this parameter is not specified, the default value is the
* value of the constant {@link #STATE_SAVING_METHOD_CLIENT}.
*/
public static final String STATE_SAVING_METHOD_PARAM_NAME =
"javax.faces.STATE_SAVING_METHOD";
/**
* The ServletContext init
* parameter consulted by the runtime to determine if the partial
* state saving mechanism should be used.
*
* If undefined, the runtime must determine the version level of
* the application.
*
*
* For applications versioned at 1.2 and under, the runtime
* must not use the partial state saving mechanism.
*
For applications versioned at 2.0 and above, the runtime
* must use the partial state saving mechanism.
* If this parameter is defined, and the application is versioned
* at 1.2 and under, the runtime must not use the partial state
* saving mechanism. Otherwise, If this param is defined, and
* calling toLowerCase().equals("true") on a
* String representation of its value returns
* true, the runtime must use partial state mechanism.
* Otherwise the partial state saving mechanism must not be
* used.
*
*
* @since 2.0
*/
public static final String PARTIAL_STATE_SAVING_PARAM_NAME =
"javax.faces.PARTIAL_STATE_SAVING";
/**
* The runtime must interpret the value
* of this parameter as a comma separated list of view IDs, each of
* which must have their state saved using the state saving
* mechanism specified in JSF 1.2.
*/
public static final String FULL_STATE_SAVING_VIEW_IDS_PARAM_NAME =
"javax.faces.FULL_STATE_SAVING_VIEW_IDS";
/**
* Constant value for the initialization parameter named by
* the STATE_SAVING_METHOD_PARAM_NAME that indicates
* state saving should take place on the client.
*/
public static final String STATE_SAVING_METHOD_CLIENT = "client";
/**
* Constant value for the initialization parameter named by
* the STATE_SAVING_METHOD_PARAM_NAME that indicates
* state saving should take place on the server.
*/
public static final String STATE_SAVING_METHOD_SERVER = "server";
// ---------------------------------------------------- State Saving Methods
/**
* Return the tree structure and component state information for the
* view contained in the specified {@link FacesContext} instance as an
* object of type StateManager.SerializedView. If there
* is no state information to be saved, return null
* instead.
*
* Components may opt out of being included in the serialized view
* by setting their transient property to true.
* This must cause the component itself, as well as all of that component's
* children and facets, to be omitted from the saved tree structure
* and component state information.
*
* This method must also enforce the rule that, for components with
* non-null ids, all components that are descendants of the
* same nearest {@link NamingContainer} must have unique identifiers.
*
* @param context {@link FacesContext} for the current request
*
* @throws IllegalStateException if more than one component or
* facet within the same {@link NamingContainer} in this view has
* the same non-null component id
* @deprecated this has been replaced by {@link #saveView}. The
* default implementation calls saveView and inspects the
* return. If the return is an Object [], it casts the
* result to an Object [] wrapping the first and second
* elements in an instance of {@link SerializedView}, which it then
* returns. Otherwise, it return null
*/
public SerializedView saveSerializedView(FacesContext context) {
Object stateObj = saveView(context);
SerializedView result = null;
if (null != stateObj) {
if (stateObj instanceof Object[]) {
Object [] state = (Object[]) stateObj;
if (state.length == 2) {
result = new SerializedView(state[0], state[1]);
}
}
}
return result;
}
/**
* Return an opaque Object containing sufficient
* information for this same instance to restore the state of the
* current {@link UIViewRoot} on a subsequent request. The returned
* object must implement java.io.Serializable. If there
* is no state information to be saved, return null
* instead.
*
* Components may opt out of being included in the serialized view
* by setting their transient property to true.
* This must cause the component itself, as well as all of that component's
* children and facets, to be omitted from the saved tree structure
* and component state information.
*
* This method must also enforce the rule that, for components with
* non-null ids, all components that are descendants of the
* same nearest {@link NamingContainer} must have unique identifiers.
*
* For backwards compatability with existing
* StateManager implementations, the default
* implementation of this method calls {@link #saveSerializedView}
* and creates and returns a two element Object array
* with element zero containing the structure property
* and element one containing the state property of the
* SerializedView.
*
* @param context {@link FacesContext} for the current request
*
* @throws IllegalStateException if more than one component or
* facet within the same {@link NamingContainer} in this view has
* the same non-null component id
* @since 1.2
*/
public Object saveView(FacesContext context) {
SerializedView view = saveSerializedView(context);
Object stateArray[] = {view.getStructure(),
view.getState()};
return stateArray;
}
/**
* Convenience method, which must be called by
* saveSerializedView(), to construct and return a
* Serializable object that represents the structure
* of the entire component tree (including children and facets)
* of this view.
*
* Components may opt-out of being included in the tree structure
* by setting their transient property to true.
* This must cause the component itself, as well as all of that component's
* children and facets, to be omitted from the saved tree structure
* information.
*
* @param context {@link FacesContext} for the current request
*
* @deprecated the distinction between tree structure and component
* state is now an implementation detail. The default
* implementation returns null.
*/
protected Object getTreeStructureToSave(FacesContext context) {
return null;
}
/**
* Convenience method, which must be called by
* saveSerializedView(), to construct and return a
* Serializable object that represents the state of
* all component properties, attributes, and attached objects, for
* the entire component tree (including children and facets)
* of this view.
*
* Components may opt-out of being included in the component state
* by setting their transient property to true.
* This must cause the component itself, as well as all of that component's
* children and facets, to be omitted from the saved component state
* information.
*
* @param context {@link FacesContext} for the current request
*
* @deprecated the distinction between tree structure and component
* state is now an implementation detail. The default
* implementation returns null.
*/
protected Object getComponentStateToSave(FacesContext context) {
return null;
}
/**
* Save the state represented in the specified state
* Object instance, in an implementation dependent
* manner.
*
* This method will typically simply delegate the actual
* writing to the writeState() method of the
* {@link ResponseStateManager} instance provided by the
* {@link RenderKit} being used to render this view. This
* method assumes that the caller has positioned the
* {@link ResponseWriter} at the correct position for the
* saved state to be written.
*
* For backwards compatability with existing
* StateManager implementations, the default
* implementation of this method checks if the argument is an
* instance of Object [] of length greater than or
* equal to two. If so, it creates a SerializedView
* instance with the tree structure coming from element zero and
* the component state coming from element one and calls through to
* {@link
* #writeState(javax.faces.context.FacesContext,javax.faces.application.StateManager.SerializedView)}.
* If not, does nothing.
*
* @param context {@link FacesContext} for the current request
* @param state the Serializable state to be written,
* as returned by {@link #saveSerializedView}
*
* @since 1.2
*/
public void writeState(FacesContext context, Object state)
throws IOException {
if (null != state && state.getClass().isArray() &&
state.getClass().getComponentType().equals(Object.class)) {
Object stateArray[] = (Object[]) state;
if (2 == stateArray.length) {
SerializedView view = new SerializedView(stateArray[0],
stateArray[1]);
writeState(context, view);
}
}
}
/**
* Save the state represented in the specified
* SerializedView isntance, in an implementation
* dependent manner.
*
* This method must consult the context initialization parameter
* named by the symbolic constant
* StateManager.STATE_SAVING_METHOD_PARAM_NAME
* to determine whether state should be saved on the client or the
* server. If not present, client side state saving is assumed.
*
* If the init parameter indicates that client side state
* saving should be used, this method must delegate the actual
* writing to the writeState() method of the
* {@link ResponseStateManager} instance provided by the
* {@link RenderKit} being used to render this view. This
* method assumes that the caller has positioned the
* {@link ResponseWriter} at the correct position for the
* saved state to be written.
*
* @param context {@link FacesContext} for the current request
* @param state the serialized state to be written
*
* @deprecated This method has been replaced by {@link
* #writeState(javax.faces.context.FacesContext,java.lang.Object)}.
* The default implementation calls the non-deprecated variant
* of the method passing an Object [] as the second
* argument, where the first element of the array is the return from
* getStructure() and the second is the return from
* getState() on the argument state.
*
*/
public void writeState(FacesContext context,
SerializedView state) throws IOException {
if (state != null) {
writeState(context, new Object[]{state.getStructure(),
state.getState()});
}
}
// ------------------------------------------------- State Restoring Methods
/**
* Restore the tree structure and the component state of the view
* for the specified viewId, in an implementation dependent
* manner, and return the restored {@link UIViewRoot}. If there is no
* saved state information available for this viewId,
* return null instead.
*
* This method must consult the context initialization parameter
* named by the symbolic constant
* StateManager.STATE_SAVING_METHOD_PARAM_NAME
* to determine whether state should be saved on the client or the
* server. If not present, client side state saving is assumed.
*
* If the init parameter indicates that client side state
* saving should be used, this method must call the
* getTreeStructureToRestore() and (if the previous method
* call returned a non-null value) getComponentStateToRestore()
* methods of the {@link ResponseStateManager} instance provided by the
* {@link RenderKit} responsible for this view.
*
* @param context {@link FacesContext} for the current request
* @param viewId View identifier of the view to be restored
* @param renderKitId the renderKitId used to render this response.
* Must not be null.
*
* @throws IllegalArgumentException if renderKitId
* is null.
*/
public abstract UIViewRoot restoreView(FacesContext context, String viewId,
String renderKitId);
/**
* Convenience method, which must be called by
* restoreView(), to construct and return a {@link UIViewRoot}
* instance (populated with children and facets) representing the
* tree structure of the component tree being restored. If no saved
* state information is available, return null instead.
*
* @param context {@link FacesContext} for the current request
* @param viewId View identifier of the view to be restored
* @param renderKitId the renderKitId used to render this response.
* Must not be null.
*
* @throws IllegalArgumentException if renderKitId
* is null.
* @deprecated the distinction between tree structure and component
* state is now an implementation detail. The default
* implementation returns null.
*/
protected UIViewRoot restoreTreeStructure(FacesContext context,
String viewId,
String renderKitId) {
return null;
}
/**
* Convenience method, which must be called by
* restoreView(), to restore the attributes, properties,
* and attached objects of all components in the restored component tree.
*
*
* @param context {@link FacesContext} for the current request
* @param viewRoot {@link UIViewRoot} returned by a previous call
* to restoreTreeStructure()
* @param renderKitId the renderKitId used to render this response.
* Must not be null.
*
* @throws IllegalArgumentException if renderKitId
* is null.
* @deprecated the distinction between tree structure and component
* state is now an implementation detail. The default
* implementation does nothing.
*/
protected void restoreComponentState(FacesContext context,
UIViewRoot viewRoot,
String renderKitId) {
}
private Boolean savingStateInClient = null;
/**
* @return true if and only if the value of the
* ServletContext init parameter named by the value of
* the constant {@link #STATE_SAVING_METHOD_PARAM_NAME} is equal to
* the value of the constant {@link #STATE_SAVING_METHOD_CLIENT}.
* false otherwise.
*
* @throws NullPointerException if context is
* null.
*/
public boolean isSavingStateInClient(FacesContext context) {
if (null != savingStateInClient) {
return savingStateInClient.booleanValue();
}
savingStateInClient = Boolean.FALSE;
String saveStateParam = context.getExternalContext().
getInitParameter(STATE_SAVING_METHOD_PARAM_NAME);
if (saveStateParam != null &&
saveStateParam.equalsIgnoreCase(STATE_SAVING_METHOD_CLIENT)) {
savingStateInClient = Boolean.TRUE;
}
return savingStateInClient.booleanValue();
}
/**
* Convenience struct for encapsulating tree structure and
* component state. This is necessary to allow the API to be
* flexible enough to work in JSP and non-JSP environments.
*
* @deprecated This class was not marked Serializable
* in the 1.0 version of the spec. It was also not a static inner
* class, so it can't be made to be Serializable.
* Therefore, it is being deprecated in version 1.2 of the spec.
* The replacement is to use an implementation dependent
* Object.
*/
public class SerializedView extends Object {
private Object structure = null;
private Object state = null;
public SerializedView(Object newStructure, Object newState) {
structure = newStructure;
state = newState;
}
public Object getStructure() {
return structure;
}
public Object getState() {
return state;
}
}
/**
*
* Convenience method to return the view state as a String with
* no RenderKit specific markup.
*
* This default implementation of this method will call {@link #saveView(javax.faces.context.FacesContext)}
* and passing the result to and returning the resulting value from
* {@link ResponseStateManager#getViewState(javax.faces.context.FacesContext, Object)}.
*
*
* @param context {@link FacesContext} for the current request
*
* @since 2.0
*/
public String getViewState(FacesContext context) {
Object state = saveView(context);
if (state != null) {
return context.getRenderKit().getResponseStateManager()
.getViewState(context, state);
}
return null;
}
}