edu.csus.ecs.pc2.api

## Interface IContest

-     public interface IContest

  This interface represents the PC2 API view of the contest information available to a client connected to a PC2 server through the API.

  This documentation describes the current draft of the PC2 API, which is subject to change.

  Version:
    $Id$
  Author:
    pc2@ecs.csus.edu

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addClarificationListener(IClarificationEventListener clarificationEventListener)` Add a Clarification Event listener to contest.
    `void` | `addConnectionListener(IConnectionEventListener connectionEventListener)` Add a Connection Event listener to the contest.
    `void` | `addContestConfigurationUpdateListener(IConfigurationUpdateListener contestConfigurationUpdateListener)` Add a Contest Configuration Update listener to the contest.
    `void` | `addRunListener(IRunEventListener runEventListener)` Add a Run Event listener to the contest.
    `IProblem[]` | `getAllProblems()` Get an ordered list of all contest problems (hidden or non-hidden).
    `String` | `getBuildNumber()` Get PC^2 Build number.
    `IProblem[]` | `getClarificationCategories()` Get an ordered list of all currently defined clarification categories.
    `IClarification[]` | `getClarifications()` Get a list of all the clarifications in the contest.
    `IClient[]` | `getClients()` Get all this site's clients.
    `IClient[]` | `getClientsAllSites()` Get all clients from all sites.
    `IContestClock` | `getContestClock()` Get an `IContestClock` object containing contest time-related information.
    `String` | `getContestTitle()` Get the contest title.
    `String` | `getFullVersionString()` Get Full PC^2 version string.
    `IGroup[]` | `getGroups()` Get a list of the groups currently defined in the contest.
    `IJudgement[]` | `getJudgements()` Get a list of all currently-defined (i.e., possible) judgements.
    `ILanguage[]` | `getLanguages()` Get a list of all currently defined contest languages.
    `String` | `getMajorVersion()` Get PC^2 Major version.
    `String` | `getMinorVersion()` Get PC^2 Minor version number.
    `IClient` | `getMyClient()` Get the current logged in client.
    `String` | `getOtherVersionInfo()` Get extra version info.
    `IProblemDetails[]` | `getProblemDetails()` Get all the problem details.
    `IProblem[]` | `getProblems()` Get an ordered list of all currently defined contest problems.
    `IRun` | `getRun(int runNumber)` Get single run by runNumber from the current site.
    `IRun` | `getRun(int siteNumber, int runNumber)` Get a run from a site.
    `IRun[]` | `getRuns()` Get a list of all the runs in the contest.
    `RunStates` | `getRunState(IRun run)` Get run state for a run (judge or admin only).
    `String` | `getServerHostName()` Returns name of the host (server) this application is using.
    `int` | `getServerPort()` Returns the port number for the host (server) this application is using.
    `String` | `getSiteName()` Get the name of the contest site for the PC2 server to which this client is currently connected.
    `String` | `getSiteName(int siteNumber)` Get the name for the specified contest site.
    `ISite[]` | `getSites()` Get an ordered list of all currently defined contest sites.
    `IStanding` | `getStanding(ITeam team)` Returns an `IStanding` describing the current standing of the specified team in the contest as determined by the currently active implementation of the PC2 scoring algorithm.
    `IStanding[]` | `getStandings()` Returns an array of `IStanding`s describing the current standing of every team in the contest as determined by the currently active plugin implementation of the PC2 scoring algorithm.
    `ITeam[]` | `getTeams()` Gets all the teams in the contest.
    `boolean` | `isCCSTestMode()` Returns true if in CCS Test Mode.
    `boolean` | `isContestClockRunning()` Returns a boolean value indicating whether the contest clock is currently running.
    `void` | `removeClarificationListener(IClarificationEventListener clarificationEventListener)` Remove the specified clarification event listener from the contest.
    `void` | `removeConnectionListener(IConnectionEventListener connectionEventListener)` Remove the specified connection event listener from the contest.
    `void` | `removeContestConfigurationUpdateListener(IConfigurationUpdateListener contestConfigurationUpdateListener)` Remove the specified Contest Configuration Update listener from the contest.
    `void` | `removeRunListener(IRunEventListener runEventListener)` Remove the specified run event listener from the contest.

- - ### Method Detail

    - #### getTeams

          ITeam[] getTeams()

      Gets all the teams in the contest. Returns an array of `ITeam` objects, where each `ITeam` element describes one Team account in the contest. Note that the returned array contains one entry for every Team account which is currently defined, whether or not that team is currently logged in to the contest via PC2. Note also that in a multi-site contest the returned array contains an entry for every account at every site, not just for the site for the server to which the client is currently connected.

      The following code snippet shows typical usage for obtaining and printing a list of all teams currently in the contest. It assumes variable `contest` represents a valid `IContest` obtained from a server to which this client is connected.

           for (ITeam team : contest.getTeams()) {
               String teamName = team.getDisplayName();
               int siteNumber = team.getSiteNumber();
               String groupName = team.getGroup().getName();
               System.out.println(teamName + " Site: " + siteNumber + " Group: " + groupName);
           }

      Returns:
        an unordered array of `ITeam`s, one for each team account defined in the contest.

    - #### getSiteName

          String getSiteName(int siteNumber)

      Get the name for the specified contest site.
      Parameters:
        `siteNumber` - The number of a site in the contest.
      Returns:
        A String containing the name of the specified contest site.

    - #### getContestTitle

          String getContestTitle()

      Get the contest title. The contest title is configured by the Contest Administrator using the PC2 "Admin" module.
      Returns:
        A String containing the title of the contest.

    - #### getSiteName

          String getSiteName()

      Get the name of the contest site for the PC2 server to which this client is currently connected.
      Returns:
        the current server's site name.

    - #### getLanguages

          ILanguage[] getLanguages()

      Get a list of all currently defined contest languages. Returns an array containing one `ILanguage` for each currently defined contest language. The languages in the returned array are always ordered in the order in which the Contest Administrator entered them into the contest: element [0] is the first language, etc.

      The following code snippet shows typical usage for obtaining and printing the names of all languages currently defined in the contest. It assumes variable `contest` represents a valid `IContest` obtained from a server to which this client is connected.

           for (ILanguage language : contest.getLanguages()) {
               System.out.println(language.getName());
           }

      Returns:
        An array of `ILanguage`s, one for each language defined in the contest.

    - #### getProblems

          IProblem[] getProblems()

      Get an ordered list of all currently defined contest problems. Returns an array containing one `IProblem` for each currently defined/active contest problem. The problems in the returned array are always ordered in the order in which the Contest Administrator entered them into the contest: element [0] is the first problem, etc.

      The following code snippet shows typical usage for obtaining and printing the names of all problems currently defined in the contest. It assumes variable `contest` represents a valid `IContest` obtained from a server to which this client is connected.

           for (IProblem problem : contest.getProblems()) {
               System.out.println(problem.getName());
           }

      Returns:
        An array containing one `IProblem` for each currently defined (non-hidden) contest problem.

    - #### getAllProblems

          IProblem[] getAllProblems()

      Get an ordered list of all contest problems (hidden or non-hidden).
      Returns:
        An array containing one `IProblem` for each currently defined contest problem.
      See Also:
        `getProblems()`

    - #### getClarificationCategories

          IProblem[] getClarificationCategories()

      Get an ordered list of all currently defined clarification categories.

           // list all clarification categories and problems.

      for (IProblem problem : contest.getClarificationCategories()) { System.out.println(problem.getName()); } for (IProblem problem : contest.getProblems()) { System.out.println(problem.getName()); }
      Returns:
        An array containing one `IProblem` for each defined clarification category.

    - #### getSites

          ISite[] getSites()

      Get an ordered list of all currently defined contest sites. Returns an array containing one `ISite` for each currently defined contest site. The sites in the returned array are always ordered in the order in which the Contest Administrator defined them in the contest: element [0] is the first site, etc.
      Returns:
        An array containing one `ISite` for each currently defined contest site.

    - #### getJudgements

          IJudgement[] getJudgements()

      Get a list of all currently-defined (i.e., possible) judgements. Note that this refers to the Judgement values which the Contest Administrator has configured into the contest settings (i.e., the list of judgement results from which a Judge may choose when assigning a result to any particular submitted run); it is not related to the specific judgements which may have been assigned to any particular run.

      Returns an array containing one `IJudgement` for each currently defined allowable Judge's response to a submitted run. The returned `IJudgement`s are given in the array in the order in which they were defined by the Contest Administrator.

      The following code snippet shows typical usage for obtaining and printing the names of all Judgements currently defined in the contest. It assumes variable `contest` represents a valid `IContest` obtained from a server to which this client is connected.

           for (IJudgement judgement : contest.getJudgements()) {
               System.out.println(judgement.getName());
           }

      Returns:
        An ordered array containing one `IJudgement` for each currently defined allowable Judge's response to a submitted run.

    - #### getRuns

          IRun[] getRuns()

      Get a list of all the runs in the contest. Returns an array of `IRun`s, where each element of the array holds a single contest `IRun`. In a multi-site contest the returned array will contain the runs from all connected sites, not just the site for the server to which this client is connected.

      The following code snippet shows typical usage for obtaining and printing a list of all runs currently in the contest. It assumes variable `contest` represents a valid `IContest` obtained from a server to which this client is connected.

           for (IRun run : contest.getRuns()) {

               System.out.println("Run " + run.getNumber() + " from site " + run.getSiteNumber());
               System.out.println("    submitted at " + run.getSubmissionTime() + " minutes by " + run.getTeam().getDisplayName());
               System.out.println("    For problem " + run.getProblem().getName());
               System.out.println("    Written in " + run.getLanguage().getName());

               if (run.isFinalJudged()) {
                   System.out.println("    Judgement: " + run.getJudgementName());
               } else {
                   System.out.println("    Judgement: not judged yet ");
               }
           }

      Returns:
        An unordered list of Runs for all sites currently connected to the contest.

    - #### getRun

          IRun getRun(int runNumber)

      Get single run by runNumber from the current site.
      Parameters:
        `runNumber` - the number of the run to be fetched
      Returns:
        the IRun or null if no such run exists.

    - #### getClarifications

          IClarification[] getClarifications()

      Get a list of all the clarifications in the contest.
      Returns:
        An unordered list of Clarifications for all sites connected to the contest.

    - #### addRunListener

          void addRunListener(IRunEventListener runEventListener)

      Add a Run Event listener to the contest. A run event listener (object of type `IRunEventListener`) will be invoked every time a run is added to the contest, modified (e.g. Judged), or marked as deleted from the contest. Custom clients using the PC2 API can therefore arrange to be notified when any of these conditions occurs.
      Parameters:
        `runEventListener` - an `IRunEventListener` listener for Run events
      See Also:
        `IRunEventListener`, `IRun`

    - #### removeRunListener

          void removeRunListener(IRunEventListener runEventListener)

      Remove the specified run event listener from the contest.
      Parameters:
        `runEventListener` - The `IRunEventListener` listener to be removed.

    - #### addConnectionListener

          void addConnectionListener(IConnectionEventListener connectionEventListener)

      Add a Connection Event listener to the contest. A connection event listener (object of type `IConnectionEventListener`) will be invoked every time a connection to the server has been dropped, this client is no longer logged in.
      Parameters:
        `connectionEventListener` - the IConnectionEventListener to be added

    - #### removeConnectionListener

          void removeConnectionListener(IConnectionEventListener connectionEventListener)

      Remove the specified connection event listener from the contest.
      Parameters:
        `connectionEventListener` - The `IConnectionEventListener` listener to be removed.

    - #### removeClarificationListener

          void removeClarificationListener(IClarificationEventListener clarificationEventListener)

      Remove the specified clarification event listener from the contest.
      Parameters:
        `clarificationEventListener` - the IClarificationEventListener to be added

    - #### addClarificationListener

          void addClarificationListener(IClarificationEventListener clarificationEventListener)

      Add a Clarification Event listener to contest. A clarification event listener (object of type `IClarificationEventListener`) will be invoked every time a clarification is added to the contest, modified (e.g. Answered), or marked as deleted from the contest. Custom clients using the PC2 API can therefore arrange to be notified when any of these conditions occurs.
      Parameters:
        `clarificationEventListener` - an `IClarificationEventListener` listener for Clarification events.
      See Also:
        `IClarificationEventListener`, `IClarification`

    - #### addContestConfigurationUpdateListener

          void addContestConfigurationUpdateListener(IConfigurationUpdateListener contestConfigurationUpdateListener)

      Add a Contest Configuration Update listener to the contest. A configuration update listener (object of type `IConfigurationUpdateListener`) will be invoked every time a contest configuration item is added, modified, or removed from the contest. Custom clients using the PC2 API can therefore arrange to be notified when any of these conditions occurs.
      Parameters:
        `contestConfigurationUpdateListener` - an `IConfigurationUpdateListener` listener for configuration update events
      See Also:
        `IConfigurationUpdateListener`, `ContestEvent`

    - #### removeContestConfigurationUpdateListener

          void removeContestConfigurationUpdateListener(IConfigurationUpdateListener contestConfigurationUpdateListener)

      Remove the specified Contest Configuration Update listener from the contest.
      Parameters:
        `contestConfigurationUpdateListener` - The `IConfigurationUpdateListener` listener to be removed.

    - #### getContestClock

          IContestClock getContestClock()

      Get an `IContestClock` object containing contest time-related information. The `IContestClock` object can be queried for values such as the amount of time elasped so far in the contest, the amount of time remaining in the contest, and whether the contest clock is currently "paused" or not.

      Note that the `IContestClock` object returned by the current implementation of this method is static; it does not dynamically update. In other words, obtaining the current contest time requires obtaining a new `IContestClock` object each time the current time information is needed.

      Returns:
        A `IContestClock` object containing contest time information
      See Also:
        `IContestClock`

    - #### getGroups

          IGroup[] getGroups()

      Get a list of the groups currently defined in the contest. Groups can be used by the Contest Administrator to associate Teams together. For example, all teams from a certain geographical region, or with an equivalent background (say, Undergraduate vs. Graduate) can be put together in the same group. The PC2 scoring algorithm implementation can then be used to compute standings on a per-group basis.
      Returns:
        list of groups.
      See Also:
        `IGroup`

    - #### getMyClient

          IClient getMyClient()

      Get the current logged in client. This method can be used by a custom client making use of the PC2 API to obtain at runtime a PC2 `IClient` description of its own client login data.
      Returns:
        the ICLient object for the currently logged-in client

    - #### isContestClockRunning

          boolean isContestClockRunning()

      Returns a boolean value indicating whether the contest clock is currently running. If the method returns false, either the contest has not been started, or it has been started and then paused by the Contest Administrator. Method `getContestClock()` can be used to obtain clock information to determine which case exists (not yet started vs. paused.)
      Returns:
        true if the contest clock is currently running; false otherwise.

    - #### isCCSTestMode

          boolean isCCSTestMode()

      Returns true if in CCS Test Mode. CCS Test mode allows the override of the elapsed (contest) time, the test mode is set in the Contest Information Tab on the Admin.
      Returns:
        true if in CCS test mode, false otherwise.

    - #### getStanding

          IStanding getStanding(ITeam team)

      Returns an `IStanding` describing the current standing of the specified team in the contest as determined by the currently active implementation of the PC2 scoring algorithm.

      Note that the determination of the data in an `IStanding` is up to the scoring algorithm, which can be dynamically changed by the Contest Administrator during a contest. Note also that scoring details such as how to rank teams that are tied is also a function of the scoring algorithm.

      Parameters:
        `team` - The `ITeam` for which an `IStanding` is being requested.
      Returns:
        An `IStanding` for the specified team.

    - #### getStandings

          IStanding[] getStandings()

      Returns an array of `IStanding`s describing the current standing of every team in the contest as determined by the currently active plugin implementation of the PC2 scoring algorithm.

      Note that the determination of the data in an `IStanding` is up to the scoring algorithm, which can be dynamically changed by the Contest Administrator during a contest. Note also that scoring details such as how to rank teams that are tied is also a function of the scoring algorithm.

      In addition, note also that the order in which the `IStanding`s are contained in the returned array is a function of the scoring algorithm. In particular, while the default PC2 scoring algorithm provides `IStanding`s in ranked order, scoring algorithm implementations are not required to do so.

           for (IStanding standingRank : contest.getStandings()) {
               String displayName = standingRank.getClient().getDisplayName();
               System.out.printf(" %3d %-35s %2d %4d", standingRank.getRank(), displayName, standingRank.getNumProblemsSolved(), standingRank.getPenaltyPoints());
           }

      Returns:
        An array of `IStanding`s, one element for each contest team.

    - #### getServerHostName

          String getServerHostName()

      Returns name of the host (server) this application is using.
      Returns:
        name of server host computer.

    - #### getServerPort

          int getServerPort()

      Returns the port number for the host (server) this application is using.
      Returns:
        port number for port.

    - #### getProblemDetails

          IProblemDetails[] getProblemDetails()

      Get all the problem details.
      Returns:
        problem details for all teams sorted by site, team and then problem.

    - #### getClientsAllSites

          IClient[] getClientsAllSites()

      Get all clients from all sites.
      Returns:
        a list of clients from all sites.

    - #### getClients

          IClient[] getClients()

      Get all this site's clients.
      Returns:
        a list of clients from this site.

    - #### getRunState

          RunStates getRunState(IRun run)

      Get run state for a run (judge or admin only).
      Parameters:
        `run` - the IRun whose state is to be fetched
      Returns:
        run state

    - #### getMajorVersion

          String getMajorVersion()

      Get PC^2 Major version. For "9.3Beta" would be "9"
      Returns:
        the "Major version number" of this version of PC^2

    - #### getMinorVersion

          String getMinorVersion()

      Get PC^2 Minor version number. For "9.3Beta" would be "3"
      Returns:
        the "minor version number" of this version of PC^2

    - #### getBuildNumber

          String getBuildNumber()

      Get PC^2 Build number.
      Returns:
        build number.

    - #### getFullVersionString

          String getFullVersionString()

      Get Full PC^2 version string.

      Example:

          Version 9.3 20150205 (Thursday, February 5th 2015 15:55 UTC) build 2920

      Returns:
        a String containing the full PC^2 version string for this version of PC^2

    - #### getOtherVersionInfo

          String getOtherVersionInfo()

      Get extra version info. Get anything after the minor version number.
      For ""9.3Beta"" would be "Beta"
      Returns:
        extra version info

    - #### getRun

          IRun getRun(int siteNumber,
                      int runNumber)

      Get a run from a site.
      Parameters:
        `siteNumber` - the site from which the run should be fetched
        `runNumber` - the ID number of the Run to be fetched
      Returns:
        an IRun object describing the requested run