PC2v9 API
The PC2v9 API (Application Programming Interface) is a set of Java interfaces and classes that provide a view into the contest data present on a running PC2v9 Server. Every PC2v9 distribution has API documentation (in Javadoc form); see Documentation, below.
The API's goals are to allow developers to extend PC² while maintaining integrity and security for the contest.
A developer can create a Java class that can login to a running PC2v9 Server (via the API) and then retrieve information about the contest. The API provides a developer with the ability to get information about teams, runs, clarification requests, contest problems, languages and current standings. Complete standings can be retrieved when using a Judge or Board login.
Each of these features/information is available after logging in to the PC2v9 server (via the login() method).
- Login / Logoff
- Get contest information
- Submit a run
- Submit a Clarification
- Handle events (event listeners)
- Get Run Information
- Get Clarification Information
- Get Scoring Information
See API testing module, a reference implementation.
Every PC2v9 distribution contains a set of Javadoc pages describing the elements of the PC2v9 API. The main Javadoc page can be found in the distribution at doc/api/index.html; this is the most up to date API documentation.
The API documentation provides code snippets for a number of activities including:
- Connect and login to a PC2 server
- Print data from all runs in the contest
- Print the name, site, and group of each team in the contest
- Print the names of all the currently defined contest languages
- Print the names of all the currently defined contest problems
- Print the names of all currently defined (allowable) judgements (that is, judgements which a Judge may choose to assign to a given submitted run)
In order to ensure contest integrity, access to contest information is limited/controlled based on the login used. For example, if an API client is logged in as team5 then the only run information and scoring information available will be for team5. To have access to more data, login using a scoreboard or judge account.
The following are samples (code snippets) using the API. At some future date these samples will be added into the distribution.
This sample will login and register to listen for run events. For brevity an inner class (RunListener) is created for the listener; in general the RunListener would be in its own source file.
import edu.csus.ecs.pc2.api.IContest;
import edu.csus.ecs.pc2.api.IRun;
import edu.csus.ecs.pc2.api.ServerConnection;
import edu.csus.ecs.pc2.api.exceptions.LoginFailureException;
import edu.csus.ecs.pc2.api.listener.IRunEventListener;
/**
* Sample to show how to implement a run listener.
*
* @author pc2@ecs.csus.edu
*/
public class SampleRunListener {
public SampleRunListener(String login, String password) {
loginAndRun(login, password);
}
/**
* Login and run something.
*
* @param login
* @param password
*/
private void loginAndRun(String login, String password) {
try {
ServerConnection connection = new ServerConnection();
IContest contest = connection.login(login, password);
registerForRunEvents(contest);
} catch (LoginFailureException e) {
e.printStackTrace();
}
}
/**
* An implementor for the Run Listener.
*
* See the IRunEventListener Java doc for descriptions of the events/methods.
*
* @author pc2@ecs.csus.edu
*/
protected class RunListener implements IRunEventListener {
@Override
public void runCheckedOut(IRun run, boolean isFinal) {
printRun(run);
}
@Override
public void runCompiling(IRun run, boolean isFinal) {
printRun(run);
}
@Override
public void runDeleted(IRun run) {
printRun(run);
}
@Override
public void runExecuting(IRun run, boolean isFinal) {
printRun(run);
}
@Override
public void runJudged(IRun run, boolean isFinal) {
printRun(run);
}
@Override
public void runJudgingCanceled(IRun run, boolean isFinal) {
printRun(run);
}
@Override
public void runSubmitted(IRun run) {
printRun(run);
}
@Override
public void runUpdated(IRun run, boolean isFinal) {
printRun(run);
}
@Override
public void runValidating(IRun run, boolean isFinal) {
printRun(run);
}
/**
* Prints some of the run information.
*
* @param run
*/
private void printRun(IRun run) {
System.out.print("run " + run.getNumber() + " at " + run.getSubmissionTime() + //
" by " + run.getTeam().getLoginName() + " for problem " + run.getProblem().getName() + //
" filename " + run.getSourceCodeFileNames());
if (run.isPreliminaryJudged() || run.isFinalJudged()) {
if (run.isPreliminaryJudged()) {
System.out.print(" preliminary");
}
System.out.print(" judgement " + run.getJudgementName());
}
System.out.println();
}
}
private void registerForRunEvents(IContest contest) {
contest.addRunListener(new RunListener());
}
/**
* Run the sample.
*
* @param args
* first argument login, second optional password.
*/
public static void main(String[] args) {
String login = args[0];
String password = login;
if (args.length > 1) {
password = args[1];
}
new SampleRunListener(login, password);
}
}- API testing module and pc2tapi - reference implementations.
- pc2submit - a program that uses the API to submit clars and runs.
