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.trinidad.context;
20  
21  import java.util.Iterator;
22  
23  import javax.faces.context.FacesContext;
24  
25  
26  /**
27   * Interface that controls access to the stack of component context changes. This class
28   * allows components to push changes onto a stack that must be rolled back in order to perform
29   * an {@link javax.faces.component.UIComponent#invokeOnComponent} or
30   * {@link javax.faces.component.UIComponent#visitTree} call in the proper context.
31   * <p>This functionality allows changes that only should apply when a component is currently
32   * processing its lifecycle to be temporarily suspended. For example, a component that alters
33   * the EL context should undo and changes when the component is not processing. An example of
34   * this is the Trinidad table that injects "var" and "varStatus" variables into the EL context
35   * while the table is iterating. By saving off these variables and restoring them, the EL will
36   * be correct should code perform an invoke on component or visit tree call, reentering the
37   * component tree from the view root.</p>
38   * <p>The changes are automatically suspended during an invoke on component or visit tree
39   * invocation. This work is performed by the trh:head, trh:body and the tr:document components.
40   * Components outside of these components are not restore to the root context.</p>
41   */
42  public abstract class ComponentContextManager
43  {
44    /**
45     * Push a change onto the stack.
46     *
47     * @param change The change to push
48     */
49    public abstract void pushChange(ComponentContextChange change);
50  
51    /**
52     * Remove the latest change from the stack.
53     *
54     * @return the change that has been removed from the stack
55     * @throws IllegalStateException if an attempt is made to pop an empty stack
56     */
57    public abstract ComponentContextChange popChange()
58      throws IllegalStateException;
59  
60    /**
61     * Get the latest change on the stack without removing it.
62     *
63     * @return the latest change or null if none
64     */
65    public abstract ComponentContextChange peekChange();
66  
67    /**
68     * Suspend the entire stack of context changes. Used by the document to clear all changes
69     * during an invoke on component or visit tree call.
70     *
71     * @param facesContext The faces context
72     * @return an object to use to pass back to the {@link #resume} method to resume the suspend
73     * changes at a later time
74     */
75    public abstract SuspendedContextChanges suspend(FacesContext facesContext);
76  
77    /**
78     * Suspend the changes on the stack to an arbitrary point. This method is useful should a
79     * component need to back out changes only to a certain point. For example, a compound
80     * component may need to back out any changes to be able to evaluate EL in the context
81     * of the defining page.
82     *
83     * @param facesContext the faces context
84     * @param callback a callback interface used to determine how far back to suspend.
85     * @return an object to use to pass back to the {@link #resume} method to resume the suspend
86     * changes at a later time
87     */
88    public abstract SuspendedContextChanges partialSuspend(
89      FacesContext    facesContext,
90      SuspendCallback callback);
91  
92    /**
93     * Resume a set of suspended changes.
94     *
95     * @param facesContext the faces context
96     * @param suspendedChanges a set of changes that have been previously suspended
97     * @return Iterator of changes that were resumed
98     * during the call (iterates in the earliest to most recent order).
99     */
100   public abstract Iterator<ComponentContextChange> resume(
101     FacesContext            facesContext,
102     SuspendedContextChanges suspendedChanges);
103 }