Package oracle.nosql.driver

## Class TimeToLive

- java.lang.Object
- - oracle.nosql.driver.TimeToLive

-     public final class TimeToLive
      extends Object

  TimeToLive is a utility class that represents a period of time, similar to java.time.Duration in Java, but specialized to the needs of this driver.

  This class is restricted to durations of days and hours. It is only used as input related to time to live (TTL) for row instances. Construction allows only day and hour durations for efficiency reasons. Durations of days are recommended as they result in the least amount of storage overhead.

  Only positive durations are allowed on input, although negative durations can be returned from `fromExpirationTime(long, long)` if the expirationTime is in the past relative to the referenceTime.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static TimeToLive` | `DO_NOT_EXPIRE` | A convenience constant that can be used as an argument to indicate that the row should not expire.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static TimeToLive` | `fromExpirationTime​(long expirationTime, long referenceTime)` | Returns an instance of TimeToLive based on an absolute expiration time and a reference time.
    `TimeUnit` | `getUnit()` | Returns the TimeUnit used for the duration
    `long` | `getValue()` | Returns the numeric duration value
    `static TimeToLive` | `ofDays​(long days)` | Creates a duration using a period of 24 hour days.
    `static TimeToLive` | `ofHours​(long hours)` | Creates a duration using a period of hours.
    `long` | `toDays()` | Returns the number of days in this duration, which may be negative.
    `long` | `toExpirationTime​(long referenceTime)` | Returns an absolute time representing the duration plus the absolute time reference parameter.
    `long` | `toHours()` | Returns the number of hours in this duration, which may be negative.
    `String` | `toString()` |

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

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DO_NOT_EXPIRE

          public static final TimeToLive DO_NOT_EXPIRE

      A convenience constant that can be used as an argument to indicate that the row should not expire.

  - ### Method Detail

    - #### ofHours

          public static TimeToLive ofHours​(long hours)

      Creates a duration using a period of hours.
      Parameters:
        `hours` - the number of hours in the duration, must be a non-negative number
      Returns:
        the duration
      Throws:
        `IllegalArgumentException` - if a negative value is provided

    - #### ofDays

          public static TimeToLive ofDays​(long days)

      Creates a duration using a period of 24 hour days.
      Parameters:
        `days` - the number of days in the duration, must be a non-negative number
      Returns:
        the duration
      Throws:
        `IllegalArgumentException` - if a negative value is provided

    - #### toDays

          public long toDays()

      Returns the number of days in this duration, which may be negative.
      Returns:
        the number of days

    - #### toHours

          public long toHours()

      Returns the number of hours in this duration, which may be negative.
      Returns:
        the number of hours

    - #### toExpirationTime

          public long toExpirationTime​(long referenceTime)

      Returns an absolute time representing the duration plus the absolute time reference parameter. If an expiration time from the current time is desired the parameter should be `System.currentTimeMillis()`. If the duration of this object is 0 (`DO_NOT_EXPIRE`), indicating no expiration time, this method will return 0, regardless of the reference time.
      Parameters:
        `referenceTime` - an absolute time in milliseconds since January 1, 1970.
      Returns:
        time in milliseconds, 0 if this object's duration is 0

    - #### fromExpirationTime

          public static TimeToLive fromExpirationTime​(long expirationTime,
                                                      long referenceTime)

      Returns an instance of TimeToLive based on an absolute expiration time and a reference time. If a duration relative to the current time is desired the referenceTime should be `System.currentTimeMillis()`. If the expirationTime is 0, the referenceTime is ignored and a TimeToLive of duration 0 is created, indicating no expiration.

      Days will be use as the primary unit of duration if the expiration time is evenly divisible into days, otherwise hours are used.

      Parameters:
        `expirationTime` - an absolute time in milliseconds since January 1, 1970
        `referenceTime` - an absolute time in milliseconds since January 1, 1970.
      Returns:
        a new TimeToLive instance

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### getValue

          public long getValue()

      Returns the numeric duration value
      Returns:
        the duration value, independent of unit

    - #### getUnit

          public TimeUnit getUnit()

      Returns the TimeUnit used for the duration
      Returns:
        the unit