source: branches/Operator Architecture Refactoring/HeuristicLab.Core/3.2/OperatorBase.cs @ 2045

#region License Information
/* HeuristicLab
 * Copyright (C) 2002-2008 Heuristic and Evolutionary Algorithms Laboratory (HEAL)
 *
 * This file is part of HeuristicLab.
 *
 * HeuristicLab is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * HeuristicLab 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 General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with HeuristicLab. If not, see <http://www.gnu.org/licenses/>.
 */
#endregion

using System;
using System.Collections.Generic;
using System.Text;
using System.Xml;

namespace HeuristicLab.Core {
  /// <summary>
  /// The base class for all operators.
  /// </summary>
  public abstract class OperatorBase : ItemBase, IOperator {
    private string myName;
    /// <summary>
    /// Gets or sets the name of the operator.
    /// </summary>
    /// <remarks>Calls <see cref="OnNameChanged"/> in the setter.</remarks>
    public string Name {
      get { return myName; }
      set {
        if (myName != value) {
          myName = value;
          OnNameChanged();
        }
      }
    }
    /// <summary>
    /// Gets the description of the current operator.
    /// </summary>
    /// <remarks>Returns "No operator description available" if the method is not overriden.</remarks>
    public virtual string Description {
      get { return "No operator description available."; }
    }
    /// <summary>
    /// Flag whether the current instance has been canceled.
    /// </summary>
    protected bool myCanceled;
    /// <inheritdoc/>
    public bool Canceled {
      get { return myCanceled; }
    }
    private bool myBreakpoint;
    /// <inheritdoc/>
    /// <remarks>Calls <see cref="OnBreakpointChanged"/> in the setter.</remarks>
    public bool Breakpoint {
      get { return myBreakpoint; }
      set {
        if (value != myBreakpoint) {
          myBreakpoint = value;
          OnBreakpointChanged();
        }
      }
    }

    private List<IOperator> mySubOperators;
    /// <summary>
    /// Gets a list of all suboperators.
    /// <note type="caution"> Returns the suboperators read-only!</note>
    /// </summary>
    public virtual IList<IOperator> SubOperators {
      get { return mySubOperators.AsReadOnly(); }
    }
    private Dictionary<string, IParameter> myParameters;
    /// <inheritdoc/>
    public virtual ICollection<IParameter> Parameters {
      get { return myParameters.Values; }
    }

    /// <summary>
    /// Initializes a new instance of <see cref="OperatorBase"/> setting the breakpoint flag and 
    /// the canceled flag to <c>false</c> and the name of the operator to the type name. 
    /// </summary>
    protected OperatorBase() {
      myName = this.GetType().Name;
      myCanceled = false;
      myBreakpoint = false;
      mySubOperators = new List<IOperator>();
      myParameters = new Dictionary<string, IParameter>();
    }

    /// <summary>
    /// Clones the current instance (deep clone).
    /// </summary>
    /// <remarks>Clones also sub operators, variables and variable infos.</remarks>
    /// <param name="clonedObjects">Dictionary of all already cloned objects. (Needed to avoid cycles.)</param>
    /// <returns>The cloned object as <see cref="OperatorBase"/>.</returns>
    public override object Clone(IDictionary<Guid, object> clonedObjects) {
      OperatorBase clone = (OperatorBase)base.Clone(clonedObjects);
      clone.myName = Name;
      clone.mySubOperators.Clear();
      for (int i = 0; i < SubOperators.Count; i++)
        clone.AddSubOperator((IOperator)Auxiliary.Clone(SubOperators[i], clonedObjects));
      clone.myParameters.Clear();
      foreach (IParameter parameter in myParameters.Values)
        clone.AddParameter((IParameter)Auxiliary.Clone(parameter, clonedObjects));
      return clone;
    }

    /// <summary>
    /// Creates a new instance of <see cref="OperatorBaseView"/> to represent the current operator
    /// visually.
    /// </summary>
    /// <returns>The created view as <see cref="OperatorBaseView"/>.</returns>
    public override IView CreateView() {
      return new OperatorBaseView(this);
    }

    #region SubOperator Methods
    /// <inheritdoc cref="HeuristicLab.Core.IOperator.AddSubOperator(HeuristicLab.Core.IOperator)"/>
    /// <param name="subOperator">The sub operator to add.</param>
    /// <remarks>Calls <see cref="OnSubOperatorAdded"/>.</remarks>
    public virtual void AddSubOperator(IOperator subOperator) {
      mySubOperators.Add(subOperator);
      OnSubOperatorAdded(subOperator, mySubOperators.Count - 1);
    }
    /// <inheritdoc cref="HeuristicLab.Core.IOperator.AddSubOperator(HeuristicLab.Core.IOperator, int)"/>
    /// <param name="subOperator">The sub operator to add.</param>
    /// <remarks>Calls <see cref="OnSubOperatorAdded"/>.</remarks>
    public virtual void AddSubOperator(IOperator subOperator, int index) {
      mySubOperators.Insert(index, subOperator);
      OnSubOperatorAdded(subOperator, index);
    }
    /// <inheritdoc/>
    /// <remarks>Calls <see cref="OnSubOperatorRemoved"/>.</remarks>
    public virtual void RemoveSubOperator(int index) {
      IOperator op = mySubOperators[index];
      mySubOperators.RemoveAt(index);
      OnSubOperatorRemoved(op, index);
    }
    #endregion

    #region Parameter Methods
    /// <inheritdoc/>
    public virtual IParameter GetParameter(string name) {
      IParameter info;
      if (myParameters.TryGetValue(name, out info))
        return info;
      else
        return null;
    }
    /// <inheritdoc/>
    /// <remarks>Calls <see cref="OnVariableInfoAdded"/>.</remarks>
    public virtual void AddParameter(IParameter parameter) {
      myParameters.Add(parameter.Name, parameter);
      OnParameterAdded(parameter);
    }
    /// <inheritdoc/>
    /// <remarks>Calls <see cref="OnVariableInfoRemoved"/>.</remarks>
    public virtual void RemoveParameter(string name) {
      IParameter parameter;
      if (myParameters.TryGetValue(name, out parameter)) {
        myParameters.Remove(name);
        OnParameterRemoved(parameter);
      }
    }
    #endregion

    /// <inheritdoc/>
    public virtual IOperation Execute(IEnvironment env, IScope scope) {
      myCanceled = false;

      IOperation next = Apply(env, scope);

      OnExecuted();
      return next;
    }
    /// <inheritdoc/>
    /// <remarks>Sets property <see cref="Canceled"/> to <c>true</c>.</remarks>
    public virtual void Abort() {
      myCanceled = true;
    }
    /// <summary>
    /// Performs the current operator on the specified <paramref name="scope"/>.
    /// </summary>
    /// <param name="scope">The scope where to execute the operator</param>
    /// <returns><c>null</c>.</returns>
    public virtual IOperation Apply(IEnvironment env, IScope scope) {
      return null;
    }
    /// <inheritdoc/>
    public event EventHandler NameChanged;
    /// <summary>
    /// Fires a new <c>NameChanged</c> event.
    /// </summary>
    protected virtual void OnNameChanged() {
      if (NameChanged != null) {
        NameChanged(this, new EventArgs());
      }
    }
    /// <inheritdoc/>
    public event EventHandler BreakpointChanged;
    /// <summary>
    /// Fires a new <c>BreakpointChanged</c> event.
    /// </summary>
    protected virtual void OnBreakpointChanged() {
      if (BreakpointChanged != null) {
        BreakpointChanged(this, new EventArgs());
      }
    }
    /// <inheritdoc/>
    public event EventHandler<OperatorIndexEventArgs> SubOperatorAdded;
    /// <summary>
    /// Fires a new <c>SubOperatorAdded</c> event.
    /// </summary>
    /// <param name="subOperator">The sub operator that has been added.</param>
    /// <param name="index">The position where the operator has been added.</param>
    protected virtual void OnSubOperatorAdded(IOperator subOperator, int index) {
      if (SubOperatorAdded != null)
        SubOperatorAdded(this, new OperatorIndexEventArgs(subOperator, index));
    }
    /// <inheritdoc/>
    public event EventHandler<OperatorIndexEventArgs> SubOperatorRemoved;
    /// <summary>
    /// Fires a new <c>SubOperatorRemoved</c> event.
    /// </summary>
    /// <param name="subOperator">The sub operator that has been removed.</param>
    /// <param name="index">The position where the operator has been removed.</param>
    protected virtual void OnSubOperatorRemoved(IOperator subOperator, int index) {
      if (SubOperatorRemoved != null)
        SubOperatorRemoved(this, new OperatorIndexEventArgs(subOperator, index));
    }
    /// <inheritdoc/>
    public event EventHandler<ParameterEventArgs> ParameterAdded;
    /// <summary>
    /// Fires a new <c>ParameterAdded</c> event.
    /// </summary>
    /// <param name="parameter">The parameter that has been added.</param>
    protected virtual void OnParameterAdded(IParameter parameter) {
      if (ParameterAdded != null)
        ParameterAdded(this, new ParameterEventArgs(parameter));
    }
    /// <inheritdoc/>
    public event EventHandler<ParameterEventArgs> ParameterRemoved;
    /// <summary>
    /// Fires a new <c>ParameterRemoved</c> event.
    /// </summary>
    /// <param name="parameter">The parameter that has been removed.</param>
    protected virtual void OnParameterRemoved(IParameter parameter) {
      if (ParameterRemoved != null)
        ParameterRemoved(this, new ParameterEventArgs(parameter));
    }
    /// <inheritdoc/>
    public event EventHandler Executed;
    /// <summary>
    /// Fires a new <c>Executed</c> event.
    /// </summary>
    protected virtual void OnExecuted() {
      if (Executed != null) {
        Executed(this, new EventArgs());
      }
    }

    #region Persistence Methods
    /// <summary>
    /// Saves the current instance as <see cref="XmlNode"/> in the specified <paramref name="document"/>.
    /// </summary>
    /// <remarks>
    /// Calls <see cref="ConstrainedItemBase.GetXmlNode"/> of base class <see cref="ConstrainedItemBase"/>.
    /// <br/>A quick overview how the single elements of the current instance are saved:
    /// <list type="bullet">
    /// <item>
    /// <term>Name: </term>
    /// <description>Saved as an <see cref="XmlAttribute"/> with the name <c>Name</c>.</description>
    /// </item>
    /// <item>
    /// <term>Breakpoint: </term>
    /// <description>Is only saved if it set to <c>true</c>. 
    /// Saved as an <see cref="XmlAttribute"/> with the name <c>Breakpoint</c>.</description>
    /// </item>
    /// <item>
    /// <term>Sub operators: </term>
    /// <description>Saved as child node with tag name <c>SubOperators</c>. All sub operators are themselves
    /// saved as child nodes.</description>
    /// </item>
    /// <item>
    /// <term>Variable infos: </term>
    /// <description>Saved as child node with tag name <c>VariableInfos</c>. All variable infos are themselves
    /// saved as child nodes.</description>
    /// </item>
    /// <item>
    /// <term>Variables: </term>
    /// <description>Saved as child node with tag name <c>Variables</c>. All variables are themselves
    /// saved as child nodes.</description>
    /// </item> 
    /// </list>
    /// </remarks>
    /// <param name="name">The (tag)name of the <see cref="XmlNode"/>.</param>
    /// <param name="document">The <see cref="XmlDocument"/> where to save the data.</param>
    /// <param name="persistedObjects">The dictionary of all already persisted objects. (Needed to avoid cycles.)</param>
    /// <returns>The saved <see cref="XmlNode"/>.</returns>
    public override XmlNode GetXmlNode(string name, XmlDocument document, IDictionary<Guid,IStorable> persistedObjects) {
      XmlNode node = base.GetXmlNode(name, document, persistedObjects);
      XmlAttribute nameAttribute = document.CreateAttribute("Name");
      nameAttribute.Value = Name;
      node.Attributes.Append(nameAttribute);
      if (Breakpoint) {
        XmlAttribute breakpointAttribute = document.CreateAttribute("Breakpoint");
        breakpointAttribute.Value = Breakpoint.ToString();
        node.Attributes.Append(breakpointAttribute);
      }
      XmlNode subOperatorsNode = document.CreateNode(XmlNodeType.Element, "SubOperators", null);
      for (int i = 0; i < SubOperators.Count; i++)
        subOperatorsNode.AppendChild(PersistenceManager.Persist(SubOperators[i], document, persistedObjects));
      node.AppendChild(subOperatorsNode);
      XmlNode parametersNode = document.CreateNode(XmlNodeType.Element, "Parameters", null);
      foreach (IParameter parameter in myParameters.Values)
        parametersNode.AppendChild(PersistenceManager.Persist(parameter, document, persistedObjects));
      node.AppendChild(parametersNode);
      return node;
    }
    /// <summary>
    /// Loads the persisted operation from the specified <paramref name="node"/>.
    /// </summary>
    /// <remarks>Calls <see cref="ConstrainedItemBase.Populate"/> of base class 
    /// <see cref="ConstrainedItemBase"/>.
    /// For informations how the different elements must be saved please see <see cref="GetXmlNode"/>.</remarks>
    /// <param name="node">The <see cref="XmlNode"/> where the operation is saved.</param>
    /// <param name="restoredObjects">A dictionary of all already restored objects. (Needed to avoid cycles.)</param>
    public override void Populate(XmlNode node, IDictionary<Guid,IStorable> restoredObjects) {
      base.Populate(node, restoredObjects);
      myName = node.Attributes["Name"].Value;
      if (node.Attributes["Breakpoint"] != null)
        myBreakpoint = bool.Parse(node.Attributes["Breakpoint"].Value);
      XmlNode subOperatorsNode = node.SelectSingleNode("SubOperators");
      for (int i = 0; i < subOperatorsNode.ChildNodes.Count; i++)
        AddSubOperator((IOperator)PersistenceManager.Restore(subOperatorsNode.ChildNodes[i], restoredObjects));
      XmlNode parametersNode = node.SelectSingleNode("Parameters");
      myParameters.Clear();
      foreach (XmlNode parameterNode in parametersNode.ChildNodes)
        AddParameter((IParameter)PersistenceManager.Restore(parameterNode, restoredObjects));
    }
    #endregion
  }
}