javacardx.framework.time.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 final short

DAYS

Unit that represents the concept of a day.

static final short

HOURS

Unit that represents the concept of an hour.

static final short

MICROS

Unit that represents the concept of a microsecond.

static final short

MILLIS

Unit that represents the concept of a millisecond.

static final short

MINUTES

Unit that represents the concept of a minute.

static final short

SECONDS

Unit that represents the concept of a second.
Method Summary

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.

Methods inherited from class Object
equals

Modifier and Type

Method

Description

boolean

equals(Object obj)

Compares two Objects for equality.

Field Details
- 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 Details
- 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:
  
  JCSystem.MEMORY_TYPE_PERSISTENT
  
  JCSystem.MEMORY_TYPE_TRANSIENT_DESELECT
  
  JCSystem.MEMORY_TYPE_TRANSIENT_RESET
  
  Returns:
  
  a new TimeDuration instance
  
  Throws:
  
  SystemException - with the following reason codes:
  
  SystemException.ILLEGAL_VALUE if memoryType is not a valid memory type.
  SystemException.NO_TRANSIENT_SPACE if sufficient transient space is not available.
  SystemException.NO_RESOURCE if not enough resources to allocate the instance
- 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:
  
  JCSystem.MEMORY_TYPE_PERSISTENT
  
  JCSystem.MEMORY_TYPE_TRANSIENT_DESELECT
  
  JCSystem.MEMORY_TYPE_TRANSIENT_RESET
  
  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:
  
  SystemException.ILLEGAL_VALUE if memoryType is not a valid memory type.
  SystemException.NO_TRANSIENT_SPACE if sufficient transient space is not available.
  SystemException.NO_RESOURCE if not enough resources to allocate the instance
  
  DateTimeException - with the following reason code
  
  DateTimeException.INVALID_UNIT if the unit is invalid
- getMemoryType
  public byte getMemoryType()
  
  Returns the memory type specified at object creation and used to store the value.
  The method returns one of the following constants:
  
  JCSystem.MEMORY_TYPE_PERSISTENT if the internal value is persistent,
  
  JCSystem.MEMORY_TYPE_TRANSIENT_DESELECT if the internal value is transient and cleared on CLEAR_ON_DESELECT event,
  
  JCSystem.MEMORY_TYPE_TRANSIENT_RESET if the internal value is transient and cleared on CLEAR_ON_RESET event.
  
  Returns:
  
  the memory type used to store the value
- 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:
  
  DateTimeException.INVALID_UNIT if the unit is invalid
- 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:
  
  DateTimeException.INVALID_UNIT if the unit is invalid
- 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:
  
  DateTimeException.INVALID_UNIT if the unit is invalid
- 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:
  
  DateTimeException.INVALID_UNIT if the unit is invalid
- 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:
  
  DateTimeException.INVALID_UNIT if the unit is invalid
  
  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:
  
  DateTimeException.INVALID_UNIT if the unit is invalid

Class TimeDuration

Field Summary

Method Summary

Methods inherited from class Object

Field Details

MICROS

MILLIS

SECONDS

MINUTES

HOURS

DAYS

Method Details

getInstance

getInstance

getMemoryType

isNegative

abs

neg

reset

compareTo

compareTo

minus

minus

plus

plus

set

toBytes

getByteLength