/*
    Copyright (C) 2006 Grid Systems, S.A.
   
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2.1 of the License, or (at your option) any later version.
   
    This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.
  
   You should have received a copy of the GNU Lesser General Public
   License along with this library; if not, write to the Free Software
   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
  */
  package com.gridsystems.nextgrid.api.pom;
  
  import java.net.URI;
  import java.util.ArrayList;
  import java.util.Collections;
  import java.util.HashMap;
  import java.util.List;
  import java.util.Map;
  import java.util.PriorityQueue;
  
  import nextgrid.api.env.Prioritiser;
  import nextgrid.api.env.ProcessEnvironment;
  import nextgrid.api.pom.AbstractProcess;
  import nextgrid.api.pom.ControlProcess;
  import nextgrid.api.pom.Process;
  import nextgrid.api.pom.ProcessException;
  import nextgrid.api.pom.Reference;
  
  /**
   * Control Process.
   * <p>
   * A control process is a process container that adds implicit execution flow
   * constraints to its children processes. These constraints may be implemented
   * through dependencies among the processes.
   * <p>
   * In addition to this, a control process can introduce "hints" that the
   * enactor may use to drive the evaluation process. For example, a conditional
   * control structure may instruct the enactor to only evaluate a subset of its
   * branches for considering it as valid.
   *
   * @author Rodrigo Ruiz
   */
  public abstract class ControlProcessImpl extends ProcessImpl
    implements ControlProcess {
  
    /**
     * Collection of children processes. As children processes will, at least,
     * be ranked and sorted at some point of the workflow life-cycle, this
     * collection must be implemented as a list.
     */
    private List<Process> children;
  
    /**
     * Process local variables.
     */
    private Map<String, Reference<?>> localVars;
  
    /**
     * Max number of children supported.
     */
    private final int maxChildren;
  
    /**
     * Memoization flag.
     */
    private boolean memoize;
  
    /**
     * Creates a new instance.
     *
     * @param maxChildren The max number of supported children processes
     */
    protected ControlProcessImpl(int maxChildren) {
      super();
      this.maxChildren = maxChildren;
      this.children = new ArrayList<Process>();
      this.localVars = new HashMap<String, Reference<?>>();
    }
  
    /**
     * {@inheritDoc}
     */
    public final Process findProcessById(URI id) {
      if (id == null) {
        return null;
      } else if (this.getId().equals(id)) {
        return this;
      } else {
        for (Process child : this.getChildren()) {
          Process found = child.findProcessById(id);
          if (found != null) {
            return found;
         }
       }
       return null;
     }
   }
 
   /**
    * {@inheritDoc}
    */
   public final void prioritise(ProcessEnvironment env, PriorityQueue<Process> queue)
     throws ProcessException {
 
     // Give a chance to global prioritisers
     Prioritiser prioritiser = env.getPrioritiserFor(this.getId());
     if (prioritiser != null) {
       prioritiser.prioritise(this);
     }
 
     for (Process p : getChildren()) {
       p.prioritise(env, queue);
     }
   }
 
   /**
    * {@inheritDoc}
    */
   public void discover(ProcessEnvironment env) throws ProcessException {
     for (Process p : getChildren()) {
       p.discover(env);
     }
   }
 
   /**
    * {@inheritDoc}
    */
   @Override
   public final void doEvaluate(ProcessEnvironment env) throws ProcessException {
     discover(env);
     PriorityQueue<Process> queue = prioritise(env);
 
     Process p = queue.poll();
     while (p != null) {
       p.evaluate(env);
       if (p instanceof AbstractProcess) {
         ENACTOR_LOG.debug("Prioritising...");
         Process selected = ((AbstractProcess)p).getSelected();
         if (selected != null) {
           selected.prioritise(env, queue);
         }
         ENACTOR_LOG.debug("Prioritised");
       }
       p = queue.poll();
     }
   }
 
   /**
    * {@inheritDoc}
    */
   public final boolean isMemoizeActive() {
     return this.memoize;
   }
 
   /**
    * {@inheritDoc}
    */
   public final void setMemoizeActive(boolean memoizeActive) {
     this.memoize = memoizeActive;
   }
 
   // ---------------------------------------------------------------------------
   // Child process management
   // ---------------------------------------------------------------------------
 
   /**
    * Gets the processes in the children list.
    *
    * @return An array of child processes
    */
   public final Process[] getChildren() {
     synchronized (children) {
       return children.toArray(new Process[children.size()]);
     }
   }
 
   /**
    * Gets a child process by its index.
    *
    * @param index The child process position
    * @return The process
    */
   public final Process getChildren(int index) {
     synchronized (children) {
       if (index >= children.size()) {
         return null;
       } else {
         return children.get(index);
       }
     }
   }
 
   /**
    * Gets the number of child processes.
    *
    * @return the number of child processes
    */
   public final int getChildCount() {
     synchronized (children) {
       return children.size();
     }
   }
 
   /**
    * Sets the size of the children list to a maximum of <tt>count</tt> items.
    * <p>
    * It correctly removes all items from position <tt>count</tt> to the end
    * of the list. If the list is already smaller than <tt>count</tt>, it does
    * nothing.
    *
    * @param count The max number of elements to maintain in the children list
    */
   public final void trim(int count) {
     synchronized (this.children) {
       int last = this.children.size() - 1;
       while (last >= count) {
         this.children.remove(last--);
       }
     }
   }
 
   /**
    * Sets the list of child processes for this process instance.
    *
    * @param children An array of processes
    */
   public final void setChildren(Process... children) {
     synchronized (this.children) {
       int pos = 0;
       for (Process item : children) {
         if (pos == this.children.size()) {
           addChildren(pos++, item);
         } else {
           setChildren(pos++, item);
         }
       }
       trim(pos);
     }
   }
 
   /**
    * Sets a child process.
    *
    * @param index The position in the list
    * @param child The process to set
    * @throws UnsupportedOperationException
    *         If the process does not support children
    */
   public final void setChildren(int index, Process child) {
     if (maxChildren == 0) {
       throw new UnsupportedOperationException("Children not supported");
     }
 
     synchronized (children) {
       if (maxChildren < 0 || index >= maxChildren) {
         throw new IndexOutOfBoundsException("Bad index: " + index);
       }
 
       Process previous;
       if (index >= children.size()) {
         children.add(child);
         previous = null;
       } else {
         previous = children.set(index, child);
       }
 
       if (child != null) {
         child.setParent(this);
       }
       if (previous != null) {
         if (previous.getParent() instanceof ControlProcess) {
           ((ControlProcess)previous.getParent()).removeChild(previous);
         }
         previous.setParent(this);
       }
     }
   }
 
   /**
    * Inserts the specified element at the specified position in this list.
    * Shifts the element currently at that position (if any) and any subsequent
    * elements to the right (adds one to their indices).<p>
    *
    * @param  index
    *         index at which the specified element is to be inserted.
    *
    * @param  child
    *         element to be inserted.
    *
    * @throws UnsupportedOperationException
    *         if the <tt>add</tt> method is not supported by this list.
    *
    * @throws ClassCastException
    *         if the class of the specified element prevents it from being added
    *         to this list.
    *
    * @throws IllegalArgumentException
    *         if some aspect of the specified element prevents it from being
    *         added to this list.
    *
    * @throws IndexOutOfBoundsException
    *         index is out of range (<tt>index &lt; 0 || index &gt; size()</tt>).
    */
   public final void addChildren(int index, Process child) {
     if (maxChildren == 0) {
       throw new UnsupportedOperationException("Children not supported");
     } else if (maxChildren > 0 && index != getChildCount()) {
       // Insertions not allowed when children size is fixed
       throw new IndexOutOfBoundsException("Bad index: " + index);
     }
 
     synchronized (children) {
       children.add(index, child);
 
       if (child != null) {
         if (child.getParent() instanceof ControlProcess) {
           ((ControlProcess)child.getParent()).removeChild(child);
         }
         child.setParent(this);
       }
     }
   }
 
   /**
    * Adds a set of processes to the child list.
    *
    * @param processes The processes to add
    */
   public final void addChildren(Process... processes) {
     int pos = this.getChildCount();
     for (Process item : processes) {
       addChildren(pos++, item);
     }
   }
 
   /**
    * Removes the element at the specified position in this list.
    * Shifts any subsequent elements to the left (subtracts one from their
    * indices). Returns the element that was removed from the list.
    *
    * @param  index
    *         the index of the element to remove
    *
    * @return the element previously at the specified position
    *
    * @throws UnsupportedOperationException
    *         if the <tt>remove</tt> method is not supported by this list.
    *
    * @throws IndexOutOfBoundsException
    *         if the specified index is out of range (<tt>index &lt; 0 ||
    *         index &gt;= size()</tt>).
    */
   public final Process removeChild(int index) {
     if (maxChildren == 0) {
       throw new UnsupportedOperationException("Children not supported");
     } else if (maxChildren > 0 && index != getChildCount() - 1) {
       // Removes not generally allowed when children size is fixed
       throw new IndexOutOfBoundsException("Bad index: " + index);
     }
 
     Process removed;
     synchronized (children) {
       removed = children.remove(index);
       removed.setParent(null);
     }
 
     return removed;
   }
 
   /**
    * Removes a process instance from the children list.
    *
    * @param child The process to remove
    * @return <tt>true</tt> if it is removed
    */
   public final boolean removeChild(Process child) {
     synchronized (children) {
       int pos = children.indexOf(child);
       if (pos == -1) {
         return false;
       } else {
         removeChild(pos);
         return true;
       }
     }
   }
 
   /**
    * {@inheritDoc}
    */
   public final Reference<?> getLocalVar(String name) {
     return this.localVars.get(name);
   }
 
   /**
    * {@inheritDoc}
    */
   public final void setLocalVar(String name, Reference<?> value) {
     this.localVars.put(name, value);
   }
 
   /**
    * {@inheritDoc}
    */
   public final Map<String, Reference<?>> getLocalVars() {
     return Collections.unmodifiableMap(localVars);
   }
 
   /**
    * {@inheritDoc}
    */
   @Override public Process copy() {
     ControlProcessImpl copy = (ControlProcessImpl)super.copy();
 
     copy.children = new ArrayList<Process>();
     for (Process p : children) {
       copy.children.add(p.copy());
     }
 
     return copy;
   }
 
   /**
    * Resets all child processes.
    * <p>
    * This method can be used by loop constructs to prepare each iteration.
    */
   @Override protected final void resetChildren() {
     for (Process p : this.getChildren()) {
       p.reset();
     }
   }
 }