1   /*
    2    * $Id: StateHolder.java,v 1.17 2007/04/27 22:00:03 ofung Exp $
    3    */
    4   
    5   /*
    6    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    7    * 
    8    * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
    9    * 
   10    * The contents of this file are subject to the terms of either the GNU
   11    * General Public License Version 2 only ("GPL") or the Common Development
   12    * and Distribution License("CDDL") (collectively, the "License").  You
   13    * may not use this file except in compliance with the License. You can obtain
   14    * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
   15    * or glassfish/bootstrap/legal/LICENSE.txt.  See the License for the specific
   16    * language governing permissions and limitations under the License.
   17    * 
   18    * When distributing the software, include this License Header Notice in each
   19    * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
   20    * Sun designates this particular file as subject to the "Classpath" exception
   21    * as provided by Sun in the GPL Version 2 section of the License file that
   22    * accompanied this code.  If applicable, add the following below the License
   23    * Header, with the fields enclosed by brackets [] replaced by your own
   24    * identifying information: "Portions Copyrighted [year]
   25    * [name of copyright owner]"
   26    * 
   27    * Contributor(s):
   28    * 
   29    * If you wish your version of this file to be governed by only the CDDL or
   30    * only the GPL Version 2, indicate your decision by adding "[Contributor]
   31    * elects to include this software in this distribution under the [CDDL or GPL
   32    * Version 2] license."  If you don't indicate a single choice of license, a
   33    * recipient has the option to distribute your version of this file under
   34    * either the CDDL, the GPL Version 2 or to extend the choice of license to
   35    * its licensees as provided above.  However, if you add GPL Version 2 code
   36    * and therefore, elected the GPL Version 2 license, then the option applies
   37    * only if the new code is made subject to such option by the copyright
   38    * holder.
   39    */
   40   
   41   package javax.faces.component;
   42   
   43   import javax.faces.context.FacesContext;
   44   
   45   /**
   46    *
   47    * <p>This interface is implemented by classes that need to save their
   48    * state between requests.</p>
   49    *
   50    * <p>An implementor <strong>must</strong> implement both {@link
   51    * #saveState} and {@link #restoreState} methods in this class, since
   52    * these two methods have a tightly coupled contract between themselves.
   53    * In other words, if there is an ineritance hierarchy, it is not
   54    * permissable to have the {@link #saveState} and {@link #restoreState}
   55    * methods reside at different levels of the hierarchy.</p>
   56    *
   57    * <p>An implementor must have a public no-args constructor.</p>
   58    *
   59    */
   60   
   61   public interface StateHolder {
   62   
   63       /**
   64        * <p> Gets the state of the instance as a
   65        * <code>Serializable</code> Object.<p>
   66        *
   67        * <p>If the class that implements this interface has references to
   68        * instances that implement StateHolder (such as a
   69        * <code>UIComponent</code> with event handlers, validators, etc.)
   70        * this method must call the {@link #saveState} method on all those
   71        * instances as well.  <strong>This method must not save the state
   72        * of children and facets.</strong> That is done via the {@link
   73        * javax.faces.application.StateManager}</p>
   74        *
   75        * <p>This method must not alter the state of the implementing
   76        * object.  In other words, after executing this code:</p>
   77        *
   78        * <code><pre>
   79        * Object state = component.saveState(facesContext);
   80        * </pre></code>
   81        *
   82        * <p><code>component</code> should be the same as before executing
   83        * it.</p>
   84        *
   85        * <p>The return from this method must be <code>Serializable</code></p>
   86        * 
   87        * @throws NullPointerException if <code>context</code> is null
   88        */
   89   
   90       public Object saveState(FacesContext context);
   91   
   92       /**
   93        *
   94        * <p> Perform any processing required to restore the state from the
   95        * entries in the state Object.</p>
   96        *
   97        * <p>If the class that implements this interface has references to
   98        * instances that also implement StateHolder (such as a
   99        * <code>UIComponent</code> with event handlers, validators, etc.)
  100        * this method must call the {@link #restoreState} method on all those
  101        * instances as well. </p>
  102        * 
  103        * @throws NullPointerException if either <code>context</code> or
  104        *  <code>state</code> are <code>null</code>
  105        */
  106   
  107       public void restoreState(FacesContext context, Object state);
  108   
  109       /**
  110        *
  111        * <p>If true, the Object implementing this interface must not
  112        * participate in state saving or restoring.</p>
  113        */
  114   
  115       public boolean isTransient();
  116   
  117       /**
  118        * <p>Denotes whether or not the Object implementing this interface must
  119        * or must not participate in state saving or restoring.</p>
  120        * 
  121        * @param newTransientValue boolean pass <code>true</code> if this Object 
  122        *  will participate in state saving or restoring, otherwise 
  123        *  pass <code>false</code>.
  124        */ 
  125       public void setTransient(boolean newTransientValue);
  126   
  127   }