edu.csus.ecs.pc2.api

Interface IContest

public interface IContest

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

This documentation describes the current draft of the PC² 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 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 PC². 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 PC² "Admin" module.

Returns:

A String containing the title of the contest.

getSiteName

String getSiteName()

Get the name of the contest site for the PC² 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.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 PC² 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 PC² 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 PC² 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 PC² 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 PC² API to obtain at runtime a PC² 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 PC² 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 PC² 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 PC² scoring algorithm provides IStandings in ranked order, scoring algorithm implementations are not required to do so.

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.