Class ZDate

java.lang.Object
java.util.Date
org.spiderwiz.zutils.ZDate
All Implemented Interfaces:
Serializable, Cloneable, Comparable<Date>

public final class ZDate
extends Date
Extension of Date that provides extra utility fields and methods.
See Also:
Serialized Form
  • Field Summary

    Fields 
    Modifier and Type Field Description
    static String DATE_FORMAT
    Represents "d/M/yyyy HH:mm" time format.
    static int DAY
    Number of milliseconds in a day (8,640,000).
    static String DAY_MONTH_HOUR_MINUTE
    Represents "dd/MM-HH:mm" time format.
    static ZDate DAY_OF_MESSIAH
    The latest possible date (Long.MAX_VALUE).
    static String FULL_DATE
    Represents "dd/MM/yy-HH:mm:ss" time format.
    static String FULL_DATE_MILLISECONDS
    Represents "dd/MM/yy-HH:mm:ss:SSS" time format.
    static String FULL_TIMESTAMP
    Represents "ddMMyyHHmmssSSS" time format.
    static int HOUR
    Number of milliseconds in an hour (360,000).
    static String HOUR_MINUTE_SECOND
    Represents "HH:mm:ss" time format.
    static int MINUTE
    Number of milliseconds in a minute (60,000).
    static String MINUTE_TIMESTAMP
    Represents "ddMMyyHHmm" time format.
    static String MMDDYYHHMMSS
    Represents "MMddyyHHmmss" time format.
    static int SECOND
    Number of milliseconds in a second (1000).
    static String SORTABLE
    Represents "yyyy-MM-dd'T'HH:mm:ss" time format.
    static String SQL_DATE
    Represents "yyyy-MM-dd HH:mm:ss" time format.
    static String TIMESTAMP
    Represents "ddMMyyHHmmss" time format.
    static String YYMMDD
    Represents "yyMMdd" time format.
    static String YYMMDDHHMM
    Represents "yyMMddHHmm" time format.
    static String YYMMDDHHMMSS
    Represents "yyMMddHHmmss" time format.
    static String YYYYMMDDHHMM
    Represents "yyyyMMddHHmm" time format.
    static String YYYYMMDDHHMMSS
    Represents "yyyyMMddHHmmss" time format.
  • Constructor Summary

    Constructors 
    Constructor Description
    ZDate()
    Constructs an object representing the current time, measured to the nearest millisecond.
    ZDate​(float seconds)
    Constructs an object representing the date of today, with the given amount of seconds, possibly with a faction, from midnight in local time.
    ZDate​(int hour, int minute)
    Constructs an object representing the date of today, with the given hour and minute in local time.
    ZDate​(long date)
    Constructs an object from a value of milliseconds since 1/1/1970 GMT.
    ZDate​(String string, String fmt)
    Constructs an object by parsing the beginning of the given string with a given time format.
    ZDate​(Date date)
    Constructs an object from the value represented by a given Date object.
  • Method Summary

    Modifier and Type Method Description
    ZDate add​(int field, int amount)
    Returns a time object with a value equal to the time in this object plus the given amount of the given time units.
    ZDate add​(long ms)
    Returns a time object with a value equal to the time in this object plus the given amount of milliseconds.
    boolean after​(Date when)
    Returns true if the time of this object is after the time of the given object or if the given object is null.
    boolean before​(Date when)
    Returns true if the time of the given object is not null and the time of this object is before the time of the given object.
    boolean between​(ZDate from, ZDate to)
    Returns true if this object is between the two given time objects, inclusive.
    long diff​(Date date)
    Returns the difference of time in milliseconds from the time represented by the date parameter till the time represented by this object.
    int diffMonths​(Date date)
    Returns the difference in whole months from the time represented by the date parameter till the time represented by this object.
    ZDate earliest​(ZDate when)
    Returns the earliest between this object and the given object.
    long elapsed()
    Returns the time that has elapsed since the time represented by this object in milliseconds.
    String format​(String fmt)
    Formats this object into a time string.
    String formatFullTimestamp()
    Formats this object into a timestamp string using the format "ddMMyyHHmmssSSS".
    String formatGMT​(String fmt)
    Formats this object into a time string representing the time of the object in GMT zone.
    String formatRoundTimestamp​(int precision)
    Formats this object into a rounded timestamp string using the format "ddMMyyHHmmssS(s)" when the number of Ss is the given precision.
    ZDate fromGMT()
    Returns a time object that represents the time of this object after shifting it from GMT time zone.
    static ZDate fromSQLdate​(Date date)
    Converts an SQL Date object to a ZDate object.
    static ZDate fromSQLtime​(Timestamp ts)
    Converts an SQL Timestamp object to a ZDate object.
    static ZDate fromXMLGregorianCalendar​(XMLGregorianCalendar xDate)
    Converts an XMLGregorianCalendar object to a ZDate object.
    int getDay()
    Returns the day of the week represented by this time object.
    int getHours()
    Returns the hour of the day that this time object represents as an integer number between 0 and 23.
    ZDate getMidnight()
    Returns a time object representing the latest midnight that precedes or equals this object.
    int getMinutes()
    Returns the minutes fraction of this time object as an integer number between 0 and 59.
    int getSeconds()
    Returns the seconds fraction of this time object as an integer number between 0 and 59.
    boolean hasCrossed​(long ms)
    Returns true if since the time of the object until now a certain point of time was crossed.
    ZDate latest​(ZDate when)
    Returns the latest between this object and the given object.
    static ZDate now()
    Returns a new time object set to the current time.
    static String now​(String fmt)
    Returns the current time formatted into a string.
    static long nowAsLong()
    Returns the current time as milliseconds since 1/1/1970.
    static ZDate parseFullTimestamp​(String string)
    Parses the beginning of the given string assuming it contains a timestamp value in the format "ddMMyyHHmmssSSS".
    static ZDate parseGMTtime​(String string, String format)
    Parses the beginning of the given string assuming it contains a formatted GMT time string.
    static ZDate parseRoundTime​(String string, int precision)
    Parses the beginning of the given string assuming it contains a rounded timestamp string formatted as "ddMMyyHHmmssS(s)" when the number of Ss is the given precision.
    static ZDate parseTime​(String string, String format, ZDate ts)
    Parses a formatted time string using the given date object to resolve full time data.
    ZDate round​(long roundBy)
    Returns a time object equal to the time represented by this object rounded to the given amount of milliseconds.
    ZDate setTime​(int hour, int minutes)
    Returns a time object with the date of this object and the given hour and minute.
    ZDate toGMT()
    Returns a time object that represents the time of this object after shifting it to GMT time zone.
    Date toSQLdate()
    Returns the time of this object as an SQL Date object.
    Timestamp toSQLtime()
    Returns the time of this object as an SQL Timestamp object.
    XMLGregorianCalendar toXMLGregorianCalendar​(DatatypeFactory factory)
    Returns the time of this object as an XMLGregorianCalendar object, using the given factory for conversion.
    ZDate truncate​(long truncateBy)
    Returns a time object equal to the time represented by this object truncated to a floor value that is a whole multiply of the given amount of milliseconds.

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

  • Constructor Details

    • ZDate

      public ZDate()
      Constructs an object representing the current time, measured to the nearest millisecond.
      See Also:
      now()
    • ZDate

      public ZDate​(long date)
      Constructs an object from a value of milliseconds since 1/1/1970 GMT.
      Parameters:
      date - the milliseconds since January 1, 1970, 00:00:00 GMT.
    • ZDate

      public ZDate​(Date date)
      Constructs an object from the value represented by a given Date object.
      Parameters:
      date - a Date object whose value shall be copied to the constructed object.
    • ZDate

      public ZDate​(int hour, int minute)
      Constructs an object representing the date of today, with the given hour and minute in local time.
      Parameters:
      hour - hour to be set.
      minute - minute to be set.
    • ZDate

      public ZDate​(float seconds)
      Constructs an object representing the date of today, with the given amount of seconds, possibly with a faction, from midnight in local time.
      Parameters:
      seconds - amount of seconds, possibly with a faction, from midnight in local time.
    • ZDate

      public ZDate​(String string, String fmt) throws ParseException
      Constructs an object by parsing the beginning of the given string with a given time format.
      Parameters:
      string - the string to parse
      fmt - the format to use
      Throws:
      ParseException
      See Also:
      SimpleDateFormat, SimpleDateFormat.parse()
  • Method Details

    • now

      public static ZDate now()
      Returns a new time object set to the current time.

      Calling ZDate.now() is equivalent to new ZDate().

      Returns:
      a new time object set to the current time.
      See Also:
      ZDate()
    • now

      public static String now​(String fmt)
      Returns the current time formatted into a string.

      This method is equivalent to new ZDate.format(fmt).

      Parameters:
      fmt - format string
      Returns:
      the current time formatted into a string.
      See Also:
      format()
    • nowAsLong

      public static long nowAsLong()
      Returns the current time as milliseconds since 1/1/1970.
      Returns:
      the current time as milliseconds since 1/1/1970.
    • add

      public ZDate add​(long ms)
      Returns a time object with a value equal to the time in this object plus the given amount of milliseconds.
      Parameters:
      ms - the amount of milliseconds to add.
      Returns:
      a time object with a value equal to the time in this object plus the given amount of milliseconds.
    • add

      public ZDate add​(int field, int amount)
      Returns a time object with a value equal to the time in this object plus the given amount of the given time units.

      This method adds the specified amount of the unit defined by the field parameter to the time of this object and returns the result as a new time object. The possible values of field are those defined by the Field numbers in Calendar class. For instance, add(Calendar.DAY_OF_MONTH, -5) returns a time object that represents the time of 5 days before the time of the object the method is called on.

      Parameters:
      field - the time unit as defined by Calendar class.
      amount - the amount of units to add.
      Returns:
      a time object with a value equal to the time in this object plus the specified amount of the specified time units.
    • diff

      public long diff​(Date date)
      Returns the difference of time in milliseconds from the time represented by the date parameter till the time represented by this object.
      Parameters:
      date - a time object to calculate difference from.
      Returns:
      the difference of time in milliseconds from the time represented by the parameter till the time represented by this object.
    • diffMonths

      public int diffMonths​(Date date)
      Returns the difference in whole months from the time represented by the date parameter till the time represented by this object.
      Parameters:
      date - a time object to calculate difference from.
      Returns:
      the difference in whole months from the time represented by the parameter till the time represented by this object, or zero if the parameter is null.
    • elapsed

      public long elapsed()
      Returns the time that has elapsed since the time represented by this object in milliseconds.
      Returns:
      the time that has elapsed since the time represented by this object in milliseconds.
    • after

      public boolean after​(Date when)
      Returns true if the time of this object is after the time of the given object or if the given object is null.
      Overrides:
      after in class Date
      Parameters:
      when - the time to compare to.
      Returns:
      true if and only if the time of this object is after the time of the given object or if the given object is null.
    • before

      public boolean before​(Date when)
      Returns true if the time of the given object is not null and the time of this object is before the time of the given object.
      Overrides:
      before in class Date
      Parameters:
      when - the time to compare to.
      Returns:
      true if and only if the time of the given object is not null and the time of this object is before the time of the given object.
    • between

      public boolean between​(ZDate from, ZDate to)
      Returns true if this object is between the two given time objects, inclusive.

      The method returns true if and only if the time of this object is not before the time of from parameter and not after the time of to parameter. If from is null then it is considered as the time of the Big Bang, i.e. ever. If to is null it is considered as the coming of Messiah, i.e. forever.

      Parameters:
      from - from time, null is considered as infinite time ago.
      to - to time, null is considered as infinite time ahead.
      Returns:
      true if and only if the object is not before from and not after to.
    • earliest

      public ZDate earliest​(ZDate when)
      Returns the earliest between this object and the given object.

      If the given time object is null or this time object is strictly before when then this object is returned, otherwise when is returned.

      Parameters:
      when - time object to compare to.
      Returns:
      this object is it is before the given object or the given object is null, otherwise return the given object.
    • latest

      public ZDate latest​(ZDate when)
      Returns the latest between this object and the given object.

      If the given time object is null or this time object is strictly after when then this object is returned, otherwise when is returned.

      Parameters:
      when - time object to compare to.
      Returns:
      this object is it is after the given object or the given object is null, otherwise return the given object.
    • getHours

      public int getHours()
      Returns the hour of the day that this time object represents as an integer number between 0 and 23.

      The method overrides the depreciated Date.getHours() and uses the Calendar.get(Calendar.HOUR_OF_DAY) replacement.

      Overrides:
      getHours in class Date
      Returns:
      the hour of the day in the local time zone that this time object represents as an integer number between 0 and 23.
    • getMinutes

      public int getMinutes()
      Returns the minutes fraction of this time object as an integer number between 0 and 59.

      The method overrides the depreciated Date.getMinutes() and uses the Calendar.get(Calendar.MINUTE) replacement.

      Overrides:
      getMinutes in class Date
      Returns:
      the minutes fraction of this time object in the local time zone as an integer number between 0 and 59.
    • getSeconds

      public int getSeconds()
      Returns the seconds fraction of this time object as an integer number between 0 and 59.

      The method overrides the depreciated Date.getSeconds() and uses the Calendar.get(Calendar.SECOND) replacement.

      Overrides:
      getSeconds in class Date
      Returns:
      the seconds fraction of this time object as an integer number between 0 and 59.
    • getDay

      public int getDay()
      Returns the day of the week represented by this time object.

      The method overrides the depreciated Date.getDay() and uses the Calendar.get(Calendar.DAY_OF_WEEK) replacement.

      Overrides:
      getDay in class Date
      Returns:
      the day of the week in the local time zone represented by this object.
    • setTime

      public ZDate setTime​(int hour, int minutes)
      Returns a time object with the date of this object and the given hour and minute.

      The method returns a new time object whose value is a combination of the date of this object with the given hour and minutes. Seconds and milliseconds are set to zero.

      Parameters:
      hour - the given hour
      minutes - the given minutes
      Returns:
      an object with the date of this object and the given hour and minute.
    • format

      public String format​(String fmt)
      Formats this object into a time string.
      Parameters:
      fmt - the given format.
      Returns:
      the formatted string.
      See Also:
      SimpleDateFormat.format()
    • formatFullTimestamp

      public String formatFullTimestamp()
      Formats this object into a timestamp string using the format "ddMMyyHHmmssSSS".
      Returns:
      the formatted string.
    • formatRoundTimestamp

      public String formatRoundTimestamp​(int precision)
      Formats this object into a rounded timestamp string using the format "ddMMyyHHmmssS(s)" when the number of Ss is the given precision.
      Parameters:
      precision - 0 - round by seconds, 1 - round by 10th of a second, 2 - round by 100th of a second, 3 - round by milliseconds (native format).
      Returns:
      the formatted string.
    • formatGMT

      public String formatGMT​(String fmt)
      Formats this object into a time string representing the time of the object in GMT zone.
      Parameters:
      fmt - the given format.
      Returns:
      the formatted string.
    • parseTime

      public static ZDate parseTime​(String string, String format, ZDate ts) throws ParseException
      Parses a formatted time string using the given date object to resolve full time data.

      Parses the beginning of the string parameter assuming it contains a time value formatted with the format parameter. The formatted string may contain partial information, for instance only the time of the day, in which case the method uses the ts parameter to resolve the full time value. If ts is null the current time is used.

      Parameters:
      string - the string to parse.
      format - the format to use.
      ts - the base timestamp. If null, the current time is used.
      Returns:
      the parsed and resolved time object.
      Throws:
      ParseException
    • parseGMTtime

      public static ZDate parseGMTtime​(String string, String format) throws ParseException
      Parses the beginning of the given string assuming it contains a formatted GMT time string.
      Parameters:
      string - the string to parse.
      format - the format to use.
      Returns:
      the parsed time object.
      Throws:
      ParseException
    • parseFullTimestamp

      public static ZDate parseFullTimestamp​(String string) throws ParseException
      Parses the beginning of the given string assuming it contains a timestamp value in the format "ddMMyyHHmmssSSS".
      Parameters:
      string - the string to parse.
      Returns:
      the parsed time object.
      Throws:
      ParseException
    • parseRoundTime

      public static ZDate parseRoundTime​(String string, int precision) throws ParseException
      Parses the beginning of the given string assuming it contains a rounded timestamp string formatted as "ddMMyyHHmmssS(s)" when the number of Ss is the given precision.
      Parameters:
      string - the string to parse.
      precision - 0 - round by seconds, 1 - round by 10th of a second, 2 - round by 100th of a second, 3 - round by milliseconds (native format).
      Returns:
      the parsed time object.
      Throws:
      ParseException
    • toGMT

      public ZDate toGMT()
      Returns a time object that represents the time of this object after shifting it to GMT time zone.

      This method assumes that the time represented by this object is in the local time zone. It allocates a new time object and sets it to the literal time of this object shifted to GMT. For instance if this object represents the time 2pm PST and the local time zone is PST, the returned object represents the time 2pm GMT.

      Returns:
      a time object that represents the time of this object after shifting it to GMT time zone.
    • fromGMT

      public ZDate fromGMT()
      Returns a time object that represents the time of this object after shifting it from GMT time zone.

      This method assumes that the time represented by this object is in GMT time zone. It allocates a new time object and sets it to the literal time of this object shifted to the local time zone. For instance if this object represents the time 2pm GMT and the local time zone is PST, the returned object represents the time 2pm PST.

      Returns:
      a time object that represents the time of this object after shifting it from GMT time zone.
    • round

      public ZDate round​(long roundBy)
      Returns a time object equal to the time represented by this object rounded to the given amount of milliseconds.

      For instance, if roundBy is 1000, the returned time is the time of this object rounded to the nearest second.

      Parameters:
      roundBy - unit of round in milliseconds
      Returns:
      a time object equal to the time represented by this object rounded to the given amount of milliseconds.
    • truncate

      public ZDate truncate​(long truncateBy)
      Returns a time object equal to the time represented by this object truncated to a floor value that is a whole multiply of the given amount of milliseconds.

      For instance, if truncateBy is 1000, the returned time is the latest time in whole seconds that is not after this object.

      Parameters:
      truncateBy - unit of round in milliseconds
      Returns:
      a time object equal to the time represented by this object rounded to the given amount of milliseconds.
    • hasCrossed

      public boolean hasCrossed​(long ms)
      Returns true if since the time of the object until now a certain point of time was crossed.

      The method accepts a parameter that is an amount of milliseconds and checks whether since the time of the object until now the point of time equal to last midnight plus the given milliseconds was crossed, i.e. if that point of time is between the time of the object (exclusive) and the current time (inclusive).

      Parameters:
      ms - milliseconds since last midnight.
      Returns:
      true if and only if the point of time equal to last midnight plus the given amount of milliseconds is between the time of the object (exclusive) and the current time (inclusive).
    • getMidnight

      public ZDate getMidnight()
      Returns a time object representing the latest midnight that precedes or equals this object.
      Returns:
      a time object representing the latest midnight that precedes or equals this object.
    • fromXMLGregorianCalendar

      public static ZDate fromXMLGregorianCalendar​(XMLGregorianCalendar xDate)
      Converts an XMLGregorianCalendar object to a ZDate object.
      Parameters:
      xDate - the given XMLGregorianCalendar object, or null, in which case the method returns null.
      Returns:
      the date as a ZDate object or null if the given XMLGregorianCalendar object is null.
    • toXMLGregorianCalendar

      public XMLGregorianCalendar toXMLGregorianCalendar​(DatatypeFactory factory) throws Exception
      Returns the time of this object as an XMLGregorianCalendar object, using the given factory for conversion.

      Converts the current object to an XMLGregorianCalendar object. Since the conversion requires the use of a DatatypeFactory object whose instantiation consumes heavy resources, the method has a factory parameter that lets you reusing the same object in multiple calls to this method. If you call the method with the value null in this parameter, the method creates a new instance and uses it for the conversion.

      Parameters:
      factory - a factory object used for the conversion. If the value of this parameter is null the method instantiates a new factory object.
      Returns:
      the time of this object as an XMLGregorianCalendar object.
      Throws:
      Exception
    • fromSQLdate

      public static ZDate fromSQLdate​(Date date)
      Converts an SQL Date object to a ZDate object.
      Parameters:
      date - the given SQL Date object, or null, in which case the method returns null.
      Returns:
      the date as a ZDate object or null if the given SQL Date object is null.
    • toSQLdate

      public Date toSQLdate()
      Returns the time of this object as an SQL Date object.
      Returns:
      the time of this object as an SQL Date object.
    • fromSQLtime

      public static ZDate fromSQLtime​(Timestamp ts)
      Converts an SQL Timestamp object to a ZDate object.
      Parameters:
      ts - the given SQL Timestamp object, or null, in which case the method returns null.
      Returns:
      the date as a ZDate object or null if the given SQL Timestamp object is null.
    • toSQLtime

      public Timestamp toSQLtime()
      Returns the time of this object as an SQL Timestamp object.
      Returns:
      the time of this object as an SQL Timestamp object.