TimeService (Power TAC common domain model 1.1.0 API)

java.lang.Object
- org.powertac.common.TimeService

```
@Scope(value="singleton")
@Service
public class TimeService
extends Object
```
This is the simulation time-keeper and event queue. Here's how it works:
- You create it with four parameters: (base, start, rate, modulo), defined as
  - base is the start time of the simulation scenario. So if we are simulating a period in the summer of 2007, base might be 2007-06-21-12:00.
  - start is the start time of the simulation run.
  - rate is the time-compression ratio for the simulation. So if we are running one-hour timeslots every 5 seconds, the rate would be 720.
  - modulo controls the values of simulation time values reported. If we are running one-hour timeslots, then the modulo should be one hour, expressed in milliseconds. If we are running one-hour timeslots but want to update time every 30 minutes of simulated time, then the modulo would be 30*60*1000. Note that this will not work correctly unless the calls to updateTime() are made at modulo/rate intervals. Also note that the reported time is computed as rawTime - rawTime % modulo, which means it will never be ahead of the raw simulation time.
- Some process periodically calls updateTime(), at least once every simulated hour. This sets the currentTime property to the correct scenario time as
  currentTime = base + (systemTime - start) * rate
  and runs any simulation actions that are due.
- If you want something to happen sometime in the future, you add an action by calling addAction(time, action). Assuming time is not in the past, then the action (a closure with a single argument, the current time) is added to a time-ordered queue, and will be run when its time arrives.
Note that all times are absolute times represented as UTC; timezone offset is 0, and there is no "daylight-saving" time. If we want to represent the effects of DST, we'll have to have our customers wake up earlier in the summertime.
Author:

John Collins

Field Summary

Fields
Modifier and Type Field and Description

static long DAY

static long HOUR

static long MINUTE

static long SECOND

static long WEEK

Fields
Modifier and Type	Field and Description
`static long`	`DAY`
`static long`	`HOUR`
`static long`	`MINUTE`
`static long`	`SECOND`
`static long`	`WEEK`

Constructor Summary

Constructors
Constructor and Description
`TimeService()` Default constructor.
`TimeService(long base, long start, long rate, long modulo)` Handy constructor for testing

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addAction(org.joda.time.Instant time, TimedAction act)` Adds an action to the simulation queue, to be triggered at the specified time.
`long`	`getBase()`
`org.joda.time.Instant`	`getBaseInstant()`
`org.joda.time.DateTime`	`getCurrentDateTime()`
`org.joda.time.Instant`	`getCurrentTime()` Returns the current time as an Instant
`int`	`getHourOfDay()` Returns the current hour-of-day
`static TimeService`	`getInstance()` Returns the most-recently created instance of TimeService.
`long`	`getModulo()`
`long`	`getOffset()` Computes and returns the offset in msec between the current system time and the current clock time.
`long`	`getRate()`
`long`	`getStart()`
`void`	`init(org.joda.time.Instant start)` Sets current time to modulo before the desired start time.
`void`	`setBase(long value)` Deprecated. use `setClockParameters` instead
`void`	`setClockParameters(Competition comp)` Sets base, rate, and modulo from a Competition instance
`void`	`setClockParameters(long base, long rate, long modulo)` Sets base, rate, and modulo clock parameters with a single call.
`void`	`setClockParameters(Map<String,Long> params)` Sets base, rate, and modulo parameters from a map, which is wrapped in a Configuration to allow for conversions and default values.
`void`	`setCurrentTime()`
`protected void`	`setCurrentTime(org.joda.time.base.AbstractDateTime time)` Sets current time to a specific value.
`void`	`setCurrentTime(org.joda.time.Instant time)` Sets current time to a specific value.
`void`	`setModulo(long value)` Deprecated. use `setClockParameters` instead
`void`	`setRate(long value)` Deprecated. use `setClockParameters` instead
`void`	`setStart(long start)`
`org.joda.time.Instant`	`truncateInstant(org.joda.time.Instant time, long mod)` Returns the most recent Instant at which time % modulo was zero
`void`	`updateTime()` Updates simulation time when called as specified by clock parameters, then runs any actions that may be due.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - SECOND
```
public static final long SECOND
```
    See Also:
    Constant Field Values
  - MINUTE
```
public static final long MINUTE
```
    See Also:
    Constant Field Values
  - HOUR
```
public static final long HOUR
```
    See Also:
    Constant Field Values
  - DAY
```
public static final long DAY
```
    See Also:
    Constant Field Values
  - WEEK
```
public static final long WEEK
```
    See Also:
    Constant Field Values
- Constructor Detail
  - TimeService
```
public TimeService()
```
    Default constructor. You need to set base, rate, start, and modulo before using it.
  - TimeService
```
public TimeService(long base,
           long start,
           long rate,
           long modulo)
```
    Handy constructor for testing
- Method Detail
  - getInstance
```
public static TimeService getInstance()
```
    Returns the most-recently created instance of TimeService. Intended to be used only for testing in Spring-free environment. Note that this is not a Singleton-type instance getter - it will not create an instance.
  - init
```
public void init(org.joda.time.Instant start)
```
    Sets current time to modulo before the desired start time. This allows scheduling of actions to take place on the first tick, which should be at the desired start time. Call this after setting clock parameters.
  - updateTime
```
public void updateTime()
```
    Updates simulation time when called as specified by clock parameters, then runs any actions that may be due.
  - truncateInstant
```
public org.joda.time.Instant truncateInstant(org.joda.time.Instant time,
                                    long mod)
```
    Returns the most recent Instant at which time % modulo was zero
  - setClockParameters
```
public void setClockParameters(long base,
                      long rate,
                      long modulo)
```
    Sets base, rate, and modulo clock parameters with a single call. We do not set start at this point, because it is changed whenever the clock is paused and therefore needs to be treated separately.
  - setClockParameters
```
public void setClockParameters(Map<String,Long> params)
```
    Sets base, rate, and modulo parameters from a map, which is wrapped in a Configuration to allow for conversions and default values. The map must contain entries named "base", "rate", and "modulo". We also init the clock here, because we have all the parameters.
  - setClockParameters
```
public void setClockParameters(Competition comp)
```
    Sets base, rate, and modulo from a Competition instance
  - getBase
```
public long getBase()
```
  - getBaseInstant
```
public org.joda.time.Instant getBaseInstant()
```
  - setBase
```
@Deprecated
public void setBase(long value)
```
    Deprecated. use setClockParameters instead
  - getStart
```
public long getStart()
```
  - setStart
```
public void setStart(long start)
```
  - getRate
```
public long getRate()
```
  - setRate
```
@Deprecated
public void setRate(long value)
```
    Deprecated. use setClockParameters instead
  - getModulo
```
public long getModulo()
```
  - setModulo
```
@Deprecated
public void setModulo(long value)
```
    Deprecated. use setClockParameters instead
  - getCurrentTime
```
public org.joda.time.Instant getCurrentTime()
```
    Returns the current time as an Instant
  - getCurrentDateTime
```
public org.joda.time.DateTime getCurrentDateTime()
```
  - getHourOfDay
```
public int getHourOfDay()
```
    Returns the current hour-of-day
  - setCurrentTime
```
public void setCurrentTime(org.joda.time.Instant time)
```
    Sets current time to a specific value. Intended for testing purposes only.
  - getOffset
```
public long getOffset()
```
    Computes and returns the offset in msec between the current system time and the current clock time.
  - setCurrentTime
```
protected void setCurrentTime(org.joda.time.base.AbstractDateTime time)
```
    Sets current time to a specific value. Intended for testing purposes only.
  - setCurrentTime
```
public void setCurrentTime()
```
  - addAction
```
public void addAction(org.joda.time.Instant time,
             TimedAction act)
```
    Adds an action to the simulation queue, to be triggered at the specified time.

Class TimeService

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SECOND

MINUTE

HOUR

DAY

WEEK

Constructor Detail

TimeService

TimeService

Method Detail

getInstance

init

updateTime

truncateInstant

setClockParameters

setClockParameters

setClockParameters

getBase

getBaseInstant

setBase

getStart

setStart

getRate

setRate

getModulo

setModulo

getCurrentTime

getCurrentDateTime

getHourOfDay

setCurrentTime

getOffset

setCurrentTime

setCurrentTime

addAction