package votorola.a.count; // Copyright 2011-2012, 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 votorola.g.lang.*;


/** A collection of votes on a prospective issue.
  *
  *     @see <a href='http://reluk.ca/w/Category:Poll' target='_top'>Category:Poll</a>
  */
public interface Poll
{


    /** A name that is guaranteed not to designate an actual poll, though it is otherwise
      * valid as a poll name.
      *
      *     @see #name()
      *     @see <a href='http://reluk.ca/w/Sys/not-a-poll' target='_top'
      *                         >zelea.com/w/Sys/not-a-poll</a>
      */
    public static final String NOT_A_POLL = "Sys/not-a-poll";



    /** The name of the local test poll, which is {@value}.  It serves as a default in
      * some contexts.
      *
      *     @see <a href='http://reluk.ca/w/Sys/p/sandbox' target='_top'
      *                         >zelea.com/w/Sys/p/sandbox</a>
      */
    public static final String TEST_POLL_NAME = "Sys/p/sandbox";



   // - P o l l --------------------------------------------------------------------------


    /** An informal, descriptive title for the poll in wiki-style title case, or null if
      * there is none.
      *
      *     @see <a href='http://reluk.ca/w/Property:Display_title' target='_top'
      *                         >zelea.com/w/Property:Display_title</a>
      */
    public String displayTitle();



    /** The issue type of the poll, specified by the short name of its page in the
      * pollwiki, i.e. without the namespace.
      *
      *     @see <a href='http://reluk.ca/w/Property:Issue_type' target='_top'
      *                         >zelea.com/w/Property:Issue_type</a>
      */
    public String issueType();



    /** The name of the poll.
      *
      *     @see PollService#POLL_NAME_PATTERN
      *     @see votorola.a.VoterService#NAME_MAX_LENGTH
      */
    public String name();



   // ====================================================================================


    /** Poll utilities.
      */
    public @ThreadSafe static final class U
    {

        private U() {}


        /** Translates a query parameter value to a poll name.
          *
          *     @return poll name, or null if value is null.
          *
          *     @see <a href='http://reluk.ca/w/Template:PN2HTP' target='_top'
          *                                     >Template:PN2HTP</a>
          *     @see #toQuery(String)
          */
        public static String toName( final String value )
        {
            return value == null? null: value.replace( '!', '/' );
        }


        /** Translates a poll name to an HTTP query parameter value by inserting
          * exclamation marks (!) in place of slash characters (/), which are technically
          * not allowed in query parameters.
          *
          *     @see <a href='http://reluk.ca/w/Template:PN2HTP' target='_top'
          *                                     >Template:PN2HTP</a>
          *     @see #toName(String)
          */
        public static String toQuery( final String pollName )
        {
            return pollName.replace( '/', '!' );
        }

    }

}