Package javacardx.framework.time

Class TimeDuration

  • public final class TimeDuration
extends Object
    A time-based amount of time.

    This class models a quantity or amount of time with microsecond resolution. The model is of a directed duration, meaning that the duration may be negative.

    A TimeDuration must support a range from -(2^63) up to +((2^63)-1) microseconds.

    A duration can be accessed using other duration-based units, such as milliseconds, seconds, minutes, hours and days. The supported units always represent an exact amount of time allowing conversion into any of them. In particular, it does not take into account leap-seconds (scientific SI-seconds) and uses exactly 86400 seconds for a day. The units that do not represent a fixed amount of time (e.g. months) are not supported.

    Durations are totally ordered and can be compared to any another duration.

    Basic arithmetic operations (plus(TimeDuration), minus(TimeDuration)) can be performed on durations.

    Example: measuring time elapsed 

     // pre-allocate 2 duration instances
 TimeDuration start   = TimeDuration.getInstance(JCSystem.MEMORY_TYPE_TRANSIENT_DESELECT);
 TimeDuration current = TimeDuration.getInstance(JCSystem.MEMORY_TYPE_TRANSIENT_DESELECT);

 // get timestamp
 SysTime.uptime(start);
 [...]
 // get another timestamp
 SysTime.uptime(current);

 // compares difference with threshold and do something if required
 if (current.minus(start).compareTo(100, MILLIS) >= 0) {
     // More than 100ms: do something
 }
    Example: comparing two durations 
     TimeDuration threshold = TimeDuration.getInstance(JCSystem.MEMORY_TYPE_TRANSIENT_DESELECT, 2, SECONDS);
 [...]
 switch (duration.compareTo(threshold)) {
    case  0: // duration == threshold
    case  1: // duration > threshold
    case -1: // duration < threshold
 }

    Since:
    3.1

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static short DAYS
      Unit that represents the concept of a day.
      static short HOURS
      Unit that represents the concept of an hour.
      static short MICROS
      Unit that represents the concept of a microsecond.
      static short MILLIS
      Unit that represents the concept of a millisecond.
      static short MINUTES
      Unit that represents the concept of a minute.
      static short SECONDS
      Unit that represents the concept of a second.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      TimeDuration abs()
      Update this duration by effectively removing the sign and making this instance a positive duration.
      short compareTo​(short amount, short unit)
      Compares this duration to the given amount of time.
      short compareTo​(TimeDuration other)
      Compares this duration to the given one.
      short getByteLength​(short unit)
      Returns the minimum number of bytes required to represent the duration in the specified unit.
      static TimeDuration getInstance​(byte memoryType)
      Gets a new TimeDuration instance with value set to zero.
      static TimeDuration getInstance​(byte memoryType, short amount, short unit)
      Gets a new TimeDuration instance initialized with the amount of time in the specified unit.
      byte getMemoryType()
      Returns the memory type specified at object creation and used to store the value.
      boolean isNegative()
      Checks if this duration is negative, excluding zero.
      TimeDuration minus​(short amount, short unit)
      Update this duration by subtracting the specified amount of time.
      TimeDuration minus​(TimeDuration duration)
      Update this duration by subtracting the specified duration.
      TimeDuration neg()
      Update this duration with the length negated.
      TimeDuration plus​(short amount, short unit)
      Update this duration by adding the specified amount of time.
      TimeDuration plus​(TimeDuration duration)
      Update this duration by adding the specified duration.
      TimeDuration reset()
      Reset this duration to zero.
      TimeDuration set​(byte[] input, short offset, short length, short unit)
      Update this duration with the specified value.
      short toBytes​(byte[] output, short offset, short length, short unit)
      Gets the integer amount of time, with the specified unit, contained in this duration and writes the result in the output byte array.

    • Field Detail

      • MICROS

        public static final short MICROS
        Unit that represents the concept of a microsecond.
        See Also:
        Constant Field Values

      • MILLIS

        public static final short MILLIS
        Unit that represents the concept of a millisecond.
        See Also:
        Constant Field Values

      • SECONDS

        public static final short SECONDS
        Unit that represents the concept of a second.
        See Also:
        Constant Field Values

      • MINUTES

        public static final short MINUTES
        Unit that represents the concept of a minute.
        See Also:
        Constant Field Values

      • HOURS

        public static final short HOURS
        Unit that represents the concept of an hour.
        See Also:
        Constant Field Values

      • DAYS

        public static final short DAYS
        Unit that represents the concept of a day.
        See Also:
        Constant Field Values

    • Method Detail

      • getInstance

        public static TimeDuration getInstance​(byte memoryType)
                                throws SystemException
        Gets a new TimeDuration instance with value set to zero.

        It is possible to create durations with a value stored in different memory spaces:

        • A TimeDuration instance with a persistent value can typically be used to store a duration that can be used across sessions. The application shall take into account that updating the duration value may imply updating non-volatile memory.

        • A TimeDuration instance with a transient value is cleared and value set to zero when the corresponding clear event occurs (deselect or reset). It should only be used during a session to store duration with the exact same lifecycle. The application has the guarantee that updating the duration is not updating non-volatile memory.

        Parameters:
        memoryType - the memory type used internally for the duration value. Valid types are the following:
        Returns:
        a new TimeDuration instance
        Throws:
        SystemException - with the following reason codes:

      • getInstance

        public static TimeDuration getInstance​(byte memoryType,
                                       short amount,
                                       short unit)
                                throws DateTimeException
        Gets a new TimeDuration instance initialized with the amount of time in the specified unit.

        It is possible to create durations with a value stored in different memory spaces:

        • A TimeDuration instance with a persistent value can typically be used to store a duration that can be used across sessions. The application shall take into account that updating the duration value may imply updating non-volatile memory.

        • A TimeDuration instance with a transient value is cleared and value set to zero when the corresponding clear event occurs (deselect or reset). It should only be used during a session to store duration with the exact same lifecycle. The application has the guarantee that updating the duration is not updating non-volatile memory.

        Examples: 

           TimeDuration.getInstance(JCSystem.MEMORY_TYPE_TRANSIENT_DESELECT, 3, SECONDS);
   TimeDuration.getInstance(JCSystem.MEMORY_TYPE_PERSISTENT, 465, HOURS);

        Parameters:
        memoryType - the memory type used internally for the duration value. Valid types are the following:
        amount - the amount of the duration, measured in terms of the unit, positive or negative
        unit - the unit of the specified amount
        Returns:
        a new TimeDuration instance
        Throws:
        SystemException - with the following reason codes:
        DateTimeException - with the following reason code

      • isNegative

        public boolean isNegative()
        Checks if this duration is negative, excluding zero.

        A duration represents a directed distance between two points on the time-line and can therefore be positive, zero or negative. This method checks whether the length is less than zero.

        Returns:
        true if this duration has a total length less than zero

      • abs

        public TimeDuration abs()
                 throws ArithmeticException
        Update this duration by effectively removing the sign and making this instance a positive duration. For example, -1,300,000 µs (PT-1.3S) will be updated as 1,300,000 µs (PT1.3S).
        Returns:
        this duration with its value made positive.
        Throws:
        ArithmeticException - if numeric overflow occurs (e.g. attempt to get the absolute value of the minimum negative duration -(2^63))

      • neg

        public TimeDuration neg()
                 throws ArithmeticException
        Update this duration with the length negated.

        This method swaps the sign of the total length of this duration. For examples, 1,300,000 µs (PT1.3S) will be updated as -1,300,000 µs (PT-1.3S) and conversely -1,300,000 µs will be updated as +1,300,000 µs.

        Returns:
        this duration with the amount negated
        Throws:
        ArithmeticException - if numeric overflow occurs (e.g. attempt to negate the minimum negative duration -(2^63))

      • reset

        public TimeDuration reset()
        Reset this duration to zero.
        Returns:
        this duration with its value set to 0

      • compareTo

        public short compareTo​(TimeDuration other)
        Compares this duration to the given one.

        In addition to returning a short result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

        Parameters:
        other - the duration to compare with
        Returns:
        • the value 0 if the two duration are equal
        • the value -1 if this duration is less than the other duration
        • the value 1 if this duration is more than the other duration
        Throws:
        NullPointerException - if the parameter is null

      • compareTo

        public short compareTo​(short amount,
                       short unit)
                throws DateTimeException
        Compares this duration to the given amount of time.

        In addition to returning a short result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

        Parameters:
        amount - the amount of time to compare with
        unit - the unit of the specified amount
        Returns:
        • the value 0 if the two duration are equal
        • the value -1 if this duration is less than the other duration
        • the value 1 if this duration is more than the other duration
        Throws:
        DateTimeException - with the following reason codes:

      • minus

        public TimeDuration minus​(TimeDuration duration)
                   throws ArithmeticException
        Update this duration by subtracting the specified duration.

        Examples:

        • TimeDuration.getInstance(mt, 2, SECONDS).minus(TimeDuration.getInstance(mt, 500, MILLIS)) returns a duration of +1.5s (PT1.5S)
        • TimeDuration.getInstance(mt,-2, SECONDS).minus(TimeDuration.getInstance(mt,-500, MILLIS)) returns a duration of -1.5s (PT1.5S)
        • TimeDuration.getInstance(mt,-2, SECONDS).minus(TimeDuration.getInstance(mt, 500, MILLIS)) returns a duration of -2.5s (PT-2.5S)

        Parameters:
        duration - the duration to subtract, not null
        Returns:
        this duration with the specified duration subtracted
        Throws:
        ArithmeticException - if numeric overflow occurs

      • minus

        public TimeDuration minus​(short amount,
                          short unit)
                   throws DateTimeException,
                          ArithmeticException
        Update this duration by subtracting the specified amount of time.

        Examples:

        • TimeDuration.getInstance(mt, 2, SECONDS).minus( 500, MILLIS) returns a duration of +1.5s (PT1.5S)
        • TimeDuration.getInstance(mt,-2, SECONDS).minus(-500, MILLIS) returns a duration of -1.5s (PT1.5S)
        • TimeDuration.getInstance(mt,-2, SECONDS).minus( 500, MILLIS) returns a duration of -2.5s (PT-2.5S)

        Parameters:
        amount - the amount of time to subtract
        unit - the unit of the specified amount
        Returns:
        this duration with the specified duration subtracted
        Throws:
        ArithmeticException - if numeric overflow occurs
        DateTimeException - with the following reason codes:

      • plus

        public TimeDuration plus​(TimeDuration duration)
                  throws ArithmeticException
        Update this duration by adding the specified duration.

        Examples:

        • TimeDuration.getInstance(mt, 2, SECONDS).plus(TimeDuration.getInstance(mt, 500, MILLIS)) returns a duration of +2.5s (PT2.5S)
        • TimeDuration.getInstance(mt,-2, SECONDS).plus(TimeDuration.getInstance(mt, 500, MILLIS)) returns a duration of -1.5s (PT-1.5S)
        • TimeDuration.getInstance(mt,-2, SECONDS).plus(TimeDuration.getInstance(mt,-500, MILLIS)) returns a duration of -2.5s (PT-2.5S)

        Parameters:
        duration - the duration to add, not null.
        Returns:
        this duration with the specified duration added.
        Throws:
        ArithmeticException - if numeric overflow occurs

      • plus

        public TimeDuration plus​(short amount,
                         short unit)
                  throws DateTimeException,
                         ArithmeticException
        Update this duration by adding the specified amount of time.

        Examples:

        • TimeDuration.getInstance(mt, +2, SECONDS).plus( 500, MILLIS) returns a duration of +2.5s (PT2.5S)
        • TimeDuration.getInstance(mt, -2, SECONDS).plus( 500, MILLIS) returns a duration of -1.5s (PT-1.5S)
        • TimeDuration.getInstance(mt, -2, SECONDS).plus(-500, MILLIS) returns a duration of -2.5s (PT-2.5S)

        Parameters:
        amount - the amount of time to add
        unit - the unit of the specified amount
        Returns:
        this duration with the specified duration added
        Throws:
        ArithmeticException - if numeric overflow occurs
        DateTimeException - with the following reason codes:

      • set

        public TimeDuration set​(byte[] input,
                        short offset,
                        short length,
                        short unit)
                 throws DateTimeException,
                        ArithmeticException
        Update this duration with the specified value.

        The new value must be encoded in the input byte array as an hexadecimal number with big-endian byte order and right justification with some leading zeros or sign extension as appropriate.

        Examples:

        • A TimeDuration can be set to 1.3e+6µs (PT1.3S) as follows:
          • using byte[] {0x13, 0xD6, 0x20} and MICROS unit
          • using byte[] {0x00 ... 0x00, 0x13, 0xD6, 0x20} containing leading zeroes and MICROS unit

        • A TimeDuration can be set to -1.3e+6µs (PT-1.3S) as follows:
          • byte[] {0xEC, 0x29, 0xE0} and MICROS unit
          • byte[] {0xFF ... 0xFF, 0xEC, 0x29, 0xE0} with sign extension and MICROS unit

        Parameters:
        input - the input buffer containing the duration value (big-endian)
        offset - the offset within the buffer where the value starts
        length - the length of the duration value in the buffer
        unit - the unit of the specified duration
        Returns:
        this duration with the specified amount set.
        Throws:
        ArithmeticException - if a numeric overflow occurs
        DateTimeException - with the following reason codes:

      • toBytes

        public short toBytes​(byte[] output,
                     short offset,
                     short length,
                     short unit)
              throws DateTimeException
        Gets the integer amount of time, with the specified unit, contained in this duration and writes the result in the output byte array. The encoding is using big-endian byte order and right justification for the number of requested bytes, with leading zeros or sign extension as appropriate.

        Examples:

        • The number of milliseconds in 1.3e+6µs (PT1.3S) is 1,300
          TimeDuration.getInstance(memtype, 1300, MILLIS).toBytes(buffer, (short)0, (short)4, MILLIS) returns [0x00, 0x00, 0x05, 0x14]
        • The number of seconds in 1.3e+6µs (PT1.3S) is 1
          TimeDuration.getInstance(memtype, 1300, MILLIS).toBytes(buffer, (short)0, (short)4, SECONDS) returns [0x00, 0x00, 0x00, 0x01]
        • the number of seconds in -1.3e+6µs (PT-1.3S) is -1
          TimeDuration.getInstance(memtype, -1300, MILLIS).toBytes(buffer, (short)0, (short)4, SECONDS) returns [0xFF, 0xFF, 0xFF, 0xFF]
        • the number of seconds in -1.6e+6µs (PT-1.6S) is -1
          TimeDuration.getInstance(memtype, -1600, MILLIS).toBytes(buffer, (short)0, (short)4, SECONDS) returns [0xFF, 0xFF, 0xFF, 0xFF]

        Parameters:
        output - the output buffer
        offset - the offset in the output buffer
        length - the output length required
        unit - the unit to use for conversion
        Returns:
        offset + length
        Throws:
        DateTimeException - with the following reason codes:
        IndexOutOfBoundsException - if the length required to store the converted duration exceeds the specified length
        See Also:
        getByteLength(short)

      • getByteLength

        public short getByteLength​(short unit)
                    throws DateTimeException
        Returns the minimum number of bytes required to represent the duration in the specified unit. It can be used to compute the length required before calling toBytes(byte[], short, short, short).

        Notes:

        • This method may need to perform the conversion to calculate the length required. For performance reason, it should be used only when length required to encode the duration cannot be estimated.
        • if the duration is positive the length might be adjusted to include a leading zero in order to remove ambiguity (e.g. +128 is encoded as [0x00, 0x80])

        Parameters:
        unit - the unit to use for conversion
        Returns:
        the byte length required to encode the duration in the specified unit
        Throws:
        DateTimeException - with the following reason codes: