/**
 * <copyright> 
 *
 * Copyright (c) 2002-2004 IBM Corporation and others.
 * All rights reserved.   This program and the accompanying materials
 * are made available under the terms of the Common Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/cpl-v10.html
 * 
 * Contributors: 
 *   IBM - Initial API and implementation
 *
 * </copyright>
 *
 * $Id: Command.java,v 1.1 2005/04/15 23:31:25 david_williams Exp $
 */
package org.eclipse.emf.common.command;


import java.util.Collection;


/**
 * An interface that every command is expected to support.
 * A command can be tested for executability, 
 * it can be executed, 
 * it can be tested for undoability, 
 * it can be undone, 
 * and can then be redone.
 * A comand also provides access to a result collection, an affected-objects collection,
 * a label, and a description.
 *
 * <p>
 * There are important constraints on the valid order in which the various methods may be invoked,
 * e.g., you cannot ask for the result before you've executed the command.
 * These constraints are documented with the various methods.
 */
public interface Command 
{
  /**
   * Returns whether the comamad is valid to <code>execute</code>.
   * The {@link UnexecutableCommand#INSTANCE}.<code>canExecute()</code> always returns <code>false</code>.
   * This <b>must</b> be called before calling <code>execute</code>.
   * @return whether the comamad is valid to <code>execute</code>.
   */
  boolean canExecute();

  /**
   * Performs the command activity required for the effect.
   * The effect of calling <code>execute</code> when <code>canExecute</code> returns <code>false</code>, 
   * or when <code>canExecute</code> hasn't been called, is undefined.
   */
  void execute();

  /**
   * Returns whether the command can be undone.
   * The result of calling this before <code>execute</code> is well defined,
   * but the result of calling this before calling <code>canExecute</code> is undefined, i.e.,
   * a command that returns <code>false</code> for <code>canExecute</code> may return <code>true</code> for canUndo, 
   * even though that is a contradiction.
   * @return whether the command can be undone.
   */
  boolean canUndo();

  /**
   * Performs the command activity required to <code>undo</code> the effects of a preceding <code>execute</code> (or <code>redo</code>).
   * The effect, if any, of calling <code>undo</code> before <code>execute</code> or <code>redo</code> have been called, 
   * or when canUndo returns <code>false</code>, is undefined.
   */
  void undo();

  /**
   * Performs the command activity required to <code>redo</code> the effect after undoing the effect.
   * The effect, if any, of calling <code>redo</code> before <code>undo</code> is called is undefined.
   * Note that if you implement <code>redo</code> to call <code>execute</code> 
   * then any derived class will be restricted by that decision also.
   */
  void redo();

  /**
   * Returns a collection of things which this command wishes to present as it's result.
   * The result of calling this before an <code>execute</code> or <code>redo</code>, or after an <code>undo</code>, is undefined.
   * @return a collection of things which this command wishes to present as it's result.
   */
  Collection getResult();

  /**
   * Returns the collection of things which this command wishes to present as the objects affected by the command.
   * Typically should could be used as the selection that should be highlighted to best illustrate the effect of the command.
   * The result of calling this before an <code>execute</code>, <code>redo</code>, or <code>undo</code> is undefined.
   * The result may be different after an <code>undo</code> than it is after an <code>execute</code> or <code>redo</code>,
   * but the result should be the same (equivalent) after either an <code>execute</code> or <code>redo</code>.
   * @return the collection of things which this command wishes to present as the objects affected by the command.
   */
  Collection getAffectedObjects();

  /**
   * Returns a string suitable to represent the label that identifies this command.
   * @return a string suitable to represent the label that identifies this command.
   */
  String getLabel();

  /**
   * Returns a string suitable to help describe the effect of this command.
   * @return a string suitable to help describe the effect of this command.
   */
  String getDescription();

  /**
   * Called to indicate that the command will never be used again.
   * Calling any other method after this one has undefined results.
   */
  void dispose();

  /**
   * Returns a command that represents the composition of this command with the given command.
   * The resulting command may just be this, if this command is capabable of composition.
   * Otherwise, it will be a new command created to compose the two.
   * <p>
   * Instead of the following pattern of usage
   * <pre>
   *   Command result = x;
   *   if (condition) result = result.chain(y);
   * </pre>
   * you should consider using a {@link org.eclipse.emf.common.command.CompoundCommand} 
   * and using {@link org.eclipse.emf.common.command.CompoundCommand#unwrap()} to optimize the result:
   * <pre>
   *   CompoundCommand subcommands = new CompoundCommand();
   *   subcommands.append(x);
   *   if (condition) subcommands.append(y);
   *   Command result = subcommands.unwrap();
   * </pre>
   * This gives you more control over how the compound command composes it's result and affected objects.
   * @param command the command to chain.
   * @return a command that represents the composition of this command with the given command.
   */
  Command chain(Command command);
}