package votorola.a.count; // Copyright 2011-2013, Michael Allan.  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Votorola Software"), to deal in the Votorola Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicence, and/or sell copies of the Votorola Software, and to permit persons to whom the Votorola Software is furnished to do so, subject to the following conditions: The preceding copyright notice and this permission notice shall be included in all copies or substantial portions of the Votorola Software. THE VOTOROLA SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE VOTOROLA SOFTWARE OR THE USE OR OTHER DEALINGS IN THE VOTOROLA SOFTWARE.

import java.util.*;


/** A positional accounting node in a delegate cascade.  It records a person's input and
  * cumulative count state in a particular poll.
  *
  *     @see <a href='http://reluk.ca/w/Category:Position'>Category:Position</a>
  */
public interface CountNode
{


   // - C o u n t - N o d e --------------------------------------------------------------


    /** Identifies the {@linkplain Vote#getCandidateEmail() candidate selected} by the
      * person, for whom a vote is to be cast if the person {@linkplain #isVoter() is a
      * voter}.
      *
      *     @return the mailish username of the candidate, or null if none was selected.
      */
    public String candidateName();



    /** The maximum dart sector, or {@value}.
      */
    public static final byte DART_SECTOR_MAX = 20;



    /** The dart sector occupied by this node, if any.  Dart sectors are used to construct
      * user interface views that are relatively stable over long periods of time despite
      * vote shifts.  A node must be in the top {@value #DART_SECTOR_MAX} of its
      * respective board (peers or end-candidates) in regard to vote flow in order to
      * occupy a dart sector.  The sector is assigned at random.  The occupying node will
      * not ordinarily be displaced from its assigned sector so long as it remains in the
      * top {@value #DART_SECTOR_MAX}.  This is the rule of non-displacement.  An
      * exception to the rule occurs in the case of cyclers.
      *
      * <p>A cycler has two roles for purposes of sectoring: voter and
      * end-candidate.  If the cycler is not among the top {@value
      * #DART_SECTOR_MAX} of end-candidates, then she (or he) will occupy no sector in
      * either role.  Otherwise she will occupy the same sector in both roles.  It is
      * therefore possible that she (now in the role of voter) will displace a co-voting
      * peer from a pre-occupied sector.  This is the one exception to the rule of
      * non-displacement.  To illustrate, consider the cycle pictured below.  If the cycle
      * is formed by (s) casting for (c), then it is possible for one of (p) to be forced
      * to a different dart sector.</p><pre
      *
     *>           ( )       ( )
      *             \  ( )  /
      *              \  |  /
      *               \ | /          |
      *   ( )          \|/           | vote flow
      *     \    ( )---(s)   (p)     V
      *      \   /       \   /
      *       \ /         \ /
      *       ( )         (c)----(p)
      *         \         /
      *          \       /
      *          ( )---( )
      *
      *
      *               <---</pre>
      *
      * <p>Dart sector assignments are persisted from count to count in the voter input
      * table.  Reassignments occur at count time due to collisions from vote shifts and
      * these are persisted individually.  Where a count based on an old snapshot of the
      * voter input is remounted, the reassignments of that count might (supposedly)
      * clobber those of historically more recent counts.  The result would be a degree of
      * sector displacement surfacing on the next count, based on a new snapshot of the
      * voter input.  This should be corrected when voter input storage is expanded to
      * include historical vote shifts and other changes of vote data, as sector
      * reassignments would then be recorded in historical sequence.</p>
      *
      * <p id='ackT'>Acknowledgement: Dart sectoring was first proposed by Thomas von der Elbe.
      * See Start/Metagov
      * <a href='http://metagovernment.org/pipermail/start_metagovernment.org/2011-April/003824.html'
      * target='_top'>2011-April/003824</a>.</p>
      *
      *     @return a value of 1 to {@value #DART_SECTOR_MAX}, or zero if this node
      *       occupies no dart sector.
      */
    public byte dartSector();



    /** The number of other nodes that name this node as a candidate.
      */
    public Long directVoterCount(); // primitive long would be problematic for gwt/CountNodeJS



    /** The display title of the person's position, or null if there is none.
      *
      *     @see <a href='http://reluk.ca/w/Property:Display_title' target='_top'
      *                                     >Property:Display_title</a>
      */
    public String displayTitle();



    /** Answers whether this node is a root candidate or a cycler.
      *
      *     @see <a href='http://reluk.ca/w/Stuff:Votorola/glossary#base_candidate' target='_top'
      *                                                    >glossary#base_candidate</a>
      */
    public boolean isBaseCandidate();



    /** Answers whether this node has a voter.
      *
      *     @see <a href='http://reluk.ca/w/Stuff:Votorola/glossary#candidate' target='_top'
      *                                                    >glossary#candidate</a>
      */
    public boolean isCandidate();



    /** Answers whether this node is voting for a voter of it's own, directly or
      * indirectly.
      *
      *     @see <a href='http://reluk.ca/w/Stuff:Votorola/glossary#cycler' target='_top'
      *                                                    >glossary#cycler</a>
      */
    public boolean isCycler();



    /** Answers whether this node is a candidate who is not a voter.
      *
      *     @see <a href='http://reluk.ca/w/Stuff:Votorola/glossary#root_candidate' target='_top'
      *                                                    >glossary#root_candidate</a>
      */
    public boolean isRootCandidate();



    /** Answers whether the {@linkplain #candidateName() candidate} is non-null and
      * non-identical with the {@linkplain #name() person}.  One may vote for oneself only
      * in a manner of speaking, because such a "vote" is actually a "null cycle,
      * equivalent to a withheld vote."  Here it is accounted as not voting at all.
      * Meanwhile, a {@linkplain CountNodeW#voteWeight() zero-weight} vote for another
      * person, even if it happens to carry no other votes along with it, is nevertheless
      * accounted as voting; although it cannot affect the count in the present, it will
      * affect the count in future if this node ever receives (and thus carries) a weight
      * of votes.
      *
      *     @see <a href='http://reluk.ca/project/votorola/d/theory.xht#cycle' target='_top'
      *                                                      >theory.xht#cycle</a>
      */
    public boolean isVoter();



    /** The mailish username of the person for whom this node accounts.
      */
    public String name();


}