edu.csus.ecs.pc2.api

## Interface IProblem

-     public interface IProblem

  This interface describes the PC2 API view of a contest Problem. Each contest problem consists of a variety of attributes configured by the Contest Administrator, including
  - The problem name;
  - A flag indicating whether the problem includes a requirement for reading input data;
  - The input data for the problem (referred to as the "Judge's data file") if required;
  - A flag indicating whether solutions to the problem should expect any input data to come from a file or from stdin;
  - A flag indicating whether the problem includes a specification of the expected output for a correct solution to the problem (referred to as a "Judge's answer file");
  - A flag indicating whether the problem includes a validator (a program designed to accept as input (1) the output of a program submitted by a Team, and (2) a Judge's answer file, and makes an automated determination as to whether the Team's program is a correct solution to the problem);
  - The executable code for the validator;
  - The command line necessary to invoke the validator.

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

  Version:
    $Id$
  Author:
    pc2@ecs.csus.edu

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(Object obj)` Check whether this problem is the same as some other contest problem.
    `byte[]` | `getJudgesAnswerFileContents()` Get the data contained in the Judge's answer file for this problem.
    `String` | `getJudgesAnswerFileName()` Get the name of the answer file for this problem.
    `byte[]` | `getJudgesDataFileContents()` Get the data contained in the Judge's data file for this problem.
    `String` | `getJudgesDataFileName()` Get the name of the data file which the Judges have provided for this problem.
    `String` | `getName()` Get the name for this problem as configured by the Contest Administrator.
    `String` | `getShortName()` Get the short name for this problem as configured by the Contest Administrator.
    `String` | `getValidatorCommandLine()` Get the command line which has been specified by the Contest Administrator as being the command required to execute the validator program associated with this problem.
    `byte[]` | `getValidatorFileContents()` Get the contents of the file containing the validator associated with this problem.
    `String` | `getValidatorFileName()` Get the name of the Validator program file for this problem.
    `boolean` | `hasAnswerFile()` Returns true if the Contest Administrator has defined a Judge's Answer File for this problem; false otherwise.
    `boolean` | `hasDataFile()` Returns true if the Contest Administrator has defined a data file for this problem; false otherwise.
    `boolean` | `hasExternalValidator()` Returns true if this problem has had an External Validator assigned to it by the Contest Administrator; false otherwise.
    `int` | `hashCode()` Get the hashcode associated with this contest problem.
    `boolean` | `isDeleted()` Returns true if the Contest Administrator has hidden this problem false otherwise.
    `boolean` | `readsInputFromFile()` Returns true if the Contest Administrator has specified that solutions to this problem are supposed to read their input from a data file; false otherwise.
    `boolean` | `readsInputFromStdIn()` Returns true if the Contest Administrator has specified that solutions to this problem are supposed to read their input from a data file; false otherwise.

- - ### Method Detail

    - #### getName

          String getName()

      Get the name for this problem as configured by the Contest Administrator.
      Returns:
        A String containing the name of the problem.

    - #### getShortName

          String getShortName()

      Get the short name for this problem as configured by the Contest Administrator.
      Returns:
        A String containing the short name of the problem.

    - #### getJudgesDataFileName

          String getJudgesDataFileName()

      Get the name of the data file which the Judges have provided for this problem.
      Returns:
        A String containing the Judge's data file name.
      See Also:
        `hasDataFile()`

    - #### getJudgesDataFileContents

          byte[] getJudgesDataFileContents()

      Get the data contained in the Judge's data file for this problem.
      Returns:
        An array of bytes containing the Judge's data file contents.
      See Also:
        `hasDataFile()`

    - #### getJudgesAnswerFileName

          String getJudgesAnswerFileName()

      Get the name of the answer file for this problem. The "answer file" for a problem is a file which the Judges provide for purposes of comparing with the output of a Team's submitted program. The answer file is also typically used as one of the inputs to a Validator program intended to do automatic judging.
      Returns:
        A String containing the name of the Judge's Answer File for the problem.
      See Also:
        `hasAnswerFile()`

    - #### getJudgesAnswerFileContents

          byte[] getJudgesAnswerFileContents()

      Get the data contained in the Judge's answer file for this problem.
      Returns:
        An array of bytes containing the Judge's answer file contents.
      See Also:
        `hasAnswerFile()`

    - #### getValidatorFileName

          String getValidatorFileName()

      Get the name of the Validator program file for this problem. A "validator" is a program intended to be used to perform automated judging, for example by comparing the output of a Team's submitted program with the Judge's Answer File for a problem.
      Returns:
        A String containing the name of the Validator program associated with this problem.
      See Also:
        `hasExternalValidator()`

    - #### getValidatorCommandLine

          String getValidatorCommandLine()

      Get the command line which has been specified by the Contest Administrator as being the command required to execute the validator program associated with this problem.

      Note that when a Contest Administrator enters a "validator command line" into PC2, the entry may contain "substitution parameters" to be filled in at run time. The validator command line obtained by calling this method will have already had any such command line parameter substitutions performed prior to returning the command line.

      Returns:
        A String containing the command required to execute the validator associated with this problem.
      See Also:
        `hasExternalValidator()`

    - #### getValidatorFileContents

          byte[] getValidatorFileContents()

      Get the contents of the file containing the validator associated with this problem. In most cases the validator will be an executable program; in this case the byte array returned by this method contains the executable (binary) contents of that executable program.

      Note that PC2 supports three possible "validator configuration modes" for a problem:

      - No Validator;
      - Use PC2 Internal Validator; and
      - Use External Validator.
      If a problem has been configured with "No Validator" or "Use PC2 Internal Validator", the contents of the array returned by this method are undefined; the only time the information returned by this method is meaningful is when a problem has been configured with an External Validator by the Contest Administrator.
      Returns:
        A byte array containing the contents of the External Validator program associated with this problem.
      See Also:
        `hasExternalValidator()`

    - #### hasExternalValidator

          boolean hasExternalValidator()

      Returns true if this problem has had an External Validator assigned to it by the Contest Administrator; false otherwise.
      Returns:
        True if this problem has had a validator program associated with it; false otherwise.

    - #### readsInputFromFile

          boolean readsInputFromFile()

      Returns true if the Contest Administrator has specified that solutions to this problem are supposed to read their input from a data file; false otherwise. Note that this condition is mutually exclusive with `readsInputFromStdIn()`.
      Returns:
        True if solutions to this problem are supposed to read input from a file; false otherwise.
      See Also:
        `readsInputFromStdIn()`

    - #### readsInputFromStdIn

          boolean readsInputFromStdIn()

      Returns true if the Contest Administrator has specified that solutions to this problem are supposed to read their input from a data file; false otherwise. Note that this condition is mutually exclusive with `readsInputFromFile()`.
      Returns:
        True if solutions to this problem are supposed to read input from stdin; false otherwise.
      See Also:
        `readsInputFromFile()`

    - #### hasDataFile

          boolean hasDataFile()

      Returns true if the Contest Administrator has defined a data file for this problem; false otherwise.
      Returns:
        True if the Contest Administrator has defined a data file for this problem; false otherwise.

    - #### hasAnswerFile

          boolean hasAnswerFile()

      Returns true if the Contest Administrator has defined a Judge's Answer File for this problem; false otherwise.
      Returns:
        True if the Contest Administrator has defined a Judge's Answer File for this problem; false otherwise.

    - #### equals

          boolean equals(Object obj)

      Check whether this problem is the same as some other contest problem.

      Determination of whether two problems are equal is based on whether they refer to the same contest problem as originally entered into PC2 by the Contest Administrator. Note in particular that subsequent changes to a problem made by the Contest Administrator (for example, changes to the problem name, the Judge's data file, etc.) do not affect the result of the `equals()` method; if this problem refers to the same contest problem as the one indicated by the specified parameter, this method will return true regardless of whether the internal contents of the two problem objects is identical or not.

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

    - #### hashCode

          int hashCode()

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

    - #### isDeleted

          boolean isDeleted()

      Returns true if the Contest Administrator has hidden this problem false otherwise.
      Returns:
        true if hidden/deleted, false otherwise.