Package com.isode.som

Class SomUtcTime

  • public class SomUtcTime
extends java.lang.Object
    This class provides a way to encapsulate a UTCtime struct as used by dcapi to represent time values returned by the DSA. When converting to a Date object, the value will represent a time in the user's current timezone. For example, a UTCtime value of 11am will produce a date with a time of 6am if the current timezone is America/New_York.

    • Constructor Summary

      Constructors 
      Constructor Description
      SomUtcTime()
      Create a new object representing the current date/time in the local timezone.
      SomUtcTime​(int seconds)
      Create a new SomUtcTime, setting it from a seconds value
      SomUtcTime​(java.lang.String utcstring)
      Deprecated. 
      SomUtcTime​(java.lang.String utcstring, SomUtcTime.TimeStringType type)
      Create a new SomUtcTime object, setting its values from the utc or generalized time string passed in
      SomUtcTime​(java.util.Date date)
      Create a new object representing a specific date/time in the local timezone.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.util.Date getDate()
      Return a Java Date object representing the UTCtime.
      static SomUtcTime getEmptyUTCtime()
      Factory method to return an "empty" UTCtime.
      SomUtcTime getOffsetTime​(java.lang.Integer offset)
      Return SomUtcTime object with value shifted by given offset
      void increment​(int seconds)
      Increment the value of a SomUtcTime object by a number of seconds
      boolean isEmpty()
      Determine whether this object represents an empty date.
      static void main​(java.lang.String[] args)
      Main method for unit testing this class.
      java.lang.String offsetFrom​(java.util.Date date)
      Get a string indicating the days, hours, miunutes and seconds offset for this SomUtcTime value from a specified Date
      long offsetMilliSecondsFrom​(java.util.Date date)
      Get a seconds offset for this SomUtcTime value from a specified Date
      java.lang.Integer offsetMinutesFrom​(java.util.Date date)
      Get a minutes offset for this SomUtcTime value from a specified Date
      java.lang.Integer offsetSecondsFrom​(java.util.Date date)
      Get a seconds offset for this SomUtcTime value from a specified Date
      java.lang.String toString()
      Make printable version of the UTCtime.
      java.lang.String toUtcString()
      Make UTC string version of the UTCtime.
      java.lang.String toUtcString​(SomUtcTime.TimeStringType type)
      Make UTC string version of the UTCtime.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • SomUtcTime

        public SomUtcTime​(java.util.Date date)
        Create a new object representing a specific date/time in the local timezone.
        Parameters:
        date - the time/date to use

      • SomUtcTime

        public SomUtcTime​(java.lang.String utcstring)
        Deprecated.
        Create a new SomUtcTime object, setting its values from the time string passed in. This is a compatibility interface which attempts to guess whether the string is UTC or Generalized by inspection. This is not infallible!
        Parameters:
        utcstring - time string to parse

      • SomUtcTime

        public SomUtcTime​(int seconds)
        Create a new SomUtcTime, setting it from a seconds value
        Parameters:
        seconds - value for use in initialization

      • SomUtcTime

        public SomUtcTime()
        Create a new object representing the current date/time in the local timezone.

    • Method Detail

      • offsetSecondsFrom

        public java.lang.Integer offsetSecondsFrom​(java.util.Date date)
        Get a seconds offset for this SomUtcTime value from a specified Date
        Parameters:
        date - Date to get difference from
        Returns:
        Difference in seconds

      • offsetMilliSecondsFrom

        public long offsetMilliSecondsFrom​(java.util.Date date)
        Get a seconds offset for this SomUtcTime value from a specified Date
        Parameters:
        date - Date to get difference from
        Returns:
        Difference in milliseconds

      • offsetMinutesFrom

        public java.lang.Integer offsetMinutesFrom​(java.util.Date date)
        Get a minutes offset for this SomUtcTime value from a specified Date
        Parameters:
        date - Date to get difference from
        Returns:
        Difference in minutes

      • offsetFrom

        public java.lang.String offsetFrom​(java.util.Date date)
        Get a string indicating the days, hours, miunutes and seconds offset for this SomUtcTime value from a specified Date
        Parameters:
        date - Date to get difference from
        Returns:
        String indicating difference

      • increment

        public void increment​(int seconds)
        Increment the value of a SomUtcTime object by a number of seconds
        Parameters:
        seconds - number to increment by

      • getEmptyUTCtime

        public static SomUtcTime getEmptyUTCtime()
        Factory method to return an "empty" UTCtime. This method provides an object suitable to be passed to the JNI layer to be filled in. A call to getDate() on an "empty" UTCtime object will return null.
        Returns:
        an empty UTCtime object

      • isEmpty

        public boolean isEmpty()
        Determine whether this object represents an empty date. An empty UTCtime is one that represents a time field from the DSA which has not been initialised (for example, the last update time of an agreement which has never been updated).
        Returns:
        true if this is an empty date, false otherwise.

      • getDate

        public java.util.Date getDate()
        Return a Java Date object representing the UTCtime.
        Returns:
        the time as a java.util.Date object. For an "empty" UTCtime, a null value will be returned.

      • getOffsetTime

        public SomUtcTime getOffsetTime​(java.lang.Integer offset)
        Return SomUtcTime object with value shifted by given offset
        Parameters:
        offset - in seconds used for shifting
        Returns:
        a new SomUtcTime object

      • toString

        public java.lang.String toString()
        Make printable version of the UTCtime. This will never be null.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a date/time string, or "" for an empty object.

      • toUtcString

        public java.lang.String toUtcString()
        Make UTC string version of the UTCtime. This will never be null.
        Returns:
        UTC time string

      • toUtcString

        public java.lang.String toUtcString​(SomUtcTime.TimeStringType type)
        Make UTC string version of the UTCtime. This will never be null.
        Parameters:
        type - time string type to return
        Returns:
        UTC time string

      • main

        public static void main​(java.lang.String[] args)
        Main method for unit testing this class. The main method constructs a new UTCtime for the current date/time, then turns it into a Date and back into a UTCtime, displaying the results of conversion, which should all be the same, regardless of the current timezone. You can test the class in different timezones by using, e.g. 
           java com.isode.dconsole.UTCtime    (current timezone)
   java -Duser.timezone=America/New_York com.isode.dconsole.UTCtime
   java -Duser.timezone=Australia/Broken_Hill com.isode.dconsole.UTCtime
        See www.worldtimeserver.com to confirm the results
        Parameters:
        args - notused