/*
    * 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;
  
  import java.io.IOException;
  import java.io.InputStream;
  import java.util.ArrayList;
  import java.util.List;
  import java.util.Map;
  
  import javax.faces.FacesException;
  import javax.faces.application.ViewHandler;
  import javax.faces.component.UIViewRoot;
  import javax.faces.context.ExternalContext;
  import javax.faces.context.FacesContext;
  import javax.faces.event.PhaseId;
  import javax.servlet.http.HttpServletResponse;
  
  import org.apache.commons.lang.StringUtils;
  import org.apache.commons.logging.Log;
  import org.apache.commons.logging.LogFactory;
  import org.apache.myfaces.orchestra.conversation.ConversationContext;
  import org.apache.myfaces.orchestra.conversation.ConversationManager;
  import org.apache.myfaces.orchestra.flow.components.ClearOnCommit;
  import org.apache.myfaces.orchestra.flow.components.ModalFlow;
  import org.apache.myfaces.orchestra.flow.config.FlowAccept;
  import org.apache.myfaces.orchestra.flow.config.FlowCall;
  import org.apache.myfaces.orchestra.flow.config.FlowConfig;
  import org.apache.myfaces.orchestra.flow.config.FlowOnCommit;
  import org.apache.myfaces.orchestra.flow.config.FlowParamAccept;
  import org.apache.myfaces.orchestra.flow.config.FlowParamSend;
  import org.apache.myfaces.orchestra.flow.config.FlowReturnAccept;
  import org.apache.myfaces.orchestra.flow.config.FlowReturnSend;
  import org.apache.myfaces.orchestra.flow.digest.FlowDigester;
  import org.apache.myfaces.orchestra.lib.OrchestraException;
  import org.xml.sax.InputSource;
  
  /**
   * Common logic for managing orchestra flows, called from both FlowNavigationHandler
   * and FlowViewHandler.
   */
  public class FlowHandler
  {
      private static final Log log = LogFactory.getLog(FlowHandler.class);
      private static final String VIEW_TO_RESTORE_KEY = FlowHandler.class.getName() + ":viewToRestore";
  
      /**
       * Return the FlowCall object associated with the current conversation
       * context (if any).
       * <p>
       * There will be one if the current context was created by some page
       * doing a "call" to a flow.
       * <p>
       * Returns null if there is no FlowCall object in the current conversation
       * context.
       */
      static FlowCall getFlowCall(FacesContext facesContext, UIViewRoot viewRoot, String outcome)
      {
          if (viewRoot == null)
          {
              return null;
          }
  
          String viewId = viewRoot.getViewId();
          FlowConfig config = getFlowConfig(facesContext, viewId);
          if (config == null)
          {
              log.debug("No flowcall for " + viewId);
              return null;
          }
  
          FlowCall fc = config.getFlowCall(outcome);
          log.debug("Flowcall for " + viewRoot.getViewId() + " outcome: " + outcome + " is " + String.valueOf(fc));
          return fc;
      }
  
      /**
       * Return the FlowAccept object associated with the current conversation
       * context (if any).
       * <p>
       * There will be one if the current context was created by some page
       * doing a "call" to a flow, AND the flow call initialisation has
       * completed. 
      */
     static FlowAccept getFlowAccept(FacesContext facesContext, FlowInfo flowInfo, String viewId)
     {
         if ((flowInfo != null) && (flowInfo.getFlowAccept() != null))
         {
             // ok, we are already within a configured flow.
             return flowInfo.getFlowAccept();
         }
 
         FlowConfig config = getFlowConfig(facesContext, viewId);
         if (config == null)
         {
             if (log.isDebugEnabled())
             {
                 log.debug("No flowaccept for " + viewId);
             }
             return null;
         }
 
         FlowAccept fa = config.getFlowAccept();
         if (log.isDebugEnabled())
         {
             log.debug("FlowAccept for " + viewId + " is " + String.valueOf(fa));
         }
         return fa;
     }
 
 
     /**
      * Tell the browser to fetch the specified viewId.
      * <p>
      * For a non-modal flow, this simply sends an http redirect to the appropriate url.
      * <p>
      * For a modal flow, we render some javascript that closes the current modal popup window
      * and tells the parent window to load the appropriate url. Sending a redirect won't work
      * as that will load the view into the modal window/frame instead. 
      */
     private static void redirectTo(FacesContext facesContext, String viewId, FlowInfo flowInfo)
     {
         ExternalContext ec = facesContext.getExternalContext();
         ViewHandler viewHandler = facesContext.getApplication().getViewHandler();
         String url = viewHandler.getActionURL(facesContext, viewId);
         url = ec.encodeActionURL(url);
         
         if (!flowInfo.isModalFlow())
         {
             try
             {
                 ec.redirect(url);
                 return;
             }
             catch(IOException ioe)
             {
                 throw new FacesException("Unable to redirect to " + viewId, ioe);
             }
         }
         
         // Ok, we are closing a modal flow. We therefore need to render some javascript that
         // will close the modal window and force the parent window to fetch the appropriate url.
         //
         // Note that we cannot allow navigation to occur then send the redirect in the createView
         // method because we would need a valid outcome to return here; without that the NavigationHandler
         // just does a "null" navigation, ie returns the current UIViewRoot and never calls the ViewHandler
         // object.
         //
         // And we cannot re-render the popup window because that would need the child context to be
         // active in order to work in all cases (though re-rendering the popup window after the postback
         // that closes it might itself cause problems eg reuse of committed persistent objects). But
         // if we need the child context in order to render the child view, then when do we destroy it?
         //
         // So here we do a truly ugly hack: send some raw html to the response stream right here.
         // The major problem here is that this assumes an HTML renderkit. Well, actually the below
         // is also valid XHTML too..
         // 
         // TODO: some modal dialog libraries (eg myfaces sandbox s:modalDialog) provide a "cancel button"
         // that closes the modal dialog. If this is done then the webapp will work but the child context
         // will not get deleted. Eventually the conversationContext-timeout will remove it but that could
         // be 30 minutes or more. One option could be to always delete all child contexts whenever a
         // request for a context is received. That doesn't work when multiple windows have the same
         // conversationContext id, but that is broken for other reasons anyway (eg access-scope).
 
         StringBuffer buf = new StringBuffer();
         buf.append("<html><head><script>//<![CDATA[\n");
         buf.append("var url='"+ url + "';\n");
         buf.append(flowInfo.getOnExitScript());
         buf.append("\n//]]>\n");
         buf.append("</script></head></html>");
         try
         {
             // Here we cannot use facesContext.getResponseWriter(). That returns null
             // until after ViewHandler.renderView has been invoked, but here we expect to
             // be in the "event broadcast" part of either APPLY_REQUEST_VALUES (for immediate
             // command components) or INVOKE_APPLICATION. So here we simply use the raw
             // servlet response stream. Hey, all this html-generation is so hacky it seems no
             // worse to access the response stream here.
             //
             // Of course this won't work with portlets, but the idea of a portlet popping
             // up a modal window to invoke a flow is rather unlikely anyway..
             HttpServletResponse rsp = (HttpServletResponse) ec.getResponse();
             rsp.getWriter().write(buf.toString());
         }
         catch(IOException ioe)
         {
             throw new FacesException(ioe);
         }
         facesContext.responseComplete();
     }
 
     private static void restoreViewRoot(FacesContext facesContext, String viewId, UIViewRoot viewRoot)
     {
         if (viewRoot == null)
         {
             viewRoot = createDummyViewRoot(facesContext, viewId);
         }
         facesContext.setViewRoot(viewRoot);
     }
 
     private static UIViewRoot createDummyViewRoot(FacesContext facesContext, String viewId)
     {
         // Create dummy viewRoot with the right viewId so that navigation
         // uses the desired from-view-id during navigation case lookup.
         //
         // Unfortunately when the navigation rule matched is not a forward,
         // then ViewHandler.createView is executed and that expects to be able to
         // copy properties locale and renderKitId from the current view root into
         // the new view root. So we need to ensure that those properties are also
         // correctly set up on our dummy view root.
 
         java.util.Locale locale;
         String renderKitId;
 
         if (facesContext.getViewRoot() != null)
         {
             UIViewRoot currViewRoot = facesContext.getViewRoot();
             locale = currViewRoot.getLocale();
             renderKitId = currViewRoot.getRenderKitId();
         }
         else
         {
             ViewHandler vh = facesContext.getApplication().getViewHandler();
             locale = vh.calculateLocale(facesContext);
             renderKitId = vh.calculateRenderKitId(facesContext);
         }
 
         UIViewRoot dummyViewRoot = new UIViewRoot();
         dummyViewRoot.setViewId(viewId);
         dummyViewRoot.setLocale(locale);
         dummyViewRoot.setRenderKitId(renderKitId);
         
         return dummyViewRoot;
     }
 
     private static String handleCancelFlow(FacesContext facesContext, FlowInfo flowInfo, String outcome)
     {
         String callerViewId = flowInfo.getCallerViewId();
         UIViewRoot callerViewRoot = flowInfo.getCallerViewRoot();
 
         ConversationManager cm = ConversationManager.getInstance(true);
         ConversationContext ctx = cm.getCurrentConversationContext();
         ConversationContext parent = ctx.getParent();
         cm.activateConversationContext(parent);
         cm.removeAndInvalidateConversationContext(ctx);
         
         // Mark flowInfo as cancelled
         flowInfo.cancel();
 
         // Store viewRoot from flowInfo into parent context. Note that this might be null;
         // in this case the user of this property will simply ignore it, and create a new
         // view tree using the viewId in the incoming request url.
         parent.setAttribute(VIEW_TO_RESTORE_KEY, callerViewRoot);
 
         // And redirect. This sets responseComplete, so navigation is skipped.
         redirectTo(facesContext, callerViewId, flowInfo);
         return outcome;
     }
 
     private static String handleCommitFlow(FacesContext facesContext, FlowInfo flowInfo, String outcome)
     {
         String callerViewId = flowInfo.getCallerViewId();
         UIViewRoot callerViewRoot = flowInfo.getCallerViewRoot();
 
         ConversationManager cm = ConversationManager.getInstance(true);
         ConversationContext ctx = cm.getCurrentConversationContext();
         ConversationContext parent = ctx.getParent();
 
         // With the child conversationContext currently active, read
         // all the output parameters
         Map<String, Object> map = flowInfo.getFlowAccept().readReturnParams(facesContext);
 
         // Mark flowInfo as committed.
         flowInfo.commit(map);
 
         // Activate the parent and discard the child context
         cm.activateConversationContext(parent);
         cm.removeAndInvalidateConversationContext(ctx);
 
         // Now restore the view tree of the caller.
         //
         // WARNING: this approach means that any "binding" attributes on the components
         // being restored are not run. If a binding to a request-scope attribute exists,
         // then it will be null during the following render phase :-(
         restoreViewRoot(facesContext, callerViewId, callerViewRoot);
 
         if (callerViewRoot != null)
         {
             // Clear any input components in the caller view which reference values that
             // are return values.
             ClearOnCommit.executeAllInstances(callerViewRoot, flowInfo.getCallerOutcome());
         }
 
         // And with the original context active, write parameters back then
         // invoke any custom actions the caller wants to run.
         //
         // Note that the setters invoked when copying data back into the caller
         // flow should *not* access any bindings. When the command component that
         // originally triggered the flowcall was not immediate, then the view is
         // just a UIViewRoot with none of the expected child components in it. When
         // the original command component was immediate, the whole view tree is here
         // but no bindings have been restored because we did not deserialize the tree.
         // Of course the backing beans should *not* have kept any binding references
         // for longer than the current request; that's bad practice for a lot of reasons.
         // Therefore all those bindings will be null. This shouldn't be a problem; 
         // property setter methods should not need to access bindings.
         //
         // Possibly with JSF1.2 we could run the "build component tree" part of the
         // render cycle, then invoke UIViewRoot.restoreState. There is no possibility of
         // doing something similar for JSF1.1 though, and it shouldn't be necessary
         // anyway.
         //
         // Note that the ViewController methods are not invoked even though
         // the backing bean for the view is. This is not a problem really, just
         // something to be aware of.
         FlowCall flowCall = flowInfo.getFlowCall();
         flowCall.writeAcceptParams(facesContext, map);
         FlowOnCommit onCommit = flowCall.getOnCommit();
         outcome = null;
         if (onCommit != null)
         {
             outcome = (String) onCommit.execute(facesContext);
         }
         if (outcome == null)
         {
             // Store viewRoot from flowInfo into parent context
             parent.setAttribute(VIEW_TO_RESTORE_KEY, callerViewRoot);
             redirectTo(facesContext, callerViewId, flowInfo);
         }
         else
         {
             // Compute the viewId that this outcome maps to, then redirect to it. Note that
             // we have restored the caller's view so navigation rules for the caller's view
             // are used.
             //
             // Tricky: any attempt to compute the new viewId will trigger createView. We therefore
             // need to set a flag telling the ViewHandler to just do a redirect in createView. Ugly,
             // and might have problems when other custom ViewHandlers are also configured, but JSF
             // gives us no option here.
             facesContext.getExternalContext().getRequestMap().put("isRedirectOnReturn", Boolean.TRUE);
         }
 
         return outcome;
     }
 
     /**
      * Do actions that do not depend on properties of the called flow (if any).
      * <p>
      * Without knowing anything about the target of the navigation (other than
      * its viewId), the following can still be done:
      * <ul>
      * <li>commit or cancel the current flow if the nav outcome matches</li>
      * <li>determine whether this navigation triggers a new flow. If so, create
      * a child context and place a partially-initialised FlowInfo object in it.</li>
      * </ul> 
      * <p>
      * This is expected to be called from the FlowNavigationHandler after some
      * postback has caused a navigation to occur. Note that in that case we do
      * not yet know what viewId we are going <i>to</i>.
      *
      * @return a navigation outcome string to pass to the NavigationHandler. Note
      * however that if this method has sent a redirect then the return value will
      * simply be ignored.
      */
     static String processPreNav(FacesContext facesContext, String outcome)
     {
         String oldViewId = facesContext.getViewRoot().getViewId();
         log.debug("processCall: [" + String.valueOf(oldViewId) + "] outcome: " + outcome);
 
         if (outcome == null)
         {
             // not calling or returning from a flow; just ignore.
             return outcome;
         }
 
         // Handle COMMIT and CANCEL
         FlowInfo flowInfo = getFlowInfo();
         if (flowInfo != null)
         {
             // we are in a flow - are we leaving it?
             FlowAccept fa = flowInfo.getFlowAccept();
 
             if (outcome.equals(fa.getCancelWhen()))
             {
                 return handleCancelFlow(facesContext, flowInfo, outcome);
             }
 
             if (outcome.equals(fa.getCommitWhen()))
             {
                 return handleCommitFlow(facesContext, flowInfo, outcome);
             }
 
             if (outcome.equals(fa.getRestartWhen()))
             {
                 // restart current flow
                 throw new FacesException("flow restart not yet implemented");
             }
         }
 
         // OK, we know we are not committing or canceling a flow. Are we trying to
         // enter one?
         UIViewRoot oldViewRoot = facesContext.getViewRoot();
         FlowCall flowCall = getFlowCall(facesContext, oldViewRoot, outcome);
         if (flowCall != null)
         {
             // ugly hack: remove any FlowConfig object that the caller may have placed in the
             // request scope. If we don't do that, then when looking for the FlowConfig for
             // the called page we find this instead of loading the -flow.xml file for the
             // caller. There may be a nicer alternative to this, but it will do for now.
             facesContext.getExternalContext().getRequestMap().remove(FlowConfig.CONFIG_KEY);
 
             // fetch parameters from caller into a map
             Map<String,Object> data = flowCall.readSendParams(facesContext);
 
             // Only when the triggering commandButton is immediate should we save the viewRoot.
             if (PhaseId.APPLY_REQUEST_VALUES == FlowPhaseTracker.getCurrentPhase())
             {
                 // yep, this was triggered by an immediate component
                 //
                 // Ideally we would serialize the state here, and just cache the serialized object.
                 // That would save memory, flush transient properties on restore, work better with
                 // distributed html sessions and just generally be tidier.
                 //
                 // However the StateManager api in JSF1.1 and JSF1.2 (and maybe later) is brain-dead;
                 // it provides a public API for saving the state but the public api for restoring it
                 // doesn't allow the old saved-state to be passed in! The only use for the saved state
                 // is to pass it to StateManager.writeState; the public API for restoring state instead
                 // uses implementation-specific code to extract the state to restore directly from either
                 // the request or the session. Sigh. Curse. So instead, we always cache a full
                 // UIViewRoot in the FlowInfo object.
                 //
                 // Note that when the view is "restored" by simply resetting the viewroot reference,
                 // component bindings are not invoked. But that is ok as
             }
 
             // Build a FlowInfo object for the called flow to use.
             flowInfo = new FlowInfo(outcome, oldViewId, oldViewRoot, flowCall, data);
             
             // create child context and activate it
             ConversationManager cm = ConversationManager.getInstance(true);
             ConversationContext parent = cm.getCurrentConversationContext();
             ConversationContext child = cm.createConversationContext(parent);
             cm.activateConversationContext(child);
 
             // Handle triggering of modalflow if any
             ModalFlow f = ModalFlow.getForOutcome(facesContext, outcome);
             if (f != null)
             {
                 // The current view contains a ModalFlow component that declares that it will handle
                 // the new flow by opening the entry page in a new frame or window. We mark that component
                 // as "active" so that the component renders javascript to open that window. We also mark
                 // the FlowInfo as modal; this is checked in FlowViewHandler.createView.
                 flowInfo.setModalFlow(true);
                 flowInfo.setOnExitScript(f.getOnExit());
                 f.setActive(true);
             }
 
             // Store the flowInfo in the child context
             child.setAttribute("flowInfo", flowInfo);
 
             String newViewId = flowCall.getViewId();
             if (newViewId != null)
             {
                 // The flowcall has directly specified a view to render.
                 ViewHolder viewHolder = new ViewHolder();
                 ViewHandler viewHandler = facesContext.getApplication().getViewHandler();
                 boolean isNewFlow = doNewFlowEntry(facesContext, viewHandler, viewHolder, flowInfo, newViewId);
                 if (isNewFlow == false)
                 {
                     throw new OrchestraException("viewId specified in flowCall is not a flow entry point");
                 }
                 
                 if (viewHolder.root == null)
                 {
                     redirectTo(facesContext, newViewId, flowInfo);
                 }
                 else
                 {
                     // this is a modal flow; we need to re-render the current view, ie do a 
                     // null navigation.
                     return null;
                 }
             }
             else
             {
                 // And let normal navigation occur. Hopefully the new page will be the entry-point
                 // for a flow, in which case we finish setting up the FlowInfo object then redirect
                 // to the flow entry point; see FlowViewHander.createView. If something goes wrong,
                 // then FlowViewHandler.createView will clean up.
             }
         }
         
         return outcome;
     }
 
     /**
      * Handle case where the user is in a flow, then navigates somehow to a page that is not
      * within the flow.
      */
     private static boolean isAbnormalFlowExit(FlowInfo flowInfo, String newViewId)
     {
         // Are we leaving a flow in an abnormal manner?
         if (flowInfo != null)
         {
             String flowPath = getFlowPath(newViewId);
             if (!flowPath.startsWith(flowInfo.getFlowPath()))
             {
                 // User must have navigated away from the current flow. Walk up the tree invalidating
                 // each context until we find a flow that does match the new path, or we find the root
                 // context (which never has a FlowInfo in it).
                 ConversationManager cm = ConversationManager.getInstance(true);
                 ConversationContext ctx = cm.getCurrentConversationContext();
                 ConversationContext parent = ctx.getParent();
                 for(;;)
                 {
                     if (parent == null)
                     {
                         // After discarding all invalid flows, let normal navigation occur
                         // to the new viewId. There is no view to "restore".. 
                         break;
                     }
     
                     cm.activateConversationContext(parent);
                     cm.removeAndInvalidateConversationContext(ctx);
                     ctx = parent;
                     parent = ctx.getParent();
                     
                     FlowInfo fi = getFlowInfo(ctx);
                     if ((fi != null) && (flowPath.startsWith(fi.getFlowPath())))
                     {
                         // ok, the view the user wants to navigate to is within
                         // the context just activated, so we now have things set
                         // up as required; break out of loop.
                         break;
                     }
                 }
 
                 return true;
             }
         }
 
         // nope, this is just a normal navigation
         return false;
     }
 
     private static class ViewHolder
     {
         UIViewRoot root;
     }
 
     /**
      * Handle case where we have just navigated to a new page, and the page that caused the
      * navigation did a flow-call.
      * <p>
      * When this is true, a child context will already have been created, and a half-initialised
      * FlowInfo object will be in the context. We need to now fetch the called flow's specs,
      * check that the caller and called flows match in type and parameters, then finish
      * initialising the FlowInfo and import the passed params into the child context.
      * <p>
      * This is expected to be called from FlowViewHandler when a new view is being created
      * (due either to a GET or POST from the user, or an internal forward due to navigation.
      */
     static boolean doNewFlowEntry(FacesContext facesContext, ViewHandler viewHandler,
             ViewHolder viewHolder, FlowInfo flowInfo, String newViewId)
     {
         if (flowInfo == null)
         {
             // No, the processCall method has not created a new partially-initialised
             // FlowInfo object.
             return false;
         }
 
         if (flowInfo.getFlowAccept() != null)
         {
             // No, the processCall method has not created a new partially-initialised
             // FlowInfo object.
             return false;
         }
 
         FlowAccept flowAccept = getFlowAccept(facesContext, flowInfo, newViewId);
         if (flowAccept == null)
         {
             // TODO: discard all flow stacks here for safety?
             StringBuffer msg = new StringBuffer();
             msg.append("Invocation of flow without callee declaration. ");
             msg.append("Calling view is " + flowInfo.getCallerViewId() + ". ");
             msg.append("Called view is " + newViewId + ".");
             if (log.isDebugEnabled())
             {
                 log.debug("isNewFlowEntry: Error: " + msg.toString());
             }
             throw new OrchestraException(msg.toString());
         }
 
         if (log.isDebugEnabled())
         {
             log.debug("isNewFlowEntry: new flow detected.");
         }
         // validate flowCall against flowAccept. TODO: discard flow stacks on error?
         validateCall(flowInfo.getFlowCall(), flowAccept);
 
         // finish initialising the new flowInfo
         String flowPath = getFlowPath(newViewId);
         flowInfo.setAcceptInfo(newViewId, flowPath, flowAccept);
 
         // push parameters from caller to callee
         Map<String,Object> argsIn = flowInfo.getArgsIn();
         flowAccept.writeAcceptParams(facesContext, argsIn);
 
         ExternalContext externalContext = facesContext.getExternalContext();
         
         // The "postback" part of the current request must have started a flow call.
         if (flowInfo.isModalFlow())
         {
             // First compute the URL for the *new* viewId (the flow entry page) while the child
             // context is active so the conversationContext query param gets set right.
             String newViewUrl = viewHandler.getActionURL(facesContext, newViewId);
             newViewUrl = externalContext.encodeActionURL(newViewUrl);
 
             // Verify that this really is the entry point for a new flow.
             // Do import On error, reset
             // context to parent then throw exception.
             // And copy input parameters for the 
             // Now we want to re-render the *old* view, so we need to activate the parent
             // context for the remainder of this request. Note that the ConversationManager
             // must exist as we have a FlowInfo object.
             ConversationManager cm = ConversationManager.getInstance();
             ConversationContext child = cm.getCurrentConversationContext();
             ConversationContext parent = child.getParent();
             cm.activateConversationContext(parent);
 
             // Set some variables that allows components in the page to
             // access the URL that the new modal window should fetch.
             setNewViewInfo(newViewId, newViewUrl);
 
             // And just return the current view rather than creating a new one.
             viewHolder.root = facesContext.getViewRoot();
             return true;
         }
 
         // Force a redirect to the entry page for the flow. Note that the currently activated context
         // is the child one, so getActionURL encodes the conversationContext value appropriately.
         String newViewUrl = viewHandler.getActionURL(facesContext, newViewId);
         newViewUrl = externalContext.encodeActionURL(newViewUrl);
         try
         {
             facesContext.getExternalContext().redirect(newViewUrl);
             return true;
         }
         catch(IOException ioe)
         {
             throw new FacesException("Unable to enter flow", ioe);
         }
         
     }
 
     private static Object rmvContextAttribute(String id)
     {
         ConversationManager cm = ConversationManager.getInstance(false);
         if (cm == null)
         {
             return null;
         }
         
         ConversationContext ctx = cm.getCurrentConversationContext();
         if (ctx == null)
         {
             return null;
         }
         
         Object o = ctx.removeAttribute(id);
         return o;
     }
 
     private static void setNewViewInfo(String viewId, String viewUrl)
     {
         FacesContext fc = FacesContext.getCurrentInstance();
         Map<String, Object> reqMap = fc.getExternalContext().getRequestMap();
         reqMap.put("orchestraFlowId", viewId);
         reqMap.put("orchestraFlowUrl", viewUrl);
     }
 
     /**
      * Special createView handling for Orchestra Flows.
      * <p>
      * When this request was a postback that started a flowcall:
      * <ul>
      * <li>validate that this new view is a suitable flow entry point
      * <li>import passed parameters into child context
      * <li>for non-modal call: send a redirect to this view
      * <li>for modal call: rerender the *old* view, which should then
      * trigger a GET to the new view in a new window or frame.
      * </ul>
      * <p>
      * When this request was a postback that started a flowreturn:
      * <ul>
      * <li>Normally the view to return to is known so this code is not executed.
      * <li>When the view to return to has a "return handler" that provides 
      * a nav-outcome then this code is executed; just redirect to the desired view.
      * </ul>
      * <p>
      * Throws OrchestraException if there is a flow error, eg if the view
      * specified is the entry point for a flow but the previous view did
      * not do a FlowCall.
      *
      * @return a UIViewRoot to use when rendering this request. If null is returned
      * then the standard ViewHandler.createView method is used to create one. Note
      * however that if this method has sent a redirect then the return value will
      * simply be ignored.
      */
     static UIViewRoot processPreCreateView(FacesContext facesContext, ViewHandler viewHandler, String newViewId)
     {
         log.debug("processAccept: [" + newViewId + "]");
 
         FlowInfo flowInfo = getFlowInfo();
 
         boolean isRedirectOnReturn = facesContext.getExternalContext().getRequestMap()
                                         .containsKey("redirectOnReturn");
         if (isRedirectOnReturn)
         {
             // The current request contained a postback that triggered a flow-return. The caller also had a
             // return-handler that returned an outcome to navigate to, ie the caller wants an immediate
             // bounce to somewhere else rather than redisplaying itself. We couldn't compute the url to redirect
             // to earlier due to the brain-dead NavigationHandler api, so have to handle it here.
             //
             // Force a redirect to the entry page for the flow. Note that the currently activated context
             // is the child one, so getActionURL encodes the conversationContext value appropriately.
             ExternalContext ec = facesContext.getExternalContext();
             String newViewUrl = viewHandler.getActionURL(facesContext, newViewId);
             newViewUrl = ec.encodeActionURL(newViewUrl);
             try
             {
                 ec.redirect(newViewUrl);
                 return null;
             }
             catch(IOException ioe)
             {
                 throw new FacesException("Unable to enter flow", ioe);
             }
         }
         
         UIViewRoot viewToRestore = (UIViewRoot) rmvContextAttribute(VIEW_TO_RESTORE_KEY);
         if (viewToRestore != null)
         {
             // The previous request triggered a flowreturn, ie this request is re-rendering the calling view.
             // We therefore may have a cached viewRoot object that holds the view saved when the call was made..
             //
             // TODO: possibly check that viewToRestore.viewId == newViewId. This should always be true, as we
             // only set that attribute immediately before sending a redirect to the matching id.
             return viewToRestore;
         }
 
         ViewHolder viewHolder = new ViewHolder();
         if (doNewFlowEntry(facesContext, viewHandler, viewHolder, flowInfo, newViewId))
         {
             // We have just entered a new flow
             return viewHolder.root;
         }
 
         if (isAbnormalFlowExit(flowInfo, newViewId))
         {
             // User has leapt out of an existing flow
             return null;
         }
 
         // Below here are just sanity checks, looking for weird situations..
 
         FlowAccept flowAccept = getFlowAccept(facesContext, flowInfo, newViewId);
         boolean isFlowEntryPoint = (flowAccept != null);
         boolean isInFlow = (flowInfo != null);
 
         if (isFlowEntryPoint && !isInFlow)
         {
             // The new page is a flow entry point, but the earlier page did a normal navigation,
             // without any flow-call. Therefore we do not have a child context set up, and no
             // FlowInfo object. Unfortunately we therefore do not know what the previous
             // page was...
             StringBuffer msg = new StringBuffer();
             msg.append("Invocation of flow without caller declaration. ");
             msg.append("Called view is " + newViewId + ".");
             log.debug("processAccept: Error: " + msg.toString());
             throw new OrchestraException(msg.toString());
         }
         
 
         if (isInFlow)
         {
             // We can safely fetch the current conversation context this without checking for
             // nulls; flowInfo is non-null so they must exist.
             ConversationManager cm = ConversationManager.getInstance();
             ConversationContext context = cm.getCurrentConversationContext();
 
             // Sanity check: verify that the current context has no children. If it
             // does, then presumably someone has used a back button to go from a 
             // nested flow to a parent flow. Possibly we could handle this by just
             // discarding the children, but for now report an error.
             //
             // Note that the case of the user simply clicking a link that goes outside
             // the current flow is handled in isAbnormalFlowExit; this is just for cases
             // where the viewId and the contextId have changed together which should only
             // happen for back-button or maybe bookmarks.
             //
             // Hmm..should we do this for any context, not just when isInFlow is true?
             // Or should the orchestra core check for this? 
             if (context.hasChildren())
             {
                 throw new OrchestraException("Child flow not properly terminated.");
             }
         }
 
         // all ok, let view be created in normal manner
         return null;
     }
 
     /**
      * Return the FlowConfig object associated with the specified viewId, or null if
      * none exists.
      * <p>
      * The current implementation just looks for a "-flow.xml" file relative to the
      * specified view.
      */
     private static FlowConfig getFlowConfig(FacesContext facesContext, String viewId)
     {
         log.debug("getflowConfig for [" + viewId + "]");
         if (viewId == null)
         {
             // This can happen when someone has a navigation-case that specifies
             // an outcome but no to-view-id.
             return null;
         }
 
         // first, see if a FlowConfig is cached in the request
         ExternalContext externalContext = facesContext.getExternalContext();
         FlowConfig cfg = (FlowConfig) externalContext.getRequestMap().get(FlowConfig.CONFIG_KEY);
         if (cfg != null) 
         {
             log.debug("Found flowConfig cached in viewRoot");
             return cfg;
         }
         
         int lastDot = viewId.lastIndexOf(".");
         if (lastDot == -1)
         {
             return null;
         }
 
 
         String path = viewId.substring(0, lastDot) + "-flow.xml";
         InputStream is = externalContext.getResourceAsStream(path);
         if (is == null)
         {
             log.debug("getFlowConfig: not found at " + path);
             return null;
         }
         try
         {
             InputSource source = new InputSource(is);
             source.setSystemId(path);
             cfg = FlowDigester.digest(source);
             log.debug("getFlowConfig: found at " + path);
             return cfg;
         }
         finally
         {
             try
             {
                 is.close();
             }
             catch(Exception e)
             {
                 // ignore
             }
         }
     }
 
     /**
      * Return the FlowInfo object stored in the current conversation
      * context (if any).
      */
     static FlowInfo getFlowInfo()
     {
         ConversationManager cm = ConversationManager.getInstance(false);
         if (cm == null)
         {
             return null;
         }
 
         ConversationContext context = cm.getCurrentConversationContext();
         if (context == null)
         {
             return null;
         }
 
         return getFlowInfo(context);
     }
 
     /**
      * Return the FlowInfo object associated with the specified conversation
      * context (if any).
      */
     private static FlowInfo getFlowInfo(ConversationContext context)
     {
         return (FlowInfo) context.getAttribute("flowInfo");
     }
 
     /**
      * Assuming that the specified viewId is the entry page for a flow, return a
      * viewId prefix that will match all views in the same flow.
      * <p>
      * This implementation assumes that a flow always lives in its own directory.
      */
     private static String getFlowPath(String viewId)
     {
         // just return everything up to (and including) the final slash
         int idx = viewId.lastIndexOf('/');
         if (idx <= 0)
         {
             // this cannot possibly be a flow
             return null;
         }
         return viewId.substring(0, idx +1);
     }
 
     /**
      * Ensure that the specified FlowCall object is compatible with this FlowAccept.
      * <p>
      * The parameters sent by the caller should match the params accepted by the called
      * flow. On return, the parameters sent by the called flow should match the params
      * accepted by the caller.
      * <p>
      * This method needs to be consistent with FlowAccept.writeAcceptParams method, but
      * should report better error messages. Possibly the writeAcceptParams method's error
      * messages could just be improved. However it is useful to be able to perform this
      * check earlier than before actually processing the return result.
      * <p>
      * This method also needs to be consistent with FlowCall.writeAcceptParams method.
      */
     static private void validateCall(FlowCall flowCall, FlowAccept flowAccept)
     {
         // check type matches
         if (!flowCall.getService().equals(flowAccept.getService()))
         {
             throw new OrchestraException(
                 "FlowCall service [" + flowCall.getService()
                 + "] does not match FlowAccept service [" + flowAccept.getService() + "]");
         }
 
         List<String> errors = new ArrayList<String>();
 
         // check input params
         List<String> callParamNames = new ArrayList<String>();
         for(FlowParamSend p : flowCall.getParams())
         {
             callParamNames.add(p.getName());
         }
 
         for(FlowParamAccept p : flowAccept.getParams())
         {
             String name = p.getName();
             if (!callParamNames.remove(name) && (p.getDflt() == null))
             {
                 // Accept param does not have call param equivalent, and there is no default parameter value
                 // defined. In other words, the called flow expects an input parameter but we have nothing that
                 // we can pass it.
                 errors.add(name);
             }
         }
         // Add any leftover call params that do not have accept param equivalents, ie where the caller is
         // trying to pass a parameter but the called flow is not expecting it.
         errors.addAll(callParamNames);
 
         if (!errors.isEmpty())
         {
             throw new OrchestraException("Parameter names mismatch:" + StringUtils.join(errors.iterator(), ","));
         }
 
         // check return params
         List<String> returnParamNames = new ArrayList<String>();
         for(FlowReturnSend p : flowAccept.getReturns())
         {
             returnParamNames.add(p.getName());
         }
 
         for(FlowReturnAccept p : flowCall.getReturns())
         {
             String name = p.getName();
             if (!returnParamNames.remove(name))
             {
                 // Returned param has no matching entry in the caller, ie the calling view is expecting a
                 // return value but the called flow is not returning it.
                 errors.add(name);
             }
         }
         // Add any leftover return params that do not have accept return param equivalents, ie where the
         // called flow is trying to return a value but the caller is not expecting it.
         errors.addAll(returnParamNames);
 
         if (!errors.isEmpty())
         {
             throw new OrchestraException("Return parameter names mismatch:" + StringUtils.join(errors.iterator(), ","));
         }
 
         // all ok
         return;
     }
 
     // no instances of this class expected
     private FlowHandler()
     {
     }
 }