001package 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. 002 003import java.util.*; 004 005 006/** A positional accounting node in a delegate cascade. It records a person's input and 007 * cumulative count state in a particular poll. 008 * 009 * @see <a href='http://reluk.ca/w/Category:Position'>Category:Position</a> 010 */ 011public interface CountNode 012{ 013 014 015 // - C o u n t - N o d e -------------------------------------------------------------- 016 017 018 /** Identifies the {@linkplain Vote#getCandidateEmail() candidate selected} by the 019 * person, for whom a vote is to be cast if the person {@linkplain #isVoter() is a 020 * voter}. 021 * 022 * @return the mailish username of the candidate, or null if none was selected. 023 */ 024 public String candidateName(); 025 026 027 028 /** The maximum dart sector, or {@value}. 029 */ 030 public static final byte DART_SECTOR_MAX = 20; 031 032 033 034 /** The dart sector occupied by this node, if any. Dart sectors are used to construct 035 * user interface views that are relatively stable over long periods of time despite 036 * vote shifts. A node must be in the top {@value #DART_SECTOR_MAX} of its 037 * respective board (peers or end-candidates) in regard to vote flow in order to 038 * occupy a dart sector. The sector is assigned at random. The occupying node will 039 * not ordinarily be displaced from its assigned sector so long as it remains in the 040 * top {@value #DART_SECTOR_MAX}. This is the rule of non-displacement. An 041 * exception to the rule occurs in the case of cyclers. 042 * 043 * <p>A cycler has two roles for purposes of sectoring: voter and 044 * end-candidate. If the cycler is not among the top {@value 045 * #DART_SECTOR_MAX} of end-candidates, then she (or he) will occupy no sector in 046 * either role. Otherwise she will occupy the same sector in both roles. It is 047 * therefore possible that she (now in the role of voter) will displace a co-voting 048 * peer from a pre-occupied sector. This is the one exception to the rule of 049 * non-displacement. To illustrate, consider the cycle pictured below. If the cycle 050 * is formed by (s) casting for (c), then it is possible for one of (p) to be forced 051 * to a different dart sector.</p><pre 052 * 053 *> ( ) ( ) 054 * \ ( ) / 055 * \ | / 056 * \ | / | 057 * ( ) \|/ | vote flow 058 * \ ( )---(s) (p) V 059 * \ / \ / 060 * \ / \ / 061 * ( ) (c)----(p) 062 * \ / 063 * \ / 064 * ( )---( ) 065 * 066 * 067 * <---</pre> 068 * 069 * <p>Dart sector assignments are persisted from count to count in the voter input 070 * table. Reassignments occur at count time due to collisions from vote shifts and 071 * these are persisted individually. Where a count based on an old snapshot of the 072 * voter input is remounted, the reassignments of that count might (supposedly) 073 * clobber those of historically more recent counts. The result would be a degree of 074 * sector displacement surfacing on the next count, based on a new snapshot of the 075 * voter input. This should be corrected when voter input storage is expanded to 076 * include historical vote shifts and other changes of vote data, as sector 077 * reassignments would then be recorded in historical sequence.</p> 078 * 079 * <p id='ackT'>Acknowledgement: Dart sectoring was first proposed by Thomas von der Elbe. 080 * See Start/Metagov 081 * <a href='http://metagovernment.org/pipermail/start_metagovernment.org/2011-April/003824.html' 082 * target='_top'>2011-April/003824</a>.</p> 083 * 084 * @return a value of 1 to {@value #DART_SECTOR_MAX}, or zero if this node 085 * occupies no dart sector. 086 */ 087 public byte dartSector(); 088 089 090 091 /** The number of other nodes that name this node as a candidate. 092 */ 093 public Long directVoterCount(); // primitive long would be problematic for gwt/CountNodeJS 094 095 096 097 /** The display title of the person's position, or null if there is none. 098 * 099 * @see <a href='http://reluk.ca/w/Property:Display_title' target='_top' 100 * >Property:Display_title</a> 101 */ 102 public String displayTitle(); 103 104 105 106 /** Answers whether this node is a root candidate or a cycler. 107 * 108 * @see <a href='http://reluk.ca/w/Stuff:Votorola/glossary#base_candidate' target='_top' 109 * >glossary#base_candidate</a> 110 */ 111 public boolean isBaseCandidate(); 112 113 114 115 /** Answers whether this node has a voter. 116 * 117 * @see <a href='http://reluk.ca/w/Stuff:Votorola/glossary#candidate' target='_top' 118 * >glossary#candidate</a> 119 */ 120 public boolean isCandidate(); 121 122 123 124 /** Answers whether this node is voting for a voter of it's own, directly or 125 * indirectly. 126 * 127 * @see <a href='http://reluk.ca/w/Stuff:Votorola/glossary#cycler' target='_top' 128 * >glossary#cycler</a> 129 */ 130 public boolean isCycler(); 131 132 133 134 /** Answers whether this node is a candidate who is not a voter. 135 * 136 * @see <a href='http://reluk.ca/w/Stuff:Votorola/glossary#root_candidate' target='_top' 137 * >glossary#root_candidate</a> 138 */ 139 public boolean isRootCandidate(); 140 141 142 143 /** Answers whether the {@linkplain #candidateName() candidate} is non-null and 144 * non-identical with the {@linkplain #name() person}. One may vote for oneself only 145 * in a manner of speaking, because such a "vote" is actually a "null cycle, 146 * equivalent to a withheld vote." Here it is accounted as not voting at all. 147 * Meanwhile, a {@linkplain CountNodeW#voteWeight() zero-weight} vote for another 148 * person, even if it happens to carry no other votes along with it, is nevertheless 149 * accounted as voting; although it cannot affect the count in the present, it will 150 * affect the count in future if this node ever receives (and thus carries) a weight 151 * of votes. 152 * 153 * @see <a href='http://reluk.ca/project/votorola/d/theory.xht#cycle' target='_top' 154 * >theory.xht#cycle</a> 155 */ 156 public boolean isVoter(); 157 158 159 160 /** The mailish username of the person for whom this node accounts. 161 */ 162 public String name(); 163 164 165}