/*
 * Copyright 2003-2005 The Apache Software Foundation
 *
 * Licensed 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.
 */

namespace Agility.Core
{
	/// <summary>
	/// A {@link Command} encapsulates a unit of processing work to be
	/// performed, whose purpose is to examine and/or modify the state of a
	/// transaction that is represented by a {@link Context}. 
	/// </summary>
	/// <remarks>
	/// <p>Individual {@link Command}s can be assembled into a {@link Chain}, which allows
	/// them to either complete the required processing or delegate further
	/// processing to the next {@link Command} in the {@link Chain}.</p>
	///
	/// <p>{@link Command} implementations should be designed in a thread-safe
	/// manner, suitable for inclusion in multiple {@link Chain}s that might be
	/// processed by different threads simultaneously.  In general, this implies
	/// that {@link Command} classes should not maintain state information in
	/// instance variables.  Instead, state information should be maintained via
	/// suitable modifications to the attributes of the {@link Context} that is
	/// passed to the <code>Execute</code> command.</p>
	///
	/// <p>{@link Command} implementations typically retrieve and store state
	/// information in the {@link Context} instance that is passed as a parameter
	/// to the <code>Execute</code> method, using particular keys into the
	/// <code>IDictionary</code> that can be acquired via 
	/// <code>Context.Keys</code>. 
	/// 
	/// <p>To improve interoperability of
	/// {@link Command} implementations, a useful design pattern is to expose the
	/// key values used as Properties of the {@link Command}
	/// implementation class itself.  For example, a {@link Command} that requires
	/// an input and an output key might implement the following properties:</p>
	///
	/// <pre>
	///   private string _InputKey = "input";
	///   public string InputKey {
	///    get { return _InputKey; }
	///	   set { _InputKey = value; }
	///   }
	///
	///   private string _OutputKey = "output";
	///   public string OutputKey {
	///    get { return _OutputKey; }
	///	   set { _OutputKey = value; }
	///   }
	/// </pre>
	///
	/// <p>And the operation of accessing the "input" information in the context
	/// would be executed by calling:</p>
	///
	/// <pre>
	///   string input = context[getInputKey()] as string;
	/// </pre>
	///
	/// <p>instead of hard coding the key attribute.  The use of the "Key"
	/// suffix on such property names is a useful convention to identify properties
	/// being used in this fashion, as opposed to properties that simply
	/// configure the internal operation of this {@link Command}.</p>
	/// </remarks>
	public interface ICommand
	{
		/// <summary>
		/// Execute a unit of processing work to be performed.  
		/// </summary>
		/// <remarks>
		/// This {@link ICommand} may either complete the required processing
		/// and return <code>true</code>, or delegate remaining processing
		/// to the next {@link ICommand} in a {@link IChain} containing this
		/// {@link ICommand} by returning <code>false</code>
		/// </remarks>
		/// <param name="context">The {@link IContext} to be processed by this
		///  {@link ICommand}</param>
		/// <returns>
		/// <code>true</code> if the processing of this {@link Context}
		///  has been completed, or <code>false</code> if the processing
		///  of this {@link IContext} should be delegated to a subsequent
		///  {@link ICommand} in an enclosing {@link IChain}
		/// </returns>
		bool Execute(IContext context);

	}
}