001    ///////////////////////////////////////////////////////////////////////////////
002    // Copyright (c) 2006, Frank S. Nestel, All Rights Reserved.
003    //
004    // This library is free software; you can redistribute it and/or
005    // modify it under the terms of the GNU Lesser General Public
006    // License as published by the Free Software Foundation; either
007    // version 2.1 of the License, or (at your option) any later version.
008    //
009    // This library is distributed in the hope that it will be useful,
010    // but WITHOUT ANY WARRANTY; without even the implied warranty of
011    // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
012    // GNU General Public License for more details.
013    //
014    // You should have received a copy of the GNU Lesser General Public
015    // License along with this program; if not, write to the Free Software
016    // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
017    ///////////////////////////////////////////////////////////////////////////////
018    
019    package de.spieleck.app.turn;
020    
021    /**
022     * Represents a way how games and players are scored.
023     * <br />
024     * ScoringMode is actually factories (GoF pattern) for
025     * implementations of {@link PlayerGameScore} and {@link PlayerScore}.
026     *
027     * <p><a href="$URL: https://svn.sourceforge.net/svnroot/jtourney/src/de/spieleck/app/turn/ScoringMode.java $">$URL: https://svn.sourceforge.net/svnroot/jtourney/src/de/spieleck/app/turn/ScoringMode.java $</a></p>
028     *
029     * @author Frank S. Nestel
030     * @author $Author: nestefan $
031     * @version $Revision: 2 $ $Date: 2006-03-20 14:33:27 +0100 (Mo, 20 Mrz 2006) $ $Author: nestefan $
032     */
033    public interface ScoringMode
034        extends LineSourceInited
035    {
036        /**
037         * Parse a single players score from a String.
038         */
039        public PlayerGameScore parseRawScore(String line)
040            throws Exception;
041    
042        /**
043         * Return error when scores are not fitting together.
044         * I.e. for chess the sum of all (=2) player scores must
045         * be 1 and it can actually only be 1:0, 0.5:0.5 or 0:1.
046         */
047        public String checkScore(PlayerGameScore[] raw);
048    
049        /**
050         * Perform adjustments on the playerscores of a game.
051         * This is useful for do some normalization of individual scores
052         * depending on total scores in a game.
053         */
054        public PlayerGameScore[] adjustScore(PlayerGameScore[] raw);
055    
056        /**
057         * Accumulate the total score of a player with the outcome of one game.
058         */
059        public PlayerScore add(PlayerScore p, PlayerGameScore pgs);
060    
061        /**
062         * Accumulate player total scores to another total for tiebreaking reasons.
063         * With the right implementation of chess scores, this results in
064         * a Buchholz score.
065         */
066        public PlayerScore addPlayers(PlayerScore p1, PlayerScore p2);
067    
068        /**
069         * Generate an initial score for a players tournament start.
070         */
071        // XXX lacks handicap mecahnism for games like Go.
072        public PlayerScore initialValue();
073    
074        /**
075         * Generate a zero score for a game with yet no outcome.
076         */
077        public PlayerGameScore zeroScore();
078    }