// Model.java
// (C) 2009 by Michael Peter Christen; mc@yacy.net, Frankfurt a. M., Germany
// first published 03.12.2009 on http://yacy.net;
//
// This is a part of YaCy, a peer-to-peer based web search engine
//
// $LastChangedDate: 2009-05-28 01:51:34 +0200 (Do, 28 Mai 2009) $
// $LastChangedRevision: 5988 $
// $LastChangedBy: orbiter $
//
// LICENSE
//
// This program 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 2 of the License, or
// (at your option) any later version.
//
// This program 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 this program; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

package net.yacy.ai.greedy;

import java.util.List;


/**
 * a Model is the universe where specific Roles act with specific Findings.
 * The Model may be a playing field if applied for game playing or it may
 * be a theorem set if applied for automated theorem proving.
 * A specific Model should provide a simple initializer that creates a start model,
 * which may be a startup board in case of game playing or a standard model in case
 * of automated theorem proving.
 * Models provide exploration (creation of possible Findings) and ranking (evaluation
 * of a model situation to produce a ordering on possible model instances)
 *
 * @param <SpecificRole>
 * @param <SpecificFinding>
 */
public interface Model<SpecificRole extends Role, SpecificFinding extends Finding<SpecificRole>> extends Cloneable {
    
    /**
     * Create a list of possible findings in the current model instance.
     * This may be the list of possible moves for the current role/player in case of
     * game playing or the list of possible inference rule applications in case of
     * automated theorem proving.
     * @return an iterator on the list of all possible findings for the current model situation
     */
    public List<SpecificFinding> explore();
    
    /**
     * apply a finding to the current model.
     */
    public void applyFinding(SpecificFinding finding);

    /**
     * compute the ranking for the given role, the higher the better.
     * @param findings the number of findings that have applied so far
     * @param role the role for which the ranking shall be computed
     * @return the ranking for the given finding size and role
     */
    public int getRanking(int findings, SpecificRole role);

    /**
     * the model contains a status about roles that may act next
     * @return the next role
     */
    public SpecificRole currentRole();

    /**
     * switch to the next role. The current role is migrated to the
     * new role status, or the current rule is replaced with a new role
     */
    public void nextRole();
    
    /**
     * based on the model content and the model next-role compute a hash code
     * do not include a computation based on latest actions
     * @return a hash code
     */
    public int hashCode();

    /**
     * equal mathod according to hash method
     * @param om
     * @return true if other model is equal to the current model.
     */
    public boolean equals(Object om);

    /**
     * clone the model
     * @return a top-level cloned model
     * @throws CloneNotSupportedException
     */
    public Object clone() throws CloneNotSupportedException;
    
    /**
     * check if this model is in a termination status for a given role
     * 
     * @param role the role that is checked
     * @return true if the role caused termination
     */
    public boolean isTermination(SpecificRole role);
    
    /**
     * check if this model is in a termination status for anyone
     * 
     * @return the role for which this is a termination
     *         or null if there is no termination yet
     */
    public SpecificRole isTermination();
    
}