edu.csus.ecs.pc2.api.listener
Interface IRunEventListener


public interface IRunEventListener

This interface describes the set of methods that any Run Listener must implement.

These methods are invoked when a run has been added, removed (marked as deleted), judged, or updated in the contest. A client utilizing the PC2 API can implement this interface and add itself to the contest as a Listener, and therefore arrange to be notified when any runs are added to, modified, or removed from the contest.

There is no guarantee that these events will appear in the order described below. The system is a asynchronous system (Threads) and many factors can affect the order which these events occur.

Run Flow - if Admin selects "Send Additional Run Status Information" to OFF

  1. runSubmitted(IRun)
  2. runCheckedOut(IRun, boolean)
  3. runJudged(IRun, boolean) typically, but also can be: runJudgingCanceled(IRun, boolean) or runDeleted(IRun) or runUpdated(IRun, boolean).
Run Flow - if Admin selects "Send Additional Run Status Information" to ON.
  1. runSubmitted(IRun)
  2. runCheckedOut(IRun, boolean)
  3. runCompiling(IRun, boolean)
  4. runExecuting(IRun, boolean)
  5. runValidating(IRun, boolean)
  6. runJudged(IRun, boolean) typically, but also can be: runJudgingCanceled(IRun, boolean) or runDeleted(IRun) or runUpdated(IRun, boolean).

Note that the events runCompiling(IRun, boolean), runExecuting(IRun, boolean) and runValidating(IRun, boolean) can appear in any order

Note 2 - runExecuting(IRun, boolean) and runValidating(IRun, boolean) are optional, if the preceeding step fails or does not create output then these states may never be reached.

This documentation describes the current draft of the PC2 API, which is subject to change.

Version:
$Id: IRunEventListener.java 1748 2009-01-14 05:51:38Z laned $
Author:
pc2@ecs.csus.edu

Method Summary
 void runCheckedOut(IRun run, boolean isFinal)
          Invoked when a run has been checked by a judge.
 void runCompiling(IRun run, boolean isFinal)
          Invoked when an existing run is being compiled.
 void runDeleted(IRun run)
          Invoked when an existing run has been deleted from the contest (marked as deleted by the Contest Administrator).
 void runExecuting(IRun run, boolean isFinal)
          Invoked when an existing run is being executed.
 void runJudged(IRun run, boolean isFinal)
          Invoked when an existing run has been judged; that is, has had a Judgement applied to it.
 void runJudgingCanceled(IRun run, boolean isFinal)
          Invoked if the run is re-queued for judgement.
 void runSubmitted(IRun run)
          Invoked when a new run has been added to the contest.
 void runUpdated(IRun run, boolean isFinal)
          Invoked when an existing run has been updated (modified) in some way.
 void runValidating(IRun run, boolean isFinal)
          Invoked when an existing run is being validated.
 

Method Detail

runSubmitted

void runSubmitted(IRun run)
Invoked when a new run has been added to the contest.

Typically this means that a run has been submitted by a team; it may also may be caused by a remote server in a multi-site contest sending its run(s) to the local server.

The added run may have been originally entered into the contest on either the local server (the server to which this client is connected) or on a remote server.

Parameters:
run - the IRun that has been added to the contest

runDeleted

void runDeleted(IRun run)
Invoked when an existing run has been deleted from the contest (marked as deleted by the Contest Administrator).

Parameters:
run - the deleted IRun

runCheckedOut

void runCheckedOut(IRun run,
                   boolean isFinal)
Invoked when a run has been checked by a judge.

Parameters:
run -
isFinal - true if this is a action for a final Judgement.
See Also:
runJudgingCanceled(edu.csus.ecs.pc2.api.IRun, boolean)

runJudged

void runJudged(IRun run,
               boolean isFinal)
Invoked when an existing run has been judged; that is, has had a Judgement applied to it. Typically this happens when a judge assigns a Judgement, but it can also occur as a result of an "automated judgement" (also known as a "validator") applying a judgement automatically.

Parameters:
run - the judged IRun
isFinal - true if this is a action for a final Judgement.

runUpdated

void runUpdated(IRun run,
                boolean isFinal)
Invoked when an existing run has been updated (modified) in some way.

Typically a runUpdated() invocation occurs when either

Parameters:
run - the IRun which has been changed
isFinal - true if this is a action for a final Judgement.

runCompiling

void runCompiling(IRun run,
                  boolean isFinal)
Invoked when an existing run is being compiled.

Parameters:
run - the IRun which is being compiled.
isFinal - true if this is a action for a final Judgement.

runExecuting

void runExecuting(IRun run,
                  boolean isFinal)
Invoked when an existing run is being executed.

Parameters:
run - the IRun which is being executed.
isFinal - true if this is a action for a final Judgement.

runValidating

void runValidating(IRun run,
                   boolean isFinal)
Invoked when an existing run is being validated.

Parameters:
run - the IRun which is being validated.
isFinal - true if this is a action for a final Judgement.

runJudgingCanceled

void runJudgingCanceled(IRun run,
                        boolean isFinal)
Invoked if the run is re-queued for judgement. If a judge has checked out a run then cancels (returns the run to the set of runs to be judged) then this method will be invoked.

Parameters:
run - the IRun which has been returned to the judging queue.
isFinal - true if this is a action for a final Judgement.