Package de.gebit.integrity.runner.time

## Class TimeAndDateSingleton

- java.lang.Object
- - de.gebit.integrity.runner.time.TimeAndDateSingleton

- All Implemented Interfaces:
    `TestTimeAdapter`

      public final class TimeAndDateSingleton
      extends Object
      implements TestTimeAdapter

  This singleton is designed to make time-sensitive processes testable by allowing to set the "current time" to a certain fixed time or a certain start time from which the "current time" progresses at a configurable speed.

  Applications which need to operate on date specific data should use `TimeAndDateSingleton.getInstance().getDate()` rather than creating a new Date with `new java.util.Date();`. In order to test that application code later, a fixed date can be used rather than the current date by assigning the date to use with `TimeAndDateSingleton.setDate(aDate)`.
  This is more a sample implementation than it is intended to be actually used directly as-is in an application, which is the reason why the instance getter below is private - YOU MUST MAKE IT PUBLIC IN YOUR COPY! You are advised at copying this class into your application, because then you won't depend on Integrity JARs during runtime. See the `SimpleTestTimeAdapter` class and the interface `TestTimeAdapter` for more information.

  Author:
    Author: Rene Schneider - initial API and implementation

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected static TimeAndDateSingleton` | `instance` | The singleton instance.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `TimeAndDateSingleton()` | Ensure that no instance can be created from outside.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `long` | `currentTimeMillis()` | The replacement for `System.currentTimeMillis()`.
    `Date` | `getDate()` | Returns the current system date or - if a static or progressing "fake" date was set - this fake date for testing purposes.
    `String` | `getInternalsAsString()` | Returns the internal values of this `TestingTimeAndDateSingleton` as a String.
    `void` | `reset()` | Resets any configured static or progressing date.
    `void` | `setDate​(Date aDate)` | Sets the "current date" to a static date.
    `void` | `setInternalsFromString​(String anInternalsString)` | Takes the string returned by `getInternalsAsString()` and inserts the internals into this `TimeAndDateSingleton`.
    `void` | `setInternalState​(long aRealtimeOffset, long aRealtimeDecouplingTime, double aProgressionFactor)` | Directly sets the internal values of the timekeeper.
    `void` | `setProgressingDate​(Date aDate, double aTimeProgressionFactor)` | Configure a progressing date, starting at a certain start date, which then progresses at a configurable speed.
    `void` | `setProgressionFactor​(double aTimeProgressionFactor)` | Change the progression factor of time.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### instance

          protected static volatile TimeAndDateSingleton instance

      The singleton instance.

  - ### Constructor Detail

    - #### TimeAndDateSingleton

          protected TimeAndDateSingleton()

      Ensure that no instance can be created from outside.

  - ### Method Detail

    - #### setProgressingDate

          public void setProgressingDate​(Date aDate,
                                         double aTimeProgressionFactor)

      Configure a progressing date, starting at a certain start date, which then progresses at a configurable speed.
      Parameters:
        `aDate` - the start date
        `aTimeProgressionFactor` - the speed at which time progresses (1.0 is "realtime").

    - #### setProgressionFactor

          public void setProgressionFactor​(double aTimeProgressionFactor)

      Change the progression factor of time. This only has an effect if the date was configured to a progressing date before by calling `setProgressingDate(Date, double)`.
      Parameters:
        `aTimeProgressionFactor` - the speed at which time progresses (1.0 is "realtime").

    - #### setDate

          public void setDate​(Date aDate)

      Sets the "current date" to a static date.
      Parameters:
        `aDate` - the static date to set (null resets the date to the actual date; see also `reset()`)

    - #### reset

          public void reset()

      Resets any configured static or progressing date. The singleton will then return the actual date again.

    - #### setInternalState

          public void setInternalState​(long aRealtimeOffset,
                                       long aRealtimeDecouplingTime,
                                       double aProgressionFactor)

      Directly sets the internal values of the timekeeper. Intended to be used by the Integrity Test Framework.
      Specified by:
        `setInternalState` in interface `TestTimeAdapter`
      Parameters:
        `aRealtimeOffset` -
        `aRealtimeDecouplingTime` -
        `aProgressionFactor` -

    - #### getInternalsAsString

          public String getInternalsAsString()

      Returns the internal values of this `TestingTimeAndDateSingleton` as a String. This string is intended to be fed into another `TestingTimeAndDateSingleton` in order to synchronize it with the source. The string consists of pipe-divided values "realtime offset", "realtime decoupling time" and "multiplier" (first two are long values, third is a double-precision floating point number in normal notation with decimal point). If the singleton is in "live" operation mode, the returned value is just null.
      Returns:
        the internal values as string without spaces

    - #### setInternalsFromString

          public void setInternalsFromString​(String anInternalsString)

      Takes the string returned by `getInternalsAsString()` and inserts the internals into this `TimeAndDateSingleton`.
      Parameters:
        `anInternalsString` - the string to use as source

    - #### getDate

          public Date getDate()

      Returns the current system date or - if a static or progressing "fake" date was set - this fake date for testing purposes.
      Returns:

    - #### currentTimeMillis

          public long currentTimeMillis()

      The replacement for `System.currentTimeMillis()`. Returns either the actual value or, if the time was overridden for testing, the "fake testing time".
      Returns: