/*
    * 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.orchestra.flow.components;
  
  import java.io.IOException;
  import java.util.Iterator;
  
  import javax.el.ELException;
  import javax.faces.FacesException;
  import javax.faces.component.UIComponent;
  
  import com.sun.facelets.FaceletContext;
  import com.sun.facelets.tag.TextHandler;
  import com.sun.facelets.tag.jsf.ComponentConfig;
  import com.sun.facelets.tag.jsf.ComponentHandler;
  
  /**
   * Facelets component-handler which creates a FlowCallComponent instance.
   * <p>
   * Note that a facelets ComponentHandler is a subclass of TagHandler. The methods in TagHandler
   * are "tag oriented", ie focused on handling a tree of tags. The methods in a ComponentHandler
   * are "higher level", ie the callbacks are focused on component creation and configuration.
   * <p>
   * Facelets first parses the input into a syntax tree (of Facelets Instruction nodes) and caches
   * it (for later use). It then walks the tree, invoking the appropriate tag or component handler.
   * Each ComponentHandler has access to the list of nodes nested within it via the "nextHandler"
   * member.
   */
  public class FlowCallComponentHandler extends ComponentHandler
  {
      public FlowCallComponentHandler(ComponentConfig config)
      {
          super(config);
      }
  
      /**
       * When Facelets encounters the start tag for this component, it will create the component and assign any
       * attributes. It then calls this method.
       * <p>
       * Here we ask the nodes nested within this element to return their text. Then the nested text is passed
       * to the new component. This has the same effect as a JSP tag overriding "doAfterBody", but is pull-style
       * rather than waiting for a callback to occur. Note, however that the body of this element *has* already
       * been parsed into instruction nodes; there appears to be no way to stop Facelets doing this.
       * <p>
       * Note that even though we process the body text explicitly here, facelets will try to process the nested
       * Instruction nodes after this method has returned. Therefore the applyNextHandler method is overridden
       * to prevent that.
       */
      @Override
      protected void onComponentCreated(FaceletContext ctx, UIComponent c, UIComponent parent)
      {
          StringBuffer content = new StringBuffer();
  
          // Method findNextByType will scan the list of child "nodes" for the "StartElementInstruction" node
          // that triggered the call to this method. We actually expect just one node (of type Instruction)
          // which implements the TextHandler interface. It will internally have broken down the XML content
          // of the flowCall element into separate nodes for the xml elements, attributes and body-text.
          // However we don't need to know that; just calling getText on that top-level child will cause
          // it to append together the text representations of all the child elements and return the complete
          // string.
          //
          // The loop is just in case there are multiple child Instruction objects for some reason; this is
          // not expected. The iterator always stops (hasNext is false) when there are no more child nodes
          // for this flowCall element.
          content.append("<flowCall>\n");
          Iterator<?> iter = findNextByType(TextHandler.class);
          while (iter.hasNext())
          {
              TextHandler text = (TextHandler) iter.next();
  
              // Fetch the text without evaluating any EL expressions.
              // Note that text.getText(ctx) *would* evaluate EL expressions
              String textBlock = text.getText();
  
              content.append(textBlock);
          }
          content.append("</flowCall>");
  
          ((FlowCallComponent) c).setBody(ctx, content.toString());
      }
      
      @Override
     protected void onComponentPopulated(FaceletContext ctx, UIComponent c, UIComponent parent)
     {
         // do nothing
     }
 
     @Override
     protected void applyNextHandler(FaceletContext ctx, UIComponent c) 
             throws IOException, FacesException, ELException
     {
         // Do nothing.
         //
         // This method is called by the Facelets framework immediately after onComponentCreated
         // is called.
         //
         // The normal behaviour is to call this.nextHandler.apply(ctx, c) in order to iterate over
         // the child instructions of this element and process them. But we don't want this as out
         // onComponentCreated method has already extracted all of the data we wanted. Without
         // this override, transient text children would be added to component "c".
         //
         // It would be better if we could tell Facelets to not create Instruction nodes for the
         // nested content of this element at all; then it would not be necessary to override
         // this method as there *would* be no nested Instruction nodes. But I haven't figured
         // out how to do that. Facelets is of course driven by a normal XML parser that will
         // always break down the input into SAX events anyway... 
     }
 }