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 }