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.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&lt;UIComponent> to the version accepting
55     * an Iterable&lt;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  }