edu.csus.ecs.pc2.api

## Interface IContestClock

-     public interface IContestClock

  This interface describes the PC2 API view of Contest Time information. It provides methods for accessing various time-related aspects of the contest, including how much time has elapsed, how much time remains, and how long the contest is scheduled to last.

  Note that under the current implementation, an `IContestClock` object is static once it is obtained; to get a current copy of the contest time information a new `IContestClock` object should be obtained each time.

  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 ContestClock object is the same as some other ContestClock.
    `long` | `getContestLengthSecs()` Get the contest length.
    `long` | `getElapsedSecs()` Get the elapsed seconds in contest.
    `long` | `getRemainingSecs()` Get the remaining seconds in the contest.
    `int` | `hashCode()` Get the hashcode associated with this ContestClock.
    `boolean` | `isContestClockRunning()` Returns a boolean value indicating whether the contest clock is currently running.

- - ### Method Detail

    - #### getRemainingSecs

          long getRemainingSecs()

      Get the remaining seconds in the contest.

      Because of network lag and other factors there will likely be an error in accuracy. For this reason typically the granularity of minutes is used, though seconds is given.

      Returns:
        number of seconds left in contest.

    - #### getElapsedSecs

          long getElapsedSecs()

      Get the elapsed seconds in contest.

      Because of network lag and other factors there will likely be an error in accuracy. For this reason typically the granularity of minutes is used, though seconds is given.

      Returns:
        elapsed seconds in contest.

    - #### getContestLengthSecs

          long getContestLengthSecs()

      Get the contest length.

      The returned value represents the length of time which the Contest Administrator has specified that the contest should run.

      Returns:
        the number of seconds the contest is intended to run.

    - #### isContestClockRunning

          boolean isContestClockRunning()

      Returns a boolean value indicating whether the contest clock is currently running. If the method returns false, either the contest has not been started, or it has been started and then paused by the Contest Administrator. Method `getElapsedSecs()` can be used to determine which case exists (not yet started vs. paused.)
      Returns:
        true if the contest clock is currently running; false otherwise.

    - #### equals

          boolean equals(Object obj)

      Check whether this ContestClock object is the same as some other ContestClock.

      Determination of whether two ContestClocks are equal is based on whether they refer to the same ContestClock as obtained from `IContest.getContestClock()`.

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

    - #### hashCode

          int hashCode()

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