edu.csus.ecs.pc2.api.listener

## Interface IRunEventListener

- All Known Implementing Classes:
    ContestTestFrame.RunListener

      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$
  Author:
    pc2@ecs.csus.edu

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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

      - A judge re-judges a run; or
      - The Contest Administrator changes a setting (such as the elapsed time or the assigned `IJudgement`) in the run.
      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.