edu.csus.ecs.pc2.api

## Interface IRun

-     public interface IRun

  This interface describes the PC2 API view of a contest Run. A Run is a submission by a Team of a program for judging. Information about run states is in `IRunEventListener`

  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
    --- | ---
    `boolean` | `equals(Object obj)` Check whether this Run is the same as some other Run.
    `IClient` | `getJudge()` Get the judge that judged this run.
    `String` | `getJudgementName()` Get the judgement name assigned to the run by the Judges.
    `ILanguage` | `getLanguage()` Get the language which was specified for this run when it was submitted by the submitting team.
    `int` | `getNumber()` Get the run number.
    `IProblem` | `getProblem()` Get the problem for which this run was submitted.
    `IRunJudgement[]` | `getRunJudgements()` Return List of judgements assigned by judges.
    `int` | `getSiteNumber()` Get the site number associated with the run.
    `byte[][]` | `getSourceCodeFileContents()` Get the source code contained in the files submitted by the Team which created this `IRun`.
    `String[]` | `getSourceCodeFileNames()` Get the names of each of the source code files submitted as part of this `IRun` by the submitting team.
    `long` | `getSubmissionTime()` Get the number of minutes which had elapsed on the contest clock at the site where the run submission was received when the run was submitted.
    `ITeam` | `getTeam()` Get the team (client) that submitted this run.
    `int` | `hashCode()` Get the hashcode associated with this client.
    `boolean` | `isDeleted()` Return a boolean indicating whether the run been marked as deleted by the Contest Administrator.
    `boolean` | `isFinalJudged()` Return a boolean indicating whether or not the run been judged.
    `boolean` | `isPreliminaryJudged()` Return a boolean indicating whether the run has only been preliminarily judged.
    `boolean` | `isSolved()` Return a boolean indicating whether the run been given a Yes (Correct) judgement.

- - ### Method Detail

    - #### isFinalJudged

          boolean isFinalJudged()

      Return a boolean indicating whether or not the run been judged. Will return false if `isPreliminaryJudged()` return true.
      Returns:
        true if the run has been judged, false if not judged.

    - #### isPreliminaryJudged

          boolean isPreliminaryJudged()

      Return a boolean indicating whether the run has only been preliminarily judged. Will return false if `isFinalJudged()` returns true.
      Returns:
        true if run only has a preliminary judgement.

    - #### isSolved

          boolean isSolved()

      Return a boolean indicating whether the run been given a Yes (Correct) judgement. Note that the value of this method is only meaningful if the Run has been judged.
      Returns:
        true if the run was judged by the Judges as having correctly solved a problem, false otherwise.

    - #### isDeleted

          boolean isDeleted()

      Return a boolean indicating whether the run been marked as deleted by the Contest Administrator.
      Returns:
        true if the run is marked deleted, else false.

    - #### getTeam

          ITeam getTeam()

      Get the team (client) that submitted this run.
      Returns:
        the `ITeam` which submitted this run.

    - #### getJudgementName

          String getJudgementName()

      Get the judgement name assigned to the run by the Judges. Note that if the run has been judged using an automated judger (also know as a validator) this method may return text from the validator which may not match any judgement name defined by the Contest Administrator (that is, the return value might be different from any defined `IJudgement`).
      Returns:
        null if the run has not been judged; otherwise, a String representing judgement assigned to the run.

    - #### getRunJudgements

          IRunJudgement[] getRunJudgements()

      Return List of judgements assigned by judges.
      Returns:
        list of IRunJudgements or zero length array of IRunJudgement.

    - #### getJudge

          IClient getJudge()

      Get the judge that judged this run.
      Returns:
        the judge client or returns null if run is not judged.

    - #### getProblem

          IProblem getProblem()

      Get the problem for which this run was submitted.
      Returns:
        the `IProblem` associated with this run.

    - #### getLanguage

          ILanguage getLanguage()

      Get the language which was specified for this run when it was submitted by the submitting team.
      Returns:
        the `ILanguage` associated with this run.

    - #### getNumber

          int getNumber()

      Get the run number. Every submitted run is assigned a site-unique Run number by the PC2 server which first receives the submission (that is, by the server to which the submitting team client is connected). Run numbers are always positive and always increasing at any given site (that is, every new run at a given site will acquire a run number higher than any previous run at that same site). Every submitted run is also populated with the unique site number of the site where the run is first received. The combination of the site number and the run number therefore provides a contest-wide unique identifier for every run in the contest.
      Returns:
        the number for this run.

    - #### getSiteNumber

          int getSiteNumber()

      Get the site number associated with the run. This will always be the unique number of the site where the run was received by a PC2 server.
      Returns:
        the site number for this run.

    - #### getSubmissionTime

          long getSubmissionTime()

      Get the number of minutes which had elapsed on the contest clock at the site where the run submission was received when the run was submitted.
      Returns:
        the number of minutes elapsed when this run was submitted to a PC2 server.

    - #### getSourceCodeFileNames

          String[] getSourceCodeFileNames()

      Get the names of each of the source code files submitted as part of this `IRun` by the submitting team. The number of elements in the returned array corresponds to the number of different source code files submitted by the Team; the first element of the array (element [0]) gives the name of the file which the Team submitted as the "main" program file.
      Returns:
        An array of Strings where each array element contains the name of one source code file submitted by the Team which created this `IRun`.

    - #### getSourceCodeFileContents

          byte[][] getSourceCodeFileContents()

      Get the source code contained in the files submitted by the Team which created this `IRun`. Returns an array of arrays of bytes containing the contents of the submitted source code files. The first element of the array contains the bytes from the first source code file submitted, which is always the "main program" file; subsequent elements of the array contain the bytes from each additional source code file submitted by the Team.
      Returns:
        The contents of each submitted source code file for this `IRun`.

    - #### equals

          boolean equals(Object obj)

      Check whether this Run is the same as some other Run.

      Determination of whether two Runs are equal is based on whether they refer to the same run as submitted by a Team. Note in particular that subsequent changes to a Run made by the Contest Administrator (for example, changes to the time the run was received, the language or problem specified in the run, or whether the run solved the problem or not) do not affect the result of the `equals()` method; if this Run refers to the same Run as the one indicated by the specified parameter, this method will return true regardless of whether the internal contents of the two Run objects is identical or not.

      Overrides:
        `equals` in class `Object`
      Parameters:
        `obj` - the Run which is to be compared with this Run for equality.
      Returns:
        True if the specified object refers to the same Run as this Run (regardless of the actual content of the two Runs).

    - #### hashCode

          int hashCode()

      Get the hashcode associated with this client.
      Overrides:
        `hashCode` in class `Object`
      Returns:
        An integer hashcode for this object.