/*
    * 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;
  
  
  import org.apache.myfaces.buildtools.maven2.plugin.builder.annotation.JSFWebConfigParam;
  
  import java.io.IOException;
  
  import javax.faces.component.UIViewRoot;
  import javax.faces.context.FacesContext;
  
  /**
   * 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 also the <a href="http://java.sun.com/javaee/javaserverfaces/1.2/docs/api/index.html">JSF Specification</a>
   */
  public abstract class StateManager
  {
      /**
       * Define the state method to be used. 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>
       * <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>
       */
      @JSFWebConfigParam(defaultValue="server", expectedValues="server,client",
              since="1.1", group="state", tags="performance", ignoreUpperLowerCase = true,
              desc="Define the state method to be used. There are two different options "
                   + "defined by the specification: 'client' and 'server' state.")
      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";
      
      /**
       * Indicate the viewId(s) separated by commas that should be saved and restored fully,
       * without use Partial State Saving (PSS).
       */
      @JSFWebConfigParam(since="2.0", group="state")
      public static final String FULL_STATE_SAVING_VIEW_IDS_PARAM_NAME = "javax.faces.FULL_STATE_SAVING_VIEW_IDS";
      
      /**
       * Enable or disable partial state saving algorithm.
       *  
       * <p>Partial State Saving algorithm allows to reduce the size of the state required to save a view, 
       * keeping track of the "delta" or differences between the view build by first time and the current 
       * state of the view.</p>
       * <p>If the webapp faces-config file version is 2.0 or upper the default value is true, otherwise is false.</p>   
       */
      @JSFWebConfigParam(expectedValues="true,false", since="2.0", defaultValue="true (false with 1.2 webapps)",
                         tags="performance", group="state")
     public static final String PARTIAL_STATE_SAVING_PARAM_NAME = "javax.faces.PARTIAL_STATE_SAVING";
     private Boolean _savingStateInClient = null;
 
     public static final String IS_BUILDING_INITIAL_STATE = "javax.faces.IS_BUILDING_INITIAL_STATE";
     
     public static final String IS_SAVING_STATE = "javax.faces.IS_SAVING_STATE";
 
     /**
      * Indicate if the state should be serialized before save it on the session.
      * <p>
      * Only applicable if state saving method is "server" (= default).
      * If <code>true</code> (default) the state will be serialized to a byte stream before it is
      * written to the session.
      * If <code>false</code> the state will not be serialized to a byte stream.
      * </p>
      */
     @JSFWebConfigParam(since="2.2", group="state", tags="performance", 
             defaultValue="false", expectedValues="true,false")
     public static final java.lang.String SERIALIZE_SERVER_STATE_PARAM_NAME = "javax.faces.SERIALIZE_SERVER_STATE";
     
     /**
      * Invokes getTreeStructureToSave and getComponentStateToSave, then return an object that wraps the two resulting
      * objects. This object can then be passed to method writeState.
      * <p>
      * Deprecated; use saveView instead.
      * 
      * @deprecated
      */
     public StateManager.SerializedView saveSerializedView(FacesContext context)
     {
         Object savedView = saveView(context);
         if (savedView != null && savedView instanceof Object[])
         {
             Object[] structureAndState = (Object[]) savedView;
             if (structureAndState.length == 2)
             {
                 return new StateManager.SerializedView(structureAndState[0], structureAndState[1]);
             }
         }
         
         return null;
     }
 
     /**
      * Returns an object that is sufficient to recreate the component tree that is the viewroot of the specified
      * context.
      * <p>
      * The return value is suitable for passing to method writeState.
      * 
      * @since 1.2
      */
     @Deprecated
     public Object saveView(FacesContext context)
     {
         StateManager.SerializedView serializedView = saveSerializedView(context);
         if (serializedView == null)
         {
             return null;
         }
 
         Object[] structureAndState = new Object[2];
         structureAndState[0] = serializedView.getStructure();
         structureAndState[1] = serializedView.getState();
 
         return structureAndState;
     }
 
     /**
      * 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.
      * <p>
      * Deprecated; use saveView instead.
      * 
      * @deprecated
      */
     protected Object getTreeStructureToSave(FacesContext context)
     {
         return null;
     }
 
     /**
      * Return data that can be applied to a component tree created using the "getTreeStructureToSave" method.
      * <p>
      * Deprecated; use saveView instead.
      * 
      * @deprecated
      */
     protected Object getComponentStateToSave(FacesContext context)
     {
         return null;
     }
 
     /**
      * 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.
      * <p>
      * Deprecated; use writeState(FacesContext, Object) instead. This method was abstract in JSF1.1, but is now an empty
      * non-abstract method so that old classes that implement this method continue to work, while new classes can just
      * override the new writeState method rather than this one.
      * 
      * @throws IOException
      *             never
      * 
      * @deprecated
      */
     public void writeState(FacesContext context, StateManager.SerializedView state)
         throws IOException
     {
         if (state != null)
         {
             writeState(context, new Object[]{state.getStructure(), state.getState()});
         }
     }
 
     /**
      * 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.
      * <p>
      * This method should be overridden by subclasses. It is not abstract because a default implementation is provided
      * that forwards to the old writeState method; this allows subclasses of StateManager written using the JSF1.1 API
      * to continue to work.
      * <p>
      * 
      * @since 1.2
      */
     public void writeState(FacesContext context, Object state) throws IOException
     {
         if (!(state instanceof Object[]))
         {
             return;
         }
         Object[] structureAndState = (Object[]) state;
         if (structureAndState.length < 2)
         {
             return;
         }
 
         writeState(context, new StateManager.SerializedView(structureAndState[0], structureAndState[1]));
     }
     
     /**
      * TODO: This method should be called from somewhere when ajax response is created to update the state saving param
      * on client. The place where this method is called is an implementation detail, so there is no references about
      * from where in the spec javadoc. 
      * 
      * @since 2.0
      * @param context
      * @return
      */
     public String getViewState(FacesContext context)
     {
         return context.getRenderKit().getResponseStateManager().getViewState(context, saveView(context));
     }
 
     @Deprecated
     public abstract UIViewRoot restoreView(FacesContext context, String viewId, String renderKitId);
 
     /**
      * @deprecated
      */
     protected UIViewRoot restoreTreeStructure(FacesContext context, String viewId, String renderKitId)
     {
         return null;
     }
 
     /**
      * @deprecated
      */
     protected void restoreComponentState(FacesContext context, UIViewRoot viewRoot, String renderKitId)
     {
         // default impl does nothing as per JSF 1.2 javadoc
     }
 
     public boolean isSavingStateInClient(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.equalsIgnoreCase(STATE_SAVING_METHOD_CLIENT))
         {
             _savingStateInClient = Boolean.TRUE;
         }
         else if (stateSavingMethod.equalsIgnoreCase(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();
     }
 
     /**
      * @deprecated
      */
     public class SerializedView
     {
         private Object _structure;
         private Object _state;
 
         /**
          * @deprecated
          */
         public SerializedView(Object structure, Object state)
         {
             _structure = structure;
             _state = state;
         }
 
         /**
          * @deprecated
          */
         public Object getStructure()
         {
             return _structure;
         }
 
         /**
          * @deprecated
          */
         public Object getState()
         {
             return _state;
         }
     }
 }