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.component;
20
21 import java.io.IOException;
22
23 import javax.faces.context.FacesContext;
24
25 /**
26 * Interface implemented by Components that don't render any content themselves but rather set
27 * up context before asking their children to render themselves. Implementing this interface
28 * enables Renderers for components that contain instances of the FlattenedComponents to
29 * visit each descendant in a flattened view of their children, recursively including any
30 * FlattenedComponent treating all of these descendants as direct children.
31 * <p>
32 * A good indicator that a
33 * component should implement FlattenedComponent is that the component doesn't delegate to a
34 * Renderer, but rather renders itself.
35 *
36 * @see ComponentProcessor
37 * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, UIComponent, Object)
38 * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, Iterable, Object)
39 */
40 public interface FlattenedComponent
41 {
42 /**
43 * Set up the component context, process all of the renderable children of this component,
44 * and the restore the previous context, returning <code>true</code> if any of the children
45 * were processed.
46 * <p>
47 * The context set up and tear down to perform is identical to that which the component
48 * would perform when handling rendering or implementing <code>invokeOnComponent</code>
49 * <p>
50 * To handle actually processing the children, the component will typically delegate to one
51 * of the two <code>UIXComponent.processFlattenedChildren</code> helpers. If the component only
52 * processes a single child, as UIXSwitcher does, it will call the version taking a single child
53 * as the argument. If it processes all of its children as UIXIterator and UIXGroup do, it
54 * will call <code>getChildren</code> and pass the List<UIComponent> to the version accepting
55 * an Iterable<UIComponent>.
56 * <p>
57 * This method should only be called if <code>FlattenedComponent.isFlatteningChildren</code>
58 * returns <code>true</code>. If called when <code>FlattenedComponent.isFlatteningChildren</code>
59 * is <code>false</code> the behavior is undefined and the implementation may throw an
60 * IllegalStateException.
61 * <p>
62 * This method may only be called when the FlattenedComponent is in the correct context
63 * to process itself.
64 * @param context Current FacesContext
65 * @param cpContext ComponentProcesingContext represetning the current child iteration state
66 * @param childProcessor ComponentProcessor to call for each flattened child
67 * @param callbackContext childProcessor-specific context to be passed on each call to the
68 * childProcessor
69 * @return <code>true</code> if this FlattenedComponent actually processed any children
70 * @throws IOException if an error occurs while processing children
71 * @throws IllegalStateException if called when <code>isFlatteningChildren()</code> is
72 * <code>false</code>.
73 * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, UIComponent, Object)
74 * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, Iterable, Object)
75 * @see #isFlatteningChildren
76 */
77 public <S> boolean processFlattenedChildren(
78 FacesContext context,
79 ComponentProcessingContext cpContext,
80 ComponentProcessor<S> childProcessor,
81 S callbackContext) throws IOException;
82
83 /**
84 * Returns <code>true</code> if this FlattenedComponent is currently flattening its children. This
85 * allows a FlattenedComponent instance to flatten or not flatten its children as it sees fit.
86 * <p>
87 * It is illegal to call <code>processFlattenedChildren</code> on a FlattenedComponent that
88 * has returned <code>false</code> from <code>isFlatteningChildren</code>.
89 * @param context FacesContext
90 * @return <code>true</code> if this FlattenedComponent is currently flattening its children
91 * @see #processFlattenedChildren
92 */
93 public boolean isFlatteningChildren(FacesContext context);
94 }