org.apache.myfaces.trinidad.component.FlattenedComponent Maven / Gradle / Ivy

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.myfaces.trinidad.component;

import java.io.IOException;

import javax.faces.context.FacesContext;

/**
 * Interface implemented by Components that don't render any content themselves but rather set
 * up context before asking their children to render themselves.  Implementing this interface
 * enables Renderers for components that contain instances of the FlattenedComponents to
 * visit each descendant in  a flattened view of their children, recursively including any
 * FlattenedComponent treating all of these descendants as direct children.
 * 
 * A good indicator that a
 * component should implement FlattenedComponent is that the component doesn't delegate to a
 * Renderer, but rather renders itself.
 * 
 * @see ComponentProcessor
 * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, UIComponent, Object)
 * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, Iterable, Object)
 */
public interface FlattenedComponent
{
  /**
   * Set up the component context, process all of the renderable children of this component,
   * and the restore the previous context, returning true if any of the children
   * were processed.
   * 

   * The context set up and tear down to perform is identical to that which the component
   * would perform when handling rendering or implementing invokeOnComponent
   * 

   * To handle actually processing the children, the component will typically delegate to one
   * of the two UIXComponent.processFlattenedChildren helpers.  If the component only
   * processes a single child, as UIXSwitcher does, it will call the version taking a single child
   * as the argument.  If it processes all of its children as UIXIterator and UIXGroup do, it
   * will call getChildren and pass the List<UIComponent> to the version accepting
   * an Iterable<UIComponent>.
   * 

   * This method should only be called if FlattenedComponent.isFlatteningChildren
   * returns true.  If called when FlattenedComponent.isFlatteningChildren
   * is false the behavior is undefined and the implementation may throw an
   * IllegalStateException.
   * 

   * This method may only be called when the FlattenedComponent is in the correct context
   * to process itself.
   * @param context Current FacesContext
   * @param cpContext ComponentProcesingContext represetning the current child iteration state
   * @param childProcessor ComponentProcessor to call for each flattened child
   * @param callbackContext childProcessor-specific context to be passed on each call to the
   * childProcessor
   * @return true if this FlattenedComponent actually processed any children
   * @throws IOException if an error occurs while processing children
   * @throws IllegalStateException if called when isFlatteningChildren() is
   * false.
   * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, UIComponent, Object)
   * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, Iterable, Object)
   * @see #isFlatteningChildren
   */  
  public  boolean processFlattenedChildren(
   FacesContext context,
   ComponentProcessingContext cpContext,
   ComponentProcessor childProcessor,
   S callbackContext) throws IOException;

  /**
   * Returns true if this FlattenedComponent is currently flattening its children. This
   * allows a FlattenedComponent instance to flatten or not flatten its children as it sees fit.
   * 
   * It is illegal to call processFlattenedChildren on a FlattenedComponent that
   * has returned false from isFlatteningChildren.
   * @param context FacesContext
   * @return true if this FlattenedComponent is currently flattening its children
   * @see #processFlattenedChildren
   */  
  public boolean isFlatteningChildren(FacesContext context);
}