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 2107 2010-09-02 00:31:35Z laned $
Author:
pc2@ecs.csus.edu

Method Summary
 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.
 IProblemDetails[] getProblemDetails()
          Get all the problem details.
 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 IStandings 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 ITeams, 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 ILanguages, 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 IJudgements 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 IRuns, 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.

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 IStandings 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 IStandings are contained in the returned array is a function of the scoring algorithm. In particular, while the default PC2 scoring algorithm provides IStandings 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 IStandings, 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.