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: IContest.java 1746 2009-01-13 05:20:50Z laned $
  Author:
    pc2@ecs.csus.edu

- - ### Method Summary

    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.
    `IClarification[]` | `getClarifications()` Get a list of all the clarifications in the contest.
    `IContestClock` | `getContestClock()` Get an `IContestClock` object containing contest time-related information.
    `String` | `getContestTitle()` Get the contest title.
    `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.
    `IClient` | `getMyClient()` Get the current logged in client.
    `IProblem[]` | `getProblems()` Get an ordered list of all currently defined contest problems.
    `IRun[]` | `getRuns()` Get a list of all the runs in the contest.
    `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` | `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 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 contest problem.

    - #### 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.isJudged()) {
                   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.

    - #### 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` -

    - #### 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` -

    - #### 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.

    - #### 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.

    - #### 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.

      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.