Difference between revisions of "API"

From PC2wiki
Jump to: navigation, search
m (API Features: add sections)
m (Get Clarification Information: added section)
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
The PC² API (Application Programming Interface) is a set of Java interfaces and classes
 
The PC² API (Application Programming Interface) is a set of Java interfaces and classes
that provide a view into the contest data.
+
that provide a view into the contest data.  Every pc2 distribution has documentation (javadoc form,
 +
see [[#Documentation|Documentation]] below).
  
 
The API's goals are to allow developers to extend PC² while keeping complete
 
The API's goals are to allow developers to extend PC² while keeping complete
Line 11: Line 12:
  
 
==API Features==
 
==API Features==
 +
 +
Each of these features/information is available after logging in to the pc2 server (via the login() method).
  
 
=== Login / Logoff ===
 
=== Login / Logoff ===
Line 18: Line 21:
 
=== Submit a [[run]]===
 
=== Submit a [[run]]===
  
=== Submit a [[Clarification]] ([[Version 9.3]])===
+
=== Submit a [[Clarification]] ===
  
=== Listeners===
+
Added to the API in [[Version 9.3]] Build 2591.
  
=== Handle events live===
+
=== Handle events live (event listeners)===
  
 
=== Get Run Information===
 
=== Get Run Information===
  
 
=== Get Clarification Information===
 
=== Get Clarification Information===
 +
 +
=== Get Scoring Information ===
 +
 +
==Debugging tools==
 +
 +
See [[API testing module]], a reference implementation.
  
 
==Documentation==
 
==Documentation==
Line 32: Line 41:
 
The API javadoc was added into the distribution in version 9.1.3 build 1899.
 
The API javadoc was added into the distribution in version 9.1.3 build 1899.
  
The main Java doc page is each distribution at doc/api/index.html.
+
The main Java doc page is each distribution at <tt>doc/api/index.html</tt> this
 +
is the most up to date API documentation.
 +
 
 +
An older copy of the API is on-line at: http://pc2.ecs.csus.edu/api
  
 
The API provides code snippets for a number of activities including:
 
The API provides code snippets for a number of activities including:
Line 42: Line 54:
 
# Print the names of all currently defined (allowable) judgements (that is, judgements which a Judge may choose to assign to a given submitted run)
 
# Print the names of all currently defined (allowable) judgements (that is, judgements which a Judge may choose to assign to a given submitted run)
  
==Status==
+
==Security==
 
 
The API provides developers the ability to access and extend pc2.
 
The API supports the following features:
 
 
 
# Login/Logoff
 
# Submit a run
 
# Submit a clar ([[Version 9.3]])
 
# Add listeners to respond to events (run submitted, judged, etc.) as they occur
 
# Get contest information
 
# Get run info (judgements, status, etc)
 
# Get clarification info (answers, status, etc).
 
# Get scoring information
 
  
 
To ensure contest integrity there may be limited access to information
 
To ensure contest integrity there may be limited access to information
Line 61: Line 61:
 
To have access to more data use a scoreboard or judge login account.
 
To have access to more data use a scoreboard or judge login account.
  
The [[pc2submit]] script/program is written using the API.
+
==Future enhancements==
 
 
===Future enhancements===
 
  
 
The following bugs/enhancements are in the pc2 Bugzilla:
 
The following bugs/enhancements are in the pc2 Bugzilla:
Line 222: Line 220:
 
=See Also=
 
=See Also=
 
* [[Version 9]]
 
* [[Version 9]]
 +
* [[API testing module]] and [[pc2tapi]] - reference implementation
 +
* [[pc2submit]] - a program that uses the API to submit clars and runs.
 +
 +
[[Category:Version 9.3]]

Latest revision as of 22:09, 20 January 2013

The PC² API (Application Programming Interface) is a set of Java interfaces and classes that provide a view into the contest data. Every pc2 distribution has documentation (javadoc form, see Documentation below).

The API's goals are to allow developers to extend PC² while keeping complete integrity and security for the contest.

A developer will be able to create a Java class that can login and then retrieve information about the contest. The API provides a developer to get information about team's, runs, problems, languages and the standings. Complete standings can be retrieved when using a Judge or Board login.

API Features

Each of these features/information is available after logging in to the pc2 server (via the login() method).

Login / Logoff

Get contest information

Submit a run

Submit a Clarification

Added to the API in Version 9.3 Build 2591.

Handle events live (event listeners)

Get Run Information

Get Clarification Information

Get Scoring Information

Debugging tools

See API testing module, a reference implementation.

Documentation

The API javadoc was added into the distribution in version 9.1.3 build 1899.

The main Java doc page is each distribution at doc/api/index.html this is the most up to date API documentation.

An older copy of the API is on-line at: http://pc2.ecs.csus.edu/api

The API provides code snippets for a number of activities including:

  1. Connect and login to a PC2 server
  2. Print data from all runs in the contest
  3. Print the name, site, and group of each team in the contest
  4. Print the names of all the currently defined contest languages
  5. Print the names of all the currently defined contest problems
  6. Print the names of all currently defined (allowable) judgements (that is, judgements which a Judge may choose to assign to a given submitted run)

Security

To ensure contest integrity there may be limited access to information depending on the login used. For example, if logged in as team5 the only run information and scoring information available will be fore team5. To have access to more data use a scoreboard or judge login account.

Future enhancements

The following bugs/enhancements are in the pc2 Bugzilla:

  • Bug 570 Implement "adduser" function in API

A complete list of all API bugs can be found by clicking here

API Samples

These are a number of samples/snippets using the API.

At some future date these samples will be added into the distribution.

Run Listener Sample

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);

    }
}

See Also