package yacs;

import yacs.domain.*;
import yacs.exceptions.*;
import yacs.net.*;

import java.util.*;

/**
 * <p>Der YACS Constraint-Manager (YCM) dient als zentrale Schnittstelle des
 * YACS-Frameworks. Er initiiert das Auslesen der Constraint-Lösungsstrategien
 * und verwaltet die entsprechenden Constraint-Netze. Über eine Instanz des YCM
 * lassen sich Constraints anhand des Namens einer verfügbaren
 * Constraint-Lösungsstrategie inkrementell zu den Constraint-Netzen
 * hinzugefügen. Der YCM initiiert und steuert die Anwendung der
 * Constraint-Lösungsstrategien und führt den phasenweisen Propagations- bzw.
 * Lösungsprozess durch.</p>
 *
 * <p>Copyright (C) 2005  Wolfgang Runte
 * <br><br>
 * 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.
 * <br><br>
 * 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.
 * <br><br>
 * 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 St, Fifth Floor, Boston, MA  02110-1301
 * USA</p>
 *
 * @author Wolfgang Runte (woru@tzi.org)
 * @version YACS 0.1.1
 */
public interface YacsConstraintManager {

  /**
   * Liefert eine "unmodifizierbare" Liste mit den Namen (<code>Strings</code>)
   * der existierenden Constraint-Lösungsstrategien und entsprechend der
   * verfügbaren Constraint-Netze.
   * @return List
   */
  public List getStrategyNames();

  /**
   * Liefert eine "unmodifizierbare" Liste mit verfügbaren Constraint-Netzen
   * (enthält Instanzen der Klasse <code>yacs.net.ConstraintNet</code>).
   * @return List
   */
  public List getConstraintNets();

  /**
   * Liefert das entsprechende Constraint-Netz zu dem übergebenen
   * Strategienamen, <code>null</code> wenn kein Constraint-Netz mit dieser
   * Strategie existiert.
   * @param strategyName String
   * @return ConstraintNet
   * @throws StrategyNotFoundException
   */
  public ConstraintNet getConstraintNet(String strategyName) throws StrategyNotFoundException;

//  /**
//   * Liefert eine "unmodifizierbare" Map mit den verfügbaren Constraint-Netzen.
//   * Der "Key" ist jeweils der Name der zuständigen Strategie, der "Value" das
//   * Constraint-Netz selbst (Instanz der Klasse
//   * <code>yacs.net.ConstraintNet</code>).
//   * @return Map
//   */
//  public Map getConstraintNetsMap();

  /**
    * Mit dieser Methoden kann ein Constraint inkrementell dem Lösungsprozess
    * zugeführt werden. Neben dem eigentlichen Constraint-Ausdruck als
    * <code>String</code> wird der Name der Strategie benötigt, mit der das
    * Constraint verarbeitet werden soll.
    * @param constraint String
    * @param strategyName String
    * @throws ConstraintParserException
    * @throws StrategyNotFoundException
    */
   public void addConstraint(String constraint, String strategyName) throws ConstraintParserException, StrategyNotFoundException;

  /**
   * Mit dieser Methoden können mehrere Constraints gleichzeitig bzw. ein
   * Teilproblem inkrementell dem Lösungsprozess zugeführt werden. Neben dem
   * eigentlichen Constraint-Ausdruck als <code>String</code> (die
   * Constraint-Ausdrücke müssen darin jeweils durch ein Semikolon voneinander
   * getrennt sein) wird der Name der Strategie benötigt, mit der die
   * Constraints verarbeitet werden sollen.
   * @param constraint String
   * @param strategyName String
   * @throws ConstraintParserException
   * @throws StrategyNotFoundException
   */
  public void addConstraints(String constraint, String strategyName) throws ConstraintParserException, StrategyNotFoundException;

  /**
   * Setzt den Wertebereich für eine Variable.
   * @param variableName String
   * @param variableDomain Domain
   * @throws VariableNotFoundException
   */
  public void setVariableDomain(String variableName, Domain variableDomain) throws VariableNotFoundException;

  /**
   * Liefert die entsprechende Domäne zur übergebenen Variable.
   * @param variableName String
   * @return Domain
   * @throws VariableNotFoundException
   */
  public Domain getVariableDomain(String variableName) throws VariableNotFoundException;

  /**
   * Liefert eine Liste mit den Namen aller Variablen sämtlicher vorhandenen
   * Constraint-Netze (enthält Instanzen der Klasse <code>String</code>).
   * @return List
   */
  public List getVariables();

  /**
   * Liefert eine Liste mit den Variablen (Instanzen der Klasse
   * <code>yacs.parser.Variable</code>), die sich in dem der übergebenen
   * Strategie zugehörigen Constraint-Netz befinden.
   * @param strategyName String
   * @return java.util.List
   * @throws yacs.exceptions.StrategyNotFoundException
   */
  public List getVariables(String strategyName) throws StrategyNotFoundException;

  /**
   * Liefert die ggf. bereits gefundenen Lösungen für das der übergebenen
   * Strategie zugehörige Teilproblem.
   * @param strategyName String
   * @return Solutions
   * @throws StrategyNotFoundException
   */
  public Solutions getSolutions(String strategyName) throws StrategyNotFoundException;

  /**
   * Liefert <code>true</code>, wenn für das der übergebenen Strategie
   * zugehörige Teilproblem bereits Lösungen gefunden wurden,
   * <code>false</code> wenn nicht.
   * @param strategyName String
   * @return boolean
   * @throws StrategyNotFoundException
   */
  public boolean hasSolutions(String strategyName) throws StrategyNotFoundException;

  /**
   * Liefert <code>true</code>, wenn die Domäne einer Variablen des der
   * übergebenen Strategie zugehörigen Teilproblems leer ist. In diesem Fall ist
   * für dieses Teilproblem keine Konsistenz bzw. Lösung herstellbar. Ansonsten
   * wird <code>false</code> zurückgegeben.
   * @param strategyName String
   * @return boolean
   * @throws StrategyNotFoundException
   */
  public boolean hasFalseDomain(String strategyName) throws StrategyNotFoundException;

  /**
   * Liefert <code>true</code>, wenn für das der übergebenen Strategie
   * zugehörige Teilproblem eine "valuation domain" vorliegt, d.h. in den
   * Domänen aller Variablen des Teilproblems ist jeweils genau ein Wert
   * enthalten. Ansonsten wird <code>false</code> zurückgegeben.
   * @param strategyName String
   * @return boolean
   * @throws StrategyNotFoundException
   */
  public boolean hasValuationDomain(String strategyName) throws StrategyNotFoundException;

  /**
   * Gibt zurück, ob ein Constraint-Solver für das der übergebenen Strategie
   * zugehörige Teilproblem eine Inkonsistenz gemeldet hat oder nicht (wird
   * zurückgesetzt durch die benutzerinitiierte Modifikation der Wertebereiche
   * der Constraint-Variablen und durch Hinzufügen einer Lösung zum
   * Teilproblem).
   * @param strategyName String
   * @return boolean
   * @throws StrategyNotFoundException
   */
  public boolean isInconsistent(String strategyName) throws StrategyNotFoundException;

  /**
   * Startet den Constraint-Lösungsvorgang. Ruft der Reihe nach die jeweiligen
   * Auswertemethoden der vorhandenen Constraint-Netze auf.
   */
  public void evaluate();

  /**
   * Setzt sämtliche Constraint-Netze wieder in den Ausgangszustand zurück, d.h.
   * es werden alle Informationen über die zugehörigen Teilprobleme einer
   * Strategie (Constraints, Variablen, Domänen, etc.) gelöscht.
   */
  public void tabularasa();

}


/**
 * <p></p>
 *
 * <p>Copyright (C) 2005  Wolfgang Runte
 * <br><br>
 * 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.
 * <br><br>
 * 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.
 * <br><br>
 * 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 St, Fifth Floor, Boston, MA  02110-1301
 * USA</p>
 *
 * @author Wolfgang Runte (woru@tzi.org)
 * @version YACS 0.1.1
 */

// ********** private attributs **********

// ********** public attributs **********

// ********** private methods **********

// ********** public methods **********

  /**
   * Konstruktor
   */
