View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.myfaces.custom.savestate;
20  
21  import javax.faces.component.StateHolder;
22  import javax.faces.component.UIParameter;
23  import javax.faces.context.FacesContext;
24  import javax.faces.el.ValueBinding;
25  
26  /**
27   * Provides the ability to store a model value inside the view's component tree.
28   * <p>
29   * JSF provides three scopes for managed beans and therefore all the model
30   * objects that the managed beans reference:  request, session, application.
31   * However a common requirement is a way for a model object to have a scope
32   * that is tied to the duration of the current view; that is longer than the
33   * request scope but shorter than session scope.
34   * </p> 
35   * <p>
36   * This component simply holds a reference to an arbitrary object (specified
37   * by the value property). Because this object is an ordinary component whose
38   * scope is the current view, the reference to the model automatically has that
39   * same scope.
40   * </p> 
41   * <p>
42   * When the value is an EL expression, then after the view is restored the
43   * recreated target object is stored at the specified location.
44   * </p>
45   * <p>
46   * The object being saved must either:
47   * </p>
48   * <ul>
49   * <li>implement java.io.Serializable, or</li>
50   * <li>implement javax.faces.component.StateHolder and have a default
51   *   constructor.</li>
52   * </ul>
53   * <p>
54   * Note that the saved object can be "chained" from view to view
55   * in order to extend its lifetime from a single view to a sequence
56   * of views if desired. A UISaveState component with an EL expression
57   * such as "#{someBean}" will save the object state after render, and
58   * restore it on postback. If navigation occurs to some other view
59   * and that view has a UISaveState component with the same EL expression
60   * then the object will simply be saved into the new view, thus extending
61   * its lifetime.
62   * </p>
63   * 
64   * @JSFComponent
65   *   name = "t:saveState"
66   *   tagClass = "org.apache.myfaces.custom.savestate.SaveStateTag"
67   * @JSFJspProperty name = "name" returnType = "java.lang.String" tagExcluded = "true"
68   * @author Manfred Geiler (latest modification by $Author: skitching $)
69   * @version $Revision: 673833 $ $Date: 2008-07-03 16:58:05 -0500 (Thu, 03 Jul 2008) $
70   */
71  public class UISaveState
72      extends UIParameter
73  {
74      public Object saveState(FacesContext context)
75      {
76          Object values[] = new Object[3];
77          values[0] = super.saveState(context);
78          Object objectToSave = getValue();
79          if (objectToSave instanceof StateHolder)
80          {
81              values[1] = Boolean.TRUE;
82              values[2] = saveAttachedState(context, objectToSave);
83          }
84          else
85          {
86              values[1] = Boolean.FALSE;
87              values[2] = objectToSave;
88          }
89          return values;
90      }
91  
92      public void restoreState(FacesContext context, Object state)
93      {
94          Object values[] = (Object[])state;
95          super.restoreState(context, values[0]);
96          
97          Object savedObject;
98          Boolean storedObjectIsAStateHolder = (Boolean) values[1];
99          if ( Boolean.TRUE.equals( storedObjectIsAStateHolder ) )
100         {
101             savedObject = restoreAttachedState(context,values[2]);
102         }
103         else
104         {
105             savedObject = values[2];
106         }
107         ValueBinding vb = getValueBinding("value");
108         if (vb != null)
109         {
110             vb.setValue(context, savedObject);
111         }
112     }
113 
114     //------------------ GENERATED CODE BEGIN (do not modify!) --------------------
115 
116     public static final String COMPONENT_TYPE = "org.apache.myfaces.SaveState";
117     public static final String COMPONENT_FAMILY = "javax.faces.Parameter";
118 
119 
120     public UISaveState()
121     {
122     }
123 
124     public String getFamily()
125     {
126         return COMPONENT_FAMILY;
127     }
128 
129 
130     //------------------ GENERATED CODE END ---------------------------------------
131 }