org.sandev.basics.util
Class DateUtil

java.lang.Object
  org.sandev.basics.util.DateUtil

public class DateUtil
extends java.lang.Object

Common date manipulation utilities.

Constructor Summary

DateUtil()

Method Summary

static java.util.Date	dateFromShortRead(java.lang.String datestr) Inverse of getShortReadDate.
static java.lang.String	debug(java.util.Calendar cal) Utility method for dumping out a calendar as a debug string.
static java.lang.String	getBasicTime(java.util.Calendar cal) Return the hours and minutes for the given calendar.
static java.lang.String	getDateTimeAsTextNumber(java.util.Calendar cal) Given a calendar, return a text numeric representation of the date and time.
static java.lang.String	getDateTimeAsTextNumber(java.util.Date date) Get the given date as a text number using the default Calendar.
static java.lang.String	getDateTimeAsTextNumberUTC(java.util.Date date) Calls the standard getDateTimeAsTextNumber with a UTC calendar.
static java.util.Date	getDateTimeFromTextNumber(java.lang.String text, java.util.Calendar cal) Read the given text numeric representation and of the date and time and return the corresponding date.
static java.util.Date	getNowUTC() Returns the current UTC time as a Date.
static java.lang.String	getQueryValue(java.util.Calendar cal) Return the query string format for this date value.
static java.lang.String	getQueryValue(java.util.Date date) Convenience wrapper that gets a new Calendar instance for the given date before calling through to the calendar version of the same method.
static java.lang.String	getShortFileDate(java.util.Calendar cal) Return a short date identifier useful for naming a file.
static java.lang.String	getShortFileDate(java.util.Date date) Convenience wrapper which gets a new Calendar instance for the given date before calling through to the calendar version of the same method.
static java.lang.String	getShortReadDate(java.util.Calendar cal) Return a short day-month-year representation that can be used as a prefix string when chronological ordering does not have to be the same as alphabetic ordering.
static java.lang.String	getShortReadDate(java.util.Date date) Convenience wrapper which gets a new Calendar instance for the given date before calling through to the calendar version of the same method.
static java.lang.String	getShortReadDateTime(java.util.Date date) Convenience wrapper that gets a new Calendar instance for the given date before calling through to the calendar based method.
static java.lang.String	getShortReadDateTimeUTC(java.util.Date date) Convenience wrapper that gets a new Calendar instance for the given date before calling through to the calendar based method.
static java.util.Calendar	getUTCCalendar() Return a Calendar instance set for UTC.
static java.lang.String	getUTCQueryValue(java.util.Date date) Convenience wrapper that gets a new UTC Calendar instance of the given date before calling through.
static java.util.Calendar	initUTCCalendar(java.util.Date date) Initialize a calendar instance to the given UTC date and return it.
static void	roundToThresholdHour(java.util.Calendar cal, int hour) Round to the next occurrence of the threshold hour.
static void	roundUpHourPeriod(java.util.Calendar cal, int hourPeriod) Round up to the nearest hour interval defined by the given period hours.
static void	roundUpMillis(java.util.Calendar cal) Round up the given calendar to the nearest second.
static void	roundUpMinutePeriod(java.util.Calendar cal, int minutePeriod) Round up to the nearest minute interval defined by the given period minutes.
static void	roundUpMinutes(java.util.Calendar cal) Round up the given calendar to the nearest hour.
static void	roundUpSeconds(java.util.Calendar cal) Round up the given calendar to the nearest minute.
static boolean	sameLongValue(java.util.Date date1, java.util.Date date2) Return true if the two dates represent the same instant in time as calculated to the nearest millisecond, false otherwise.
static java.util.Date	utc2WallClock(java.util.Date utcDate, int offset) Return a date that displays as the wall clock time for the given UTC date and offset.
static java.lang.String	utcstr(java.util.Date date) Return a string representation of the given UTC datetime.
static java.util.Date	wallClock2UTC(java.util.Date wcDate, int offset) Return the original UTC date from the given wall clock display date and the user offset.
static boolean	within(java.util.Date date, int seconds) Return true if the given date is within the given number of seconds from our current time, false otherwise.

Methods inherited from class java.lang.Object

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

Constructor Detail

DateUtil

public DateUtil()

Method Detail

getShortReadDate

public static java.lang.String getShortReadDate(java.util.Date date)

Convenience wrapper which gets a new Calendar instance for the given date before calling through to the calendar version of the same method.

getShortReadDate

public static java.lang.String getShortReadDate(java.util.Calendar cal)

Return a short day-month-year representation that can be used as a prefix string when chronological ordering does not have to be the same as alphabetic ordering. This returns values like "27may05".

dateFromShortRead

public static java.util.Date dateFromShortRead(java.lang.String datestr)

Inverse of getShortReadDate. 12dec07

getBasicTime

public static java.lang.String getBasicTime(java.util.Calendar cal)

Return the hours and minutes for the given calendar.

getShortReadDateTime

public static java.lang.String getShortReadDateTime(java.util.Date date)

Convenience wrapper that gets a new Calendar instance for the given date before calling through to the calendar based method.

getShortFileDate

public static java.lang.String getShortFileDate(java.util.Date date)

Convenience wrapper which gets a new Calendar instance for the given date before calling through to the calendar version of the same method.

getShortFileDate

public static java.lang.String getShortFileDate(java.util.Calendar cal)

Return a short date identifier useful for naming a file. This is something like "2004_05_27" or "2004_11_09" so that a pile of these files will be ordered correctly via directory access.

getDateTimeAsTextNumber

public static java.lang.String getDateTimeAsTextNumber(java.util.Date date)

Get the given date as a text number using the default Calendar. Caution: This uses the default timezone. If you want anything other than the local timezone applied, then get the appropriate Calendar and call using that instead.

getDateTimeAsTextNumber

public static java.lang.String getDateTimeAsTextNumber(java.util.Calendar cal)

Given a calendar, return a text numeric representation of the date and time. Returns YYYYMMDDHHMM (24 hr clock). This method takes a Calendar rather than a Date because the Calendar sets the timezone we are working with.

getDateTimeFromTextNumber

public static java.util.Date getDateTimeFromTextNumber(java.lang.String text,
                                                       java.util.Calendar cal)

Read the given text numeric representation and of the date and time and return the corresponding date. Returns null if the given text could not be parsed into a date value. The Calendar parameter is required if anything other than the default is to be used for reconstructing the date. Note that the default serialization of the returned date value does not reflect the timezone of the calendar (if specified) but still represents the correct millisecond value.

getQueryValue

public static java.lang.String getQueryValue(java.util.Date date)

Convenience wrapper that gets a new Calendar instance for the given date before calling through to the calendar version of the same method.

getQueryValue

public static java.lang.String getQueryValue(java.util.Calendar cal)

Return the query string format for this date value. This is the quoted timestamp text format of the given date, which is used in query processing.

within

public static boolean within(java.util.Date date,
                             int seconds)

Return true if the given date is within the given number of seconds from our current time, false otherwise.

sameLongValue

public static boolean sameLongValue(java.util.Date date1,
                                    java.util.Date date2)

Return true if the two dates represent the same instant in time as calculated to the nearest millisecond, false otherwise. If either parameter is null, the result is false.

Why not just use java.util.Date.equals? Basically because it doesn't always work. In a WhereWhen message with a field called "start" we added the following instrumentation to the "start" comparison in the generated isEquivalent method:

   System.out.println("WhereWhen.isEquivalent: start is different");
   System.out.println("         start: " + start);
   System.out.println("msg.getStart(): " + msg.getStart());
   System.out.println("         start.getTime(): " + start.getTime());
   System.out.println("msg.getStart().getTime(): " + msg.getStart().getTime());
 

which produced the following output:

   WhereWhen.isEquivalent: start is different
            start: 2006-07-27 14:30:00.0
   msg.getStart(): Thu Jul 27 14:30:00 EDT 2006
            start.getTime(): 1154025000000
   msg.getStart().getTime(): 1154025000000
 

As you can see, the milliseconds are the same even though Date.equals said they were not the same. The default output formatting is a giveaway that the actual Date objects were different, and Date.equals returns false, but the milliseconds are the same. We need a real millisecond comparison without any nonsense, which is what this method does.

debug

public static java.lang.String debug(java.util.Calendar cal)

Utility method for dumping out a calendar as a debug string. This is here because Calendar.toString gives an exhaustive dump of all the calendar fields, but Calendar.getDate().toString() uses the local timezone of the runtime environment. This does a simple format dump of the date with the actual timezone.

getNowUTC

public static java.util.Date getNowUTC()

Returns the current UTC time as a Date.

getUTCCalendar

public static java.util.Calendar getUTCCalendar()

Return a Calendar instance set for UTC. Retrieving a calendar using the default Calendar.getInstance method typically gets you a calendar that takes into account daylight savings time which can mess up offset calculations.

initUTCCalendar

public static java.util.Calendar initUTCCalendar(java.util.Date date)

Initialize a calendar instance to the given UTC date and return it.

getUTCQueryValue

public static java.lang.String getUTCQueryValue(java.util.Date date)

Convenience wrapper that gets a new UTC Calendar instance of the given date before calling through.

utcstr

public static java.lang.String utcstr(java.util.Date date)

Return a string representation of the given UTC datetime. This method is typically used for debug or log output just to make the UTC dates be more generally recognizable. Not used for serialization, see the StringUtil date methods for that.

Returns the string "null" if given a null date, just to make debugging use a bit friendlier.

getDateTimeAsTextNumberUTC

public static java.lang.String getDateTimeAsTextNumberUTC(java.util.Date date)

Calls the standard getDateTimeAsTextNumber with a UTC calendar.

getShortReadDateTimeUTC

public static java.lang.String getShortReadDateTimeUTC(java.util.Date date)

Convenience wrapper that gets a new Calendar instance for the given date before calling through to the calendar based method.

utc2WallClock

public static java.util.Date utc2WallClock(java.util.Date utcDate,
                                           int offset)

Return a date that displays as the wall clock time for the given UTC date and offset. This is intended to provide a wall clock display using the current server time as a base. In other words this will return a date that displays as the wall clock time of the location with the given offset, using the default timezone of the runtime environment. Useful for forcing a display through default timezones.

wallClock2UTC

public static java.util.Date wallClock2UTC(java.util.Date wcDate,
                                           int offset)

Return the original UTC date from the given wall clock display date and the user offset. This is intended to be the inverse operation for utc2WallClock, and assumes that we are translating using the current server time.

There is a slight chance that we may have passed a DST boundary from the time when we displayed the given date to the time when we are translating it back, but that's pretty unlikely and there's not much we can do about it.

roundUpMillis

public static void roundUpMillis(java.util.Calendar cal)

Round up the given calendar to the nearest second. So 03:00:00.001 becomes 03:00:01.000.

roundUpSeconds

public static void roundUpSeconds(java.util.Calendar cal)

Round up the given calendar to the nearest minute. So 03:00:01 becomes 03:01:00.

roundUpMinutes

public static void roundUpMinutes(java.util.Calendar cal)

Round up the given calendar to the nearest hour. So 03:01 becomes 04:00.

roundUpMinutePeriod

public static void roundUpMinutePeriod(java.util.Calendar cal,
                                       int minutePeriod)

Round up to the nearest minute interval defined by the given period minutes. For example if you want to round to the nearest quarter hour, you would pass in 15 as the minutePeriod. The calendar will be rounded up to the nearest minute first.

roundUpHourPeriod

public static void roundUpHourPeriod(java.util.Calendar cal,
                                     int hourPeriod)

Round up to the nearest hour interval defined by the given period hours. For example if you want to bump things up to the end of morning or end of day you would pass in an hourPeriod of 12. The calendar will be rounded to the nearest hour first.

roundToThresholdHour

public static void roundToThresholdHour(java.util.Calendar cal,
                                        int hour)

Round to the next occurrence of the threshold hour. So if have a threshold of 18 (the 6PM hour), and the calendar is currently 14:00 (2:00PM) then 4 hours will be added to the calendar. If it is currently 20:00 (8:00PM), then 22 hours will be added to the calendar to wrap it around to the threshold on the following day.