/*
    * 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.Map;
  
  import javax.el.ELContext;
  import javax.faces.FacesException;
  import javax.faces.component.UIComponentBase;
  import javax.faces.context.FacesContext;
  import javax.faces.render.Renderer;
  
  import org.apache.commons.logging.Log;
  import org.apache.commons.logging.LogFactory;
  import org.apache.myfaces.orchestra.flow.config.FlowCall;
  import org.apache.myfaces.orchestra.flow.config.FlowConfig;
  import org.apache.myfaces.orchestra.flow.digest.FlowDigester;
  import org.apache.myfaces.orchestra.flow.utils._ExpressionFactory;
  import org.apache.myfaces.orchestra.lib.OrchestraException;
  
  /**
   * A component which allows the configuration for a flow-call to be defined in the page
   * rather than in a separate flow.xml file.
   * <p>
   * A page can contain zero or more of these tags. It is recommended that all flowCall tags be
   * placed at the top of the view definition file (eg immediately after the f:view) so that
   * the flows can clearly be seen at a glance. However placing tags next to the command
   * components that can be used to trigger the associated outcome is also reasonable.
   * <p>
   * Defining flow-calls via tags is particularly useful when the component that triggers the
   * call is in a "view fragment" that is included into other pages via jsp:include or facelets
   * templating. In that case, defining the flow call configuration in a separate file that is
   * associated with the *including* view is ugly, and an in-page tag is preferable.
   * <p>
   * This must be a component (rather than just being implemented in a JSP tag) because the
   * flowcall information must be available at the end of the postback phase when navigation
   * occurs. The render phase has not run, so no JSF tags have executed; the view tree
   * consists just of objects recreated from the saved state. Therefore the flowcall info
   * must be held by a component that is recreated during RESTORE_VIEW.
   * <p>
   * It would not be good to re-parse the nested text on each postback; that would be very
   * inefficient. Therefore we parse it just once and store the (serializable) FlowCall
   * object as a member. This does mean that if the nested text changes then this will be
   * ignored until the view is recreated, but it is not expected that the flow config data
   * will be dynamic. In fact, that would be quite insane.
   */
  
  public class FlowCallComponent extends UIComponentBase
  {
      public static final String COMPONENT_FAMILY = "javax.faces.Component";
      public static final String COMPONENT_TYPE = "org.apache.myfaces.orchestra.flow.components.FlowCall";
  
      // This must not be transient; it is needed during postback
      private FlowCall flowCall;
  
      private transient String outcome;
      private transient String viewId;
      private transient String service;
  
      @Override
      public String getFamily()
      {
          return COMPONENT_FAMILY;
      }
  
      public boolean isInitialized()
      {
          return flowCall != null;
      }
  
      public void setOutcome(String outcome)
      {
          this.outcome = outcome;
      }
  
      public void setViewId(String viewId)
      {
          this.viewId = viewId;
      }
  
      public void setService(String service)
     {
         this.service = service;
     }
 
     public void setBody(ELContext elContext, String content)
     {
         if (flowCall != null)
         {
             // already parsed once, just ignore
             return;
         }
 
         if (content == null)
         {
             throw new FacesException("Empty flowCall tag");
         }
 
         try
         {
             // Parse the plain xml that is nested within this component.
             //
             // Note that it is important that any EL expressions within this text content be converted into
             // real EL-expression objects immediately, rather than simply being stored as strings and the
             // EL expression objects being created later when needed. The reason is that during the building
             // of the component tree, the "current expression context" may be modified. Creating an EL
             // expression captures the current state of the "expression context" so that when the EL expression
             // is later executed it runs with the appropriate environment. In particular, the Facelets
             // ui:include tag can include ui:param tags that expose data to the nested components, effectively
             // mapping a name to another EL expression during the build-tree phase (note: the param-expression
             // is not *evaluated*; the name maps to the expression itself, not its value). When the included page
             // creates EL objects, they internally remember the current mappings. During rendering, the ui:param
             // settings are *not* restored; rendering simply walks the tree of components and a ui:include is not
             // a component. However the EL expression objects have enough info to recreate the ui:param settings
             // that existed when the EL expression was created, so setValue and getValue work ok.
             //
             // Of course, the above only applies when running in an environment that supports javax.el (ie JSF1.2
             // or JSF1.1 with Facelets). For JSF1.1 with JSP, this is not relevant; there is no standard support
             // for passing "parameters" to included files. There is one non-standard way: the Tomahawk t:aliasBean
             // tag. I don't know how that works with respect to orchestra flow....
             flowCall = new FlowCall();
             flowCall.setOutcome(outcome);
             flowCall.setViewId(viewId);
             flowCall.setService(service);
 
             _ExpressionFactory.pushContext(elContext);
             try
             {
                 FlowDigester.digestFlowCall(flowCall, content);
             }
             finally
             {
                 _ExpressionFactory.popContext(elContext);
             }
 
             flowCall.validate();
         }
         catch(OrchestraException e)
         {
             String msg = "Invalid flowCall declaration for component " + this.getId() + ":" + content;
             Log log = LogFactory.getLog(FlowCallComponent.class);
             log.warn(msg, e);
             throw new FacesException(msg, e);
         }
     }
 
     // ================ State Methods =================
 
     @Override
     public void restoreState(FacesContext context, Object state)
     throws FacesException
     {
         Object[] states = (Object[]) state;
         super.restoreState(context, states[0]);
         flowCall = (FlowCall) states[1];
 
         getFlowConfigForRequest(context).addFlowCall(flowCall);
     }
 
     @Override
     public Object saveState(FacesContext context)
     {
         return new Object[]
         {
             super.saveState(context),
             flowCall
         };
     }
 
     // ================ Renderer Methods =================
     
     @Override
     protected Renderer getRenderer(FacesContext context)
     {
         return null;
     }
 
     /**
      * Return true so that method encodeChildren gets called.
      */
     @Override
     public boolean getRendersChildren()
     {
         return true;
     }
 
     /**
      * Suppress rendering of children.
      * <p>
      * We don't expect there to ever be children here. However it's best to be sure...
      */
     @Override
     public void encodeChildren(FacesContext context)
     throws IOException
     {
         int nChildren = getChildCount();
         if (nChildren > 0)
         {
             Log log = LogFactory.getLog(FlowCallComponent.class);
             log.warn("encodeChildren: child count is " + nChildren);
         }
         // ignore all children
     }
     
     // ================ Static Methods =================
     
     private static FlowConfig getFlowConfigForRequest(FacesContext facesContext)
     {
         Map<String, Object> reqMap = facesContext.getExternalContext().getRequestMap();
         FlowConfig flowConfig = (FlowConfig) reqMap.get(FlowConfig.CONFIG_KEY);
         if (flowConfig == null)
         {
             flowConfig = new FlowConfig();
             reqMap.put(FlowConfig.CONFIG_KEY, flowConfig);
         }
         return flowConfig;
     }
 }