/**
 * Copyright (c) 2002-2006 IBM Corporation and others.
 * All rights reserved.   This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 * 
 * Contributors: 
 *   IBM - Initial API and implementation
 */
package org.eclipse.emf.common.command;


import java.util.List;
import java.util.ListIterator;

import org.eclipse.emf.common.CommonPlugin;
import org.eclipse.emf.common.util.WrappedException;


/**
 * A composite command which assumes that later commands in the list 
 * may depend on the results and side-effects of earlier commands in the list.
 * Because of this, it must implement {@link Command#canExecute} more carefully,
 * i.e., in order to determine canExecute for the composite, it doesn't simply test each command.
 * It tests the first command to see if it can execute;
 * then, if there is another command in the list, it checks if the first command can undo and then goes ahead and executes it!
 * This process is repeated until the last command that is not followed by another, which then determines the final result.
 * (For efficiency, when this processing gets to the last command, that command is tested for canUndo too and that result is cached.)
 * All the commands that have been executed are then undone, if {@link #isPessimistic} is <code>true</code>; 
 * by default it's <code>false</code>.
 *
 * <p>
 * It is important for all but the last command to have no visible side-effect!
 * Multiple commands with visible side-effects must be composed into a single command using just a {@link CompoundCommand}
 * and that composite could be the last command of a strict composite.
 *
 * <p>
 * Here is an example of how this can be used in conjunction with a {@link CommandWrapper}.
 * <pre>
 *   Command strictCompoundCommand = new StrictCompoundCommand();
 *   Command copyCommand = new CopyCommand(...);
 *   strictCompoundCommand.add(copyCommand);
 *
 *   Command addCommand =
 *     new CommandWrapper()
 *     {
 *       public Command createCommand()
 *       {
 *         new AddCommand(parent, copyCommand.getResult()); 
 *       }
 *     };
 *   strictCompoundCommand.append(addCommand);
 * </pre>
 * Here the add command won't know which command to create until it has the result of the copy command.
 * The proxy makes sure the creation of the add command is deferred and the strict composite ensures that execution dependencies are met.
 */
public class StrictCompoundCommand extends CompoundCommand 
{
  /**
   * The result for {@link Command#canUndo}.
   */
  protected boolean isUndoable;

  /**
   * Whether commands that have been tentatively executed need to be undone.
   */
  protected boolean isPessimistic;

  /**
   * Remember to call redo instead of execute for any command at or before this index in the list.
   */
  protected int rightMostExecutedCommandIndex = -1;

  /**
   * Creates an empty instance.
   */
  public StrictCompoundCommand()
  {
    super();
    resultIndex = LAST_COMMAND_ALL;
  }

  /**
   * Creates an instance with the given label.
   * @param label the label.
   */
  public StrictCompoundCommand(String label)
  {
    super(label);
    resultIndex = LAST_COMMAND_ALL;
  }

  /**
   * Creates an instance with the given label and description.
   * @param label the label.
   * @param description the description.
   */
  public StrictCompoundCommand(String label, String description)
  {
    super(label, description);
    resultIndex = LAST_COMMAND_ALL;
  }

  /**
   * Creates an instance with the given command list.
   * @param commandList the list of commands.
   */
  public StrictCompoundCommand(List<Command> commandList)
  {     
    super(commandList);
    resultIndex = LAST_COMMAND_ALL;
  }

  /**
   * Creates an instance with the given label and command list.
   * @param label the label.
   * @param commandList the list of commands.
   */
  public StrictCompoundCommand(String label, List<Command> commandList)
  {     
    super(label, commandList);
    resultIndex = LAST_COMMAND_ALL;
  }

  /**
   * Creates an instance with the given label, description, and command list.
   * @param label the label.
   * @param description the description.
   * @param commandList the list of commands.
   */
  public StrictCompoundCommand(String label, String description, List<Command> commandList)
  {     
    super(label, description, commandList);
    resultIndex = LAST_COMMAND_ALL;
  }

  /**
   * Returns <code>false</code> if any command on the list returns <code>false</code> for {@link Command#canExecute},
   * or if some command before the last one can't be undone and hence we can't test all the commands for executability.
   * @return whether the command can execute.
   */
  @Override
  protected boolean prepare() 
  {
    // Go through the commands of the list.
    //
    ListIterator<Command> commands = commandList.listIterator(); 

    // If there are some...
    //
    if (commands.hasNext())
    {
      boolean result = true;

      // The termination guard is in the body.
      //
      for (;;)
      {
        Command command = commands.next();
        if (command.canExecute())
        {
          if (commands.hasNext())
          {
            if (command.canUndo())
            {
              try
              {
                if (commands.previousIndex() <= rightMostExecutedCommandIndex)
                {
                  command.redo();
                }
                else
                {
                  ++rightMostExecutedCommandIndex;
                  command.execute();
                }
              }
              catch (RuntimeException exception)
              {
                CommonPlugin.INSTANCE.log
                  (new WrappedException
                    (CommonPlugin.INSTANCE.getString("_UI_IgnoreException_exception"), exception).fillInStackTrace());

                result = false;
                break;
              }
            }
            else
            {
              // We can't undo it, so we'd better give up.
              //
              result = false;
              break;
            }
          }
          else
          {
            // Now is the best time to record isUndoable because later we would have to do all the executes again!
            // This makes canUndo very simple!
            //
            isUndoable = command.canUndo();
            break;
          }
        }
        else
        {
          // If we can't execute this one, we just can't do it at all.
          //
          result = false;
          break;
        }
      }

      // If we are pessimistic, then we need to undo all the commands that we have executed so far.
      //
      if (isPessimistic)
      {
        // The most recently processed command will never have been executed.
        //
        commands.previous();
  
        // We want to unroll all the effects of the previous commands.
        //
        while (commands.hasPrevious()) 
        {
          Command command = commands.previous();
          command.undo();
        }
      }

      return result;
    }
    else
    {
      isUndoable = false;
      return false;
    }
  }

  /**
   * Calls {@link Command#execute} for each command in the list, 
   * but makes sure to call redo for any commands that were previously executed to compute canExecute.
   * In the case that {@link #isPessimistic} is false, only the last command will be executed
   * since the others will have been executed but not undone during {@link #prepare}.
   */
  @Override
  public void execute() 
  {
    if (isPessimistic)
    {
      for (ListIterator<Command> commands = commandList.listIterator(); commands.hasNext(); ) 
      {
        try
        {
          // Either execute or redo the command, as appropriate.
          //
          Command command = commands.next();
          if (commands.previousIndex() <= rightMostExecutedCommandIndex)
          {
            command.redo();
          }
          else
          {
            command.execute();
          }
        }
        catch (RuntimeException exception)
        {
          // Skip over the command that threw the exception.
          //
          commands.previous();

          // Iterate back over the executed commands to undo them.
          //
          while (commands.hasPrevious())
          {
            commands.previous();
            Command command = commands.previous();
            if (command.canUndo())
            {
              command.undo();
            }
            else
            {
              break;
            }
          }

          throw exception;
        }
      }
    }
    else if (!commandList.isEmpty())
    {
      Command command = commandList.get(commandList.size() - 1);
      command.execute();
    }
  }

  /**
   * Calls {@link Command#undo} for each command in the list.
   * In the case that {@link #isPessimistic} is false, only the last command will be undone
   * since the others will have been executed and not undo during {@link #prepare}.
   */
  @Override
  public void undo() 
  {
    if (isPessimistic)
    {
      super.undo();
    }
    else if (!commandList.isEmpty())
    {
      Command command = commandList.get(commandList.size() - 1);
      command.undo();
    }
  }

  /**
   * Calls {@link Command#redo} for each command in the list.
   * In the case that {@link #isPessimistic} is false, only the last command will be redone
   * since the others will have been executed and not undo during {@link #prepare}.
   */
  @Override
  public void redo() 
  {
    if (isPessimistic)
    {
      super.redo();
    }
    else if (!commandList.isEmpty())
    {
      Command command = commandList.get(commandList.size() - 1);
      command.redo();
    }
  }

  /**
   * Checks if the command can execute; 
   * if so, it is executed, appended to the list, and <code>true</code> is returned,
   * if not, it is just disposed and <code>false</code> is returned.
   * A typical use for this is to execute commands created during the execution of another command, e.g.,
   * <pre>
   *   class MyCommand extends AbstractCommand
   *   {
   *     protected Command subcommand;
   *
   *     //...
   *
   *     public void execute()
   *     {
   *       // ...
   *       StrictCompoundCommand subcommands = new StrictCompoundCommand();
   *       subcommands.appendAndExecute(new AddCommand(...));
   *       if (condition) subcommands.appendAndExecute(new AddCommand(...));
   *       subcommand = subcommands.unwrap();
   *     }
   *
   *     public void undo()
   *     {
   *       // ...
   *       subcommand.undo();
   *     }
   *
   *     public void redo()
   *     {
   *       // ...
   *       subcommand.redo();
   *     }
   *
   *     public void dispose()
   *     {
   *       // ...
   *       if (subcommand != null)
   *      {
   *         subcommand.dispose();
   *       }
   *     }
   *   }
   * </pre>
   * @return whether the command was successfully executed and appended.
   */
  @Override
  public boolean appendAndExecute(Command command)
  {
    if (command != null)
    {
      if (!isPrepared)
      {
        if (commandList.isEmpty())
        {
          isPrepared = true;
          isExecutable = true;
        }
        else
        {
          isExecutable = prepare();
          isPrepared = true;
          isPessimistic = true;
          if (isExecutable)
          {
            execute();
          }
        }
      }
  
      if (command.canExecute())
      {
        try
        {
          command.execute();
          commandList.add(command);
          ++rightMostExecutedCommandIndex;
          isUndoable = command.canUndo();
          return true;
        }
        catch (RuntimeException exception)
        {
          CommonPlugin.INSTANCE.log
            (new WrappedException
              (CommonPlugin.INSTANCE.getString("_UI_IgnoreException_exception"), exception).fillInStackTrace());
        }
      }
  
      command.dispose();
    }

    return false;
  }

  /*
   * Javadoc copied from base class.
   */
  @Override
  public String toString()
  {
    StringBuffer result = new StringBuffer(super.toString());
    result.append(" (isUndoable: " + isUndoable + ")");
    result.append(" (isPessimistic: " + isPessimistic + ")");
    result.append(" (rightMostExecutedCommandIndex: " + rightMostExecutedCommandIndex + ")");

    return result.toString();
  }
}
