com.h3c.util

## Class TimeUtils

- java.lang.Object
- - com.h3c.util.TimeUtils

-     public final class TimeUtils
      extends Object

  Provides utilities dealing with timestamps and time intervals.

  This class has been designed with unit tests that need to make assertions about times relative to "now" in mind. It provides an interface that defines the notion of "`now`". Every instance of `TimeUtils` must provide an implementation of that interface. The `default` instance has an implementation that always returns `System.currentTimeMillis()`.

  See Also:
    `FakeTimeUtils`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `TimeUtils.Now` Defines the notion of "now" as expressed by the implementation of `TimeUtils.Now.currentTimeMillis()`.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static long` | `HOURS_PER_DAY` The number of hours in a day.
    `static long` | `HUNDREDTHS_PER_MILLIS` The number of milliseconds in a hundredth of a second.
    `static long` | `MILLIS_PER_DAY` The number of milliseconds in a day.
    `static long` | `MILLIS_PER_HOUR` The number of milliseconds in an hour.
    `static long` | `MILLIS_PER_MINUTE` The number of milliseconds in a minute.
    `static long` | `MILLIS_PER_SECOND` The number of milliseconds in a second.
    `static long` | `MINUTES_PER_HOUR` The number of minutes in an hour.
    `static long` | `SECONDS_PER_MINUTE` The number of seconds in a minute.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `currentTimeHundredths()` Returns the current time in hundredths of a second.
    `long` | `currentTimeMillis()` Equivalent to invoking `System.currentTimeMillis()`.
    `long` | `currentTimeSecs()` Returns the current time in seconds.
    `Date` | `daysAgo(int numDays)` Returns the timestamp of a number of days prior to now.
    `Date` | `daysBefore(Date when, int numDays)` Returns the timestamp of a number of days prior to the given date.
    `String` | `formatDateOrTime(Date date)` Returns the given date as a time if it occurred within the last 24 hours, or as a date if it occurred more than 24 hours ago.
    `String` | `formatInterval(long ms)` Returns a human-friendly string breaking out the specified number of milliseconds into a representative duration measured in some combination of days, hours, minutes, and seconds.
    `String` | `formatInterval(long ms, boolean longFormat)` Returns a human-friendly string breaking out the specified number of milliseconds into a representative duration measured in some combination of days, hours, minutes, and seconds.
    `static TimeUtils` | `getInstance()` Returns the default instance.
    `static TimeUtils` | `getInstance(TimeUtils.Now altNow)` Returns a specialized instance that has an alternate implementation of `TimeUtils.Now`.
    `String` | `hhmmss()` Returns a string representation of the time now, in the form `"hh:mm:ss"`.
    `String` | `hhmmss(long epochMs)` Returns a string representation of the given timestamp, in the form `"hh:mm:ss"`.
    `String` | `hhmmssnnn()` Returns a string representation of the time now, in the form `"hh:mm:ss.nnn"`.
    `String` | `hhmmssnnn(long epochMs)` Returns a string representation of the given timestamp, in the form `"hh:mm:ss.nnn"`.
    `Date` | `hoursAgo(int numHours)` Returns the date timestamp of a number of hours prior to now.
    `Date` | `hoursBefore(Date when, int numHours)` Returns the date timestamp of a number of hours prior to the given date.
    `Date` | `makeDate(String s)` Convenience method that will create a `Date` instance corresponding to the date specified in the given string.
    `long` | `millisSince(Date date)` Returns the number of milliseconds that have elapsed since the specified date.
    `static String` | `rfc822Timestamp(Date date)` Converts a Date into an RFC-822 UTC timestamp String.
    `static String` | `rfc822Timestamp(long timeInMillis)` Converts a long representing an offset in milliseconds from the "epoch" into an RFC-822 UTC timestamp String.
    `static Date` | `rfc822Timestamp(String timestamp)` Converts an RFC-822 UTC timestamp String into a Date.
    `long` | `upTimeHundredths()` Returns the number of hundredths of seconds since the JVM started up.
    `long` | `upTimeMillis()` Returns the number of milliseconds since the JVM started up.
    `long` | `upTimeSecs()` Returns the number of seconds since the JVM started up.

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

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

- - ### Field Detail

    - #### HOURS_PER_DAY

          public static final long HOURS_PER_DAY

      The number of hours in a day.
      See Also:
        Constant Field Values

    - #### MINUTES_PER_HOUR

          public static final long MINUTES_PER_HOUR

      The number of minutes in an hour.
      See Also:
        Constant Field Values

    - #### SECONDS_PER_MINUTE

          public static final long SECONDS_PER_MINUTE

      The number of seconds in a minute.
      See Also:
        Constant Field Values

    - #### MILLIS_PER_SECOND

          public static final long MILLIS_PER_SECOND

      The number of milliseconds in a second.
      See Also:
        Constant Field Values

    - #### HUNDREDTHS_PER_MILLIS

          public static final long HUNDREDTHS_PER_MILLIS

      The number of milliseconds in a hundredth of a second.
      See Also:
        Constant Field Values

    - #### MILLIS_PER_MINUTE

          public static final long MILLIS_PER_MINUTE

      The number of milliseconds in a minute.
      See Also:
        Constant Field Values

    - #### MILLIS_PER_HOUR

          public static final long MILLIS_PER_HOUR

      The number of milliseconds in an hour.
      See Also:
        Constant Field Values

    - #### MILLIS_PER_DAY

          public static final long MILLIS_PER_DAY

      The number of milliseconds in a day.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getInstance

          public static TimeUtils getInstance()

      Returns the default instance.
      Returns:
        the default TimeUtils instance

    - #### getInstance

          public static TimeUtils getInstance(TimeUtils.Now altNow)

      Returns a specialized instance that has an alternate implementation of `TimeUtils.Now`. This is designed for use by unit tests that are testing time-based methods and that want to provide a fully deterministic notion of "now".
      Parameters:
        `altNow` - the alternative implementation of Now
      Returns:
        a specialized TimeUtils instance

    - #### currentTimeMillis

          public long currentTimeMillis()

      Equivalent to invoking `System.currentTimeMillis()`.
      Returns:
        the current time in milliseconds (epoch time)

    - #### currentTimeHundredths

          public long currentTimeHundredths()

      Returns the current time in hundredths of a second.
      Returns:
        the current time in hundredths (epoch time)

    - #### currentTimeSecs

          public long currentTimeSecs()

      Returns the current time in seconds.
      Returns:
        the current time in seconds (epoch time)

    - #### upTimeMillis

          public long upTimeMillis()

      Returns the number of milliseconds since the JVM started up.
      Returns:
        the elapsed milliseconds since the JVM started

    - #### upTimeHundredths

          public long upTimeHundredths()

      Returns the number of hundredths of seconds since the JVM started up.
      Returns:
        the elapsed hundredths since the JVM started

    - #### upTimeSecs

          public long upTimeSecs()

      Returns the number of seconds since the JVM started up.
      Returns:
        the elapsed seconds since the JVM started

    - #### millisSince

          public long millisSince(Date date)

      Returns the number of milliseconds that have elapsed since the specified date.
      Parameters:
        `date` - the date to examine
      Returns:
        the number of milliseconds since that date

    - #### formatDateOrTime

          public String formatDateOrTime(Date date)

      Returns the given date as a time if it occurred within the last 24 hours, or as a date if it occurred more than 24 hours ago. Uses either `DateFormat.getTimeInstance()` or `DateFormat.getDateInstance()` as appropriate.
      Parameters:
        `date` - the date to format
      Returns:
        the formatted date

    - #### hoursAgo

          public Date hoursAgo(int numHours)

      Returns the date timestamp of a number of hours prior to now.
      Parameters:
        `numHours` - the number of hours before now
      Returns:
        the date for the specified number of hours ago

    - #### daysAgo

          public Date daysAgo(int numDays)

      Returns the timestamp of a number of days prior to now.
      Parameters:
        `numDays` - the number of days before now
      Returns:
        the date for the specified number of days ago

    - #### hoursBefore

          public Date hoursBefore(Date when,
                         int numHours)

      Returns the date timestamp of a number of hours prior to the given date.
      Parameters:
        `when` - the date
        `numHours` - the number of hours earlier
      Returns:
        the date for the specified number of hours earlier

    - #### daysBefore

          public Date daysBefore(Date when,
                        int numDays)

      Returns the timestamp of a number of days prior to the given date.
      Parameters:
        `when` - the date
        `numDays` - the number of days earlier
      Returns:
        the date for the specified number of days earlier

    - #### formatInterval

          public String formatInterval(long ms)

      Returns a human-friendly string breaking out the specified number of milliseconds into a representative duration measured in some combination of days, hours, minutes, and seconds. Only two terms are included in the returned string so what is returned depends upon the duration specified.

      For example if days is nonzero then a day and hour count will be returned, whereas if days is zero but hours isn't then an hour and minute count will be returned; if days and hours are both zero then a minute and second count will be returned.

      Parameters:
        `ms` - time interval in milliseconds
      Returns:
        formatted string representing time interval
      Throws:
        `IllegalArgumentException` - if `ms` is negative

    - #### formatInterval

          public String formatInterval(long ms,
                              boolean longFormat)

      Returns a human-friendly string breaking out the specified number of milliseconds into a representative duration measured in some combination of days, hours, minutes, and seconds. Only two terms are included in the returned string so what is returned depends upon the duration specified.

      For example if days is nonzero then a day and hour count will be returned, whereas if days is zero but hours isn't then an hour and minute count will be returned; if days and hours are both zero then a minute and second count will be returned.

      If `longFormat` is `true`, the returned string will spell out the time element units in full, whereas if `false`, the returned string will use abbreviated units.

      Parameters:
        `ms` - time interval in milliseconds
        `longFormat` - `true` spells out time element units; `false` uses abbreviated units
      Returns:
        a formatted string representing the time interval
      Throws:
        `IllegalArgumentException` - if `ms` is negative

    - #### makeDate

          public Date makeDate(String s)

      Convenience method that will create a `Date` instance corresponding to the date specified in the given string. The string must take the form `"YYYY-MM-DD"` and must be the year 2000 or later.
      Parameters:
        `s` - the date string
      Returns:
        a corresponding date instance

    - #### hhmmss

          public String hhmmss()

      Returns a string representation of the time now, in the form `"hh:mm:ss"`.
      Returns:
        the formatted time stamp

    - #### hhmmss

          public String hhmmss(long epochMs)

      Returns a string representation of the given timestamp, in the form `"hh:mm:ss"`.
      Parameters:
        `epochMs` - epoch time stamp
      Returns:
        the formatted time stamp

    - #### hhmmssnnn

          public String hhmmssnnn()

      Returns a string representation of the time now, in the form `"hh:mm:ss.nnn"`.
      Returns:
        the formatted time stamp

    - #### hhmmssnnn

          public String hhmmssnnn(long epochMs)

      Returns a string representation of the given timestamp, in the form `"hh:mm:ss.nnn"`.
      Parameters:
        `epochMs` - the epoch time stamp
      Returns:
        the formatted time stamp

    - #### rfc822Timestamp

          public static String rfc822Timestamp(Date date)

      Converts a Date into an RFC-822 UTC timestamp String.

      Dates prior to 1 AD (which is the same as 0 BC) are not supported and will result in an IllegalArgumentException.

      Parameters:
        `date` - a Date object to be converted
      Returns:
        an RFC-822 UTC formated timestamp String.
      Throws:
        `IllegalArgumentException` - if a date before 0 BC (or 1 AD) is passed

    - #### rfc822Timestamp

          public static String rfc822Timestamp(long timeInMillis)

      Converts a long representing an offset in milliseconds from the "epoch" into an RFC-822 UTC timestamp String.

      Dates prior to 1 AD (which is the same as 0 BC) are not supported and will result in an IllegalArgumentException.

      Parameters:
        `timeInMillis` - a long representing an offset in milliseconds from the "epoch"
      Returns:
        an RFC-822 UTC formated timestamp String.
      Throws:
        `IllegalArgumentException` - if a time before 0 BC (or 1 AD) is passed

    - #### rfc822Timestamp

          public static Date rfc822Timestamp(String timestamp)
                                      throws ParseException

      Converts an RFC-822 UTC timestamp String into a Date.

      Given the RFC-822 format, it is not possible to pass a date prior to 1 AD (which is the same as 0 BC).

      Parameters:
        `timestamp` - an RFC-822 UTC timestamp String to be converted
      Returns:
        a Date object representing the given RFC-822 UTC formated timestamp String.
      Throws:
        `ParseException` - if the `date` string is not a valid RFC-822 UTC timestamp

Copyright © 2014. All Rights Reserved.