Package net.obvj.performetrics.util

Class Duration

  • All Implemented Interfaces:
    Comparable<Duration>
    public final class Duration
extends Object
implements Comparable<Duration>

    A time-based amount, such as '01:59:59.987654321 (H:M:S.ns)'.

    This class models a quantity or amount of time in terms of:

    • hours, from 0 to the maximum value that can be held in a long
    • minutes within the hour, from 0 to 59
    • seconds within the minute, from 0 to 59
    • nanoseconds within the second, from 0 to 999,999,999

    This class is immutable and thread-safe.

    Since:
    2.0.0
    Author:
    oswaldo.bapvic.jr

    • Method Detail

      • of

        public static Duration of​(long amount,
                          TimeUnit timeUnit)
        Obtains a Duration representing an amount in the specified time unit.

        For example, calling Duration.of(65, SECONDS) produces an object in which the getters behave according to the example below: 

         duration.getHours()       //returns: 0
 duration.getMinutes()     //returns: 1
 duration.getSeconds()     //returns: 5
 duration.getNanoseconds() //returns: 0
        Parameters:
        amount - the amount of the duration (positive or negative), measured in terms of the time unit argument
        timeUnit - the unit that the amount argument is measured in, not null
        Returns:
        a Duration, not null
        Throws:
        NullPointerException - if the specified time unit is null

      • of

        public static Duration of​(long amount,
                          TemporalUnit temporalUnit)
        Obtains a Duration representing an amount in the specified unit.

        For example, calling Duration.of(65, SECONDS) produces an object in which the getters behave according to the example below: 

         duration.getHours()       //returns: 0
 duration.getMinutes()     //returns: 1
 duration.getSeconds()     //returns: 5
 duration.getNanoseconds() //returns: 0
        Parameters:
        amount - the amount of the duration (positive or negative), measured in terms of the time unit argument
        temporalUnit - the unit that the amount argument is measured in, not null
        Returns:
        a Duration, not null
        Throws:
        NullPointerException - if the specified time unit is null
        IllegalArgumentException - if the specified duration amount is negative
        Since:
        2.5.0

      • parse

        public static Duration parse​(String string)
        Obtains a Duration from a string in default format.

        This will parse a textual representation of a duration produced by toString().

        Parameters:
        string - the string to parse, not null
        Returns:
        the parsed Duration, not null
        Throws:
        NullPointerException - if the specified string is null
        IllegalArgumentException - if the string cannot be parsed using default format
        Since:
        2.4.0

      • getHours

        public long getHours()
        Returns the number of hours in this duration.

        The hours field is a value from 0 to the maximum value that can be held in a long.

        Returns:
        the number of hours in this duration

      • getMinutes

        public int getMinutes()
        Returns the number of minutes within the hour in this duration.

        The minutes field is a value from 0 to 59, which is an adjustment to the length in hours, retrieved by calling getHours().

        Returns:
        the minutes within the hours part of the length of the duration, from 0 to 59

      • getSeconds

        public int getSeconds()
        Returns the number of seconds within the minute in this duration.

        The seconds field is a value from 0 to 59, which is an adjustment to the length in minutes, and hours, each part separately retrieved with their respective getter methods.

        Returns:
        the seconds within the minutes part of the length of the duration, from 0 to 59

      • getNanoseconds

        public int getNanoseconds()
        Returns the number of nanoseconds within the second in this duration.

        The nanoseconds field is a value from 0 to 999,999,999, which is an adjustment to the length in seconds, minutes, and hours, each part separately retrieved with their respective getter methods.

        Returns:
        the nanoseconds within the seconds part of the length of the duration, from 0 to 999,999,999

      • isZero

        public boolean isZero()
        Checks if this duration is zero length.
        Returns:
        true if this duration has a total length equal to zero
        Since:
        2.2.2

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • toString

        public String toString()
        Returns a string representation of this Duration in default format.
        Overrides:
        toString in class Object
        Returns:
        a string representation of this object

      • toString

        public String toString​(DurationFormat format)
        Returns a string representation of this Duration with a specific format.

        Note: This is equivalent to calling toString(format, true)

        Parameters:
        format - the DurationFormat to be applied
        Returns:
        a string representation of this object in the specified format

      • toString

        public String toString​(DurationFormat format,
                       boolean printLegend)
        Returns a string representation of this Duration with a specific format.
        Parameters:
        format - the DurationFormat to be applied
        printLegend - a flag indicating whether or not to include a legend in the generated string
        Returns:
        a string representation of this object in the specified format
        Throws:
        NullPointerException - if the specified DurationFormat is null

      • toTimeUnit

        public double toTimeUnit​(TimeUnit timeUnit)
        Converts this duration to the total length in a given time unit, with default scale.

        Note: The number of decimal places applied is determined by ConfigurationHolder.getConfiguration().getScale() and may be changed by calling Performetrics.setScale(int).

        Parameters:
        timeUnit - the target time unit, not null
        Returns:
        the total length of the duration in the specified time unit, with default scale
        Throws:
        NullPointerException - if the specified time unit is null

      • toTimeUnit

        public double toTimeUnit​(TimeUnit timeUnit,
                         int scale)
        Converts this duration to the total length in a given time unit, with a custom scale.
        Parameters:
        timeUnit - the target time unit, not null
        scale - a positive number indicates the number of decimal places to maintain; if negative, the default scale will be applied
        Returns:
        the total length of the duration in the specified time unit, with a custom scale, not null
        Throws:
        NullPointerException - if the specified time unit is null

      • toSeconds

        public double toSeconds()
        Converts this duration to the total length in seconds and fractional nanoseconds, with a fixed scale of 9, so nanoseconds precision is preserved.

        Note: This is equivalent to calling: toTimeUnit(TimeUnit.SECONDS, 9)

        Returns:
        the total length of the duration in seconds, with a scale of 9, not null

      • plus

        public Duration plus​(Duration duration)
        Returns a copy of this duration with the specified duration added.

        This instance is immutable and unaffected by this method call.

        Parameters:
        duration - the duration to add, not null
        Returns:
        a Duration based on this duration with the specified duration added, not null
        Throws:
        NullPointerException - if the specified duration is null
        ArithmeticException - if numeric overflow occurs

      • plus

        public Duration plus​(long amount,
                     TimeUnit timeUnit)
        Returns a copy of this duration with the specified duration added.

        This instance is immutable and unaffected by this method call.

        Parameters:
        amount - the amount to add (positive or negative), measured in terms of the timeUnit argument
        timeUnit - the unit that the amount to add is measured in, not null
        Returns:
        a Duration based on this duration with the specified duration added, not null
        Throws:
        NullPointerException - if the specified time unit is null
        ArithmeticException - if numeric overflow occurs
        Since:
        2.2.2

      • sum

        public static Duration sum​(Duration duration1,
                           Duration duration2)
        Returns the sum of two durations.

        This instances are immutable and unaffected by this method call.

        Parameters:
        duration1 - the first duration to add, not null
        duration2 - the second duration to add, not null
        Returns:
        a Duration resulting by adding two durations, not null
        Throws:
        NullPointerException - if the specified duration is null
        ArithmeticException - if numeric overflow occurs

      • dividedBy

        public Duration dividedBy​(long divisor)
        Returns a copy of this duration divided by the specified value.

        This instance is immutable and unaffected by this method call.

        Parameters:
        divisor - the value to divide the duration by, positive or negative, not zero
        Returns:
        a Duration based on this duration divided by the specified divisor, not null
        Throws:
        ArithmeticException - if the divisor is zero or if numeric overflow occurs
        Since:
        2.2.0

      • compareTo

        public int compareTo​(Duration otherDuration)
        Compares this duration to the specified Duration based on the total length of the durations, as defined by Comparable.
        Specified by:
        compareTo in interface Comparable<Duration>
        Parameters:
        otherDuration - the other duration to compare to; not null
        Returns:
        the comparator value, negative if less, positive if greater
        Since:
        2.2.3