com.atlassian.core.util
Class DateUtils

java.lang.Object
  com.atlassian.core.util.DateUtils

public class DateUtils
extends Object

Nested Class Summary

static class	DateUtils.DateRange
static class	DateUtils.Duration

Field Summary

static String	AM
static long	DAY_MILLIS
static long	HOUR_MILLIS
static DateFormat	ISO8601DateFormat Date Format to be used for internal logging operations
static long	MINUTE_MILLIS
static long	MONTH_MILLIS
static String	PM
static long	SECOND_MILLIS
static long	YEAR_MILLIS

Constructor Summary

DateUtils(ResourceBundle resourceBundle)

Method Summary

static String	dateDifference(long dateA, long dateB, long resolution, ResourceBundle resourceBundle) Resolution is the degree of difference.
String	dateDifferenceBean(long dateA, long dateB, long resolution, ResourceBundle resourceBundle)
static boolean	equalTimestamps(Timestamp t1, Timestamp t2) compares if these two timestamps are within 10 milliseconds of each other (precision error)
static String	formatDateISO8601(Date ts)
String	formatDurationPretty(long l) This is used by the Velocity templates as a bean
String	formatDurationPretty(String seconds) This is used by the Velocity templates as a bean
String	formatDurationString(long l) Deprecated. You should be calling formatDurationPretty
static int	get24HourTime(String meridianIndicator, int hours)
static Calendar	getCalendarDay(int year, int month, int day)
static Date	getDateDay(int year, int month, int day)
static long	getDuration(String durationStr) Given a duration string, get the number of seconds it represents (all case insensitive): w = weeks d = days h = hours m = minutes If no category is specified, assume minutes. Each field must be separated by a space, and they can come in any order.
static long	getDuration(String durationStr, DateUtils.Duration defaultUnit) Given a duration string, get the number of seconds it represents (all case insensitive): w = weeks d = days h = hours m = minutes ie 2h = 7200, 60m = 3600, 3d = 259200, 30m
static long	getDuration(String durationStr, int hoursPerDay, int daysPerWeek) This function retrieves a duration in seconds that depends on number of hours in a day and days in a week.
static long	getDuration(String durationStr, int hoursPerDay, int daysPerWeek, DateUtils.Duration defaultUnit) This function retrieves a duration in seconds that depends on number of hours in a day and days in a week
static String	getDurationPretty(long numSecs, int hoursPerDay, int daysPerWeek, ResourceBundle resourceBundle) Converts a number of seconds into a pretty formatted data string.
static String	getDurationPretty(long numSecs, ResourceBundle resourceBundle) Converts a number of seconds into a pretty formatted data string.
static String	getDurationPrettySeconds(long numSecs, long secondsPerDay, long secondsPerWeek, ResourceBundle resourceBundle) Get a pretty formatted duration for the given number of seconds.
static String	getDurationPrettySecondsResolution(long numSecs, int hoursPerDay, int daysPerWeek, ResourceBundle resourceBundle) Converts a number of seconds into a pretty formatted data string.
static String	getDurationPrettySecondsResolution(long numSecs, ResourceBundle resourceBundle) Converts a number of seconds into a pretty formatted data string.
static long	getDurationSeconds(String durationStr, long secondsPerDay, long secondsPerWeek, DateUtils.Duration defaultUnit) Convert a duration string in the number of seconds it represents.
static String	getDurationString(long seconds) Get String representation of a duration
static String	getDurationString(long l, int hoursPerDay, int daysPerWeek) Get a duration string representing the given number of seconds.
static String	getDurationStringSeconds(long l, long secondsPerDay, long secondsPerWeek) Get a duration string representing the given number of seconds.
static String	getDurationStringWithNegative(long seconds) Get String representation of a (possibly negative) duration.
static long	getDurationWithNegative(String durationStr) Get a duration string with the possibility of a negative.
static Date	getSqlDateDay(int year, int month, int day)
static DateUtils.DateRange	toDateRange(Calendar date, int period) Given a period, and a date that falls within that period, create a range of dates such that the period is contained exactly within [startDate <= {range} < endDate]
static Calendar	toEndOfPeriod(Calendar calendar, int period) Change the date of a Calendar object so that it has the maximum resolution of "period" where period is one of the constants in CALENDAR_PERIODS above.
static Date	tomorrow()
static Calendar	toStartOfPeriod(Calendar calendar, int period) Change the date of a Calendar object so that it has the minimum resolution of "period" where period is one of the constants in CALENDAR_PERIODS above.
static boolean	validDuration(String s) Check whether a given duration string is valid
static Date	yesterday()

Methods inherited from class java.lang.Object

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

Field Detail

SECOND_MILLIS

public static final long SECOND_MILLIS

MINUTE_MILLIS

public static final long MINUTE_MILLIS

HOUR_MILLIS

public static final long HOUR_MILLIS

DAY_MILLIS

public static final long DAY_MILLIS

MONTH_MILLIS

public static final long MONTH_MILLIS

YEAR_MILLIS

public static final long YEAR_MILLIS

AM

public static final String AM

See Also:

Constant Field Values

PM

public static final String PM

See Also:

Constant Field Values

ISO8601DateFormat

public static final DateFormat ISO8601DateFormat

Date Format to be used for internal logging operations

Constructor Detail

DateUtils

public DateUtils(ResourceBundle resourceBundle)

Method Detail

equalTimestamps

public static boolean equalTimestamps(Timestamp t1,
                                      Timestamp t2)

compares if these two timestamps are within 10 milliseconds of each other (precision error)

Parameters:

t1 - first timestamp to compare

t2 - second timestamp to compare

Returns:

true if the two timestamps are within 10 milliseconds of one another

dateDifferenceBean

public String dateDifferenceBean(long dateA,
                                 long dateB,
                                 long resolution,
                                 ResourceBundle resourceBundle)

dateDifference

public static String dateDifference(long dateA,
                                    long dateB,
                                    long resolution,
                                    ResourceBundle resourceBundle)

Resolution is the degree of difference.

0 = months 1 = days 2 = hours 3 = minutes 4 = seconds

Parameters:

dateA - first date to compare

dateB - second date to compare

resolution - the degree of difference

resourceBundle - contains localizations for core.dateutils strings

Returns:

the difference between the two dates as a human readable string (i.e. 2 months, 3 days, 4 hours)

formatDateISO8601

public static String formatDateISO8601(Date ts)

validDuration

public static boolean validDuration(String s)

Check whether a given duration string is valid

Parameters:

s - the duration string

Returns:

true if it a valid duration

getDuration

public static long getDuration(String durationStr)
                        throws InvalidDurationException

Given a duration string, get the number of seconds it represents (all case insensitive):

• w = weeks
• d = days
• h = hours
• m = minutes

If no category is specified, assume minutes.
Each field must be separated by a space, and they can come in any order. Case is ignored.

ie 2h = 7200, 60m = 3600, 3d = 259200, 30m

Parameters:

durationStr - the duration string

Returns:

the duration in seconds

Throws:

InvalidDurationException - if the duration is invalid

getDuration

public static long getDuration(String durationStr,
                               DateUtils.Duration defaultUnit)
                        throws InvalidDurationException

Given a duration string, get the number of seconds it represents (all case insensitive):

• w = weeks
• d = days
• h = hours
• m = minutes

ie 2h = 7200, 60m = 3600, 3d = 259200, 30m

Parameters:

durationStr - the duration string

defaultUnit - the unit used when another is not specified in the durationStr

Returns:

the duration in seconds

Throws:

InvalidDurationException - if the duration is invalid

getDuration

public static long getDuration(String durationStr,
                               int hoursPerDay,
                               int daysPerWeek)
                        throws InvalidDurationException

This function retrieves a duration in seconds that depends on number of hours in a day and days in a week. The default unit is MINUTE (i.e. "2" == "2 minutes")

Parameters:

durationStr - to convert to a duration

hoursPerDay - Number of hourse i day

daysPerWeek - Days Per Week

Returns:

the duration in seconds

Throws:

InvalidDurationException - if its badly formatted duration

getDuration

public static long getDuration(String durationStr,
                               int hoursPerDay,
                               int daysPerWeek,
                               DateUtils.Duration defaultUnit)
                        throws InvalidDurationException

This function retrieves a duration in seconds that depends on number of hours in a day and days in a week

Parameters:

durationStr - to convert to a duration

hoursPerDay - Number of hourse i day

daysPerWeek - Days Per Week

defaultUnit - the unit used when one is not specified on a measure in the durationStr

Returns:

the duration in seconds

Throws:

InvalidDurationException - if its badly formatted duration

getDurationWithNegative

public static long getDurationWithNegative(String durationStr)
                                    throws InvalidDurationException

Get a duration string with the possibility of a negative.

A duration will be considered negative if the first non-space character is a - sign.

Parameters:

durationStr - the duration string

Returns:

the duration in seconds, which can be negative

Throws:

InvalidDurationException - if its a badly formatted duration

getDurationSeconds

public static long getDurationSeconds(String durationStr,
                                      long secondsPerDay,
                                      long secondsPerWeek,
                                      DateUtils.Duration defaultUnit)
                               throws InvalidDurationException

Convert a duration string in the number of seconds it represents. This method takes seconds per day and seconds per weeks instead of "hours per day" or "days per week" because we may want a non-integral number of hours per day.

Parameters:

durationStr - the duration string

secondsPerDay - number of seconds in a working "day" (e.g. could be equal 6.5 hours)

secondsPerWeek - number of seconds in a working "week" (e.g. could be equal to 4.5 days)

defaultUnit - the unit to use for numbers with no unit specified (e.g. "12")

Returns:

the number of seconds representing the duration string

Throws:

InvalidDurationException - if the duration string cannot be parsed

getDurationString

public static String getDurationString(long seconds)

Get String representation of a duration

Parameters:

seconds - Number of seconds

Returns:

String representing duration, eg: "1h 30m"

See Also:

getDurationStringWithNegative(long)

getDurationStringWithNegative

public static String getDurationStringWithNegative(long seconds)

Get String representation of a (possibly negative) duration.

Parameters:

seconds - Number of seconds

Returns:

String representing duration, eg: "-1h 30m"

See Also:

getDurationString(long)

getDurationString

public static String getDurationString(long l,
                                       int hoursPerDay,
                                       int daysPerWeek)

Get a duration string representing the given number of seconds. The string will use the largest unit possible. (i.e. 1w 3d)

Parameters:

l - the number of seconds

hoursPerDay - hours in a working day

daysPerWeek - days in a working week

Returns:

the duration string

getDurationStringSeconds

public static String getDurationStringSeconds(long l,
                                              long secondsPerDay,
                                              long secondsPerWeek)

Get a duration string representing the given number of seconds. The string will use the largest unit possible. (i.e. 1w 3d). Use this method when you want to specify a non-integral number of hours in a day (e.g. 7.5) or days per week.

Parameters:

l - the number of seconds

secondsPerDay - the number of seconds in a working day

secondsPerWeek - the number of seconds in a working week

Returns:

the formatted duration string

getDurationPretty

public static String getDurationPretty(long numSecs,
                                       ResourceBundle resourceBundle)

Converts a number of seconds into a pretty formatted data string. The resolution is in minutes. So if the number of seconds is greater than a minute, it will only be shown down top minute resolution. If the number of seconds is less than a minute it will be shown in seconds.

So for example 76 becomes '1 minute', while 42 becomes '42 seconds'

Parameters:

numSecs - the number of seconds in the duration

resourceBundle - a resouce bundle for i18n

Returns:

a string in readable pretty duration format, using minute resolution

getDurationPretty

public static String getDurationPretty(long numSecs,
                                       int hoursPerDay,
                                       int daysPerWeek,
                                       ResourceBundle resourceBundle)

Converts a number of seconds into a pretty formatted data string. The resolution is in minutes. So if the number of seconds is greater than a minute, it will only be shown down top minute resolution. If the number of seconds is less than a minute it will be shown in seconds.

So for example 76 becomes '1 minute', while 42 becomes '42 seconds'

Parameters:

numSecs - the number of seconds in the duration

hoursPerDay - the hours in a day

daysPerWeek - the number of days in a week

resourceBundle - a resouce bundle for i18n

Returns:

a string in readable pretty duration format, using minute resolution

getDurationPrettySecondsResolution

public static String getDurationPrettySecondsResolution(long numSecs,
                                                        ResourceBundle resourceBundle)

Converts a number of seconds into a pretty formatted data string. The resolution is in seconds.

So for example 76 becomes '1 minute, 16 seconds', while 42 becomes '42 seconds'

Parameters:

numSecs - the number of seconds in the duration

resourceBundle - a resouce bundle for i18n

Returns:

a string in readable pretty duration format, using second resolution

getDurationPrettySecondsResolution

public static String getDurationPrettySecondsResolution(long numSecs,
                                                        int hoursPerDay,
                                                        int daysPerWeek,
                                                        ResourceBundle resourceBundle)

Converts a number of seconds into a pretty formatted data string. The resolution is in seconds.

So for example 76 becomes '1 minute, 16 seconds', while 42 becomes '42 seconds'

Parameters:

numSecs - the number of seconds in the duration

hoursPerDay - the hours in a day

daysPerWeek - the number of days in a week

resourceBundle - a resouce bundle for i18n

Returns:

a string in readable pretty duration format, using second resolution

getDurationPrettySeconds

public static String getDurationPrettySeconds(long numSecs,
                                              long secondsPerDay,
                                              long secondsPerWeek,
                                              ResourceBundle resourceBundle)

Get a pretty formatted duration for the given number of seconds. (e.g. "4 days, 2 hours, 30 minutes")

Parameters:

numSecs - the number of seconds in the duration

secondsPerDay - the number of seconds in a "day"

secondsPerWeek - the number of seconds in a "week"

resourceBundle - the bundle containing translations for the strings used in the pretty string (e.g. "days")

Returns:

the formatted pretty duration

formatDurationPretty

public String formatDurationPretty(long l)

This is used by the Velocity templates as a bean

Parameters:

l - a duration in seconds

Returns:

a pretty formatted version of the duration

formatDurationPretty

public String formatDurationPretty(String seconds)

This is used by the Velocity templates as a bean

Parameters:

seconds - duration as a string

Returns:

a pretty formatted version of the duration

formatDurationString

public String formatDurationString(long l)

Deprecated. You should be calling formatDurationPretty

This is used by the WebWork tags as a bean Despite the name it doesn't actually format a duration string. It takes a long.

Parameters:

l - a duration in seconds

Returns:

a pretty formatted version of the duration

See Also:

formatDurationPretty(long)

toEndOfPeriod

public static Calendar toEndOfPeriod(Calendar calendar,
                                     int period)

Change the date of a Calendar object so that it has the maximum resolution of "period" where period is one of the constants in CALENDAR_PERIODS above.

e.g. to obtain the maximum value for a month, call toEndOfPeriod(calendarObject, Calendar.MONTH)

Parameters:

calendar - The Calendar to change

period - The period to "maximise"

Returns:

A modified Calendar object

toStartOfPeriod

public static Calendar toStartOfPeriod(Calendar calendar,
                                       int period)

Change the date of a Calendar object so that it has the minimum resolution of "period" where period is one of the constants in CALENDAR_PERIODS above.

Parameters:

calendar - calendar to modify

period - the new calendar period from CALENDAR_PERIODS

Returns:

the calendar that was passed in

toDateRange

public static DateUtils.DateRange toDateRange(Calendar date,
                                              int period)

Given a period, and a date that falls within that period, create a range of dates such that the period is contained exactly within [startDate <= {range} < endDate]

Parameters:

date - a calendar object of a date falling in that range

period - something in CALENDAR_PERIODS

Returns:

resulting range of dates

getCalendarDay

public static Calendar getCalendarDay(int year,
                                      int month,
                                      int day)

getDateDay

public static Date getDateDay(int year,
                              int month,
                              int day)

getSqlDateDay

public static Date getSqlDateDay(int year,
                                 int month,
                                 int day)

get24HourTime

public static int get24HourTime(String meridianIndicator,
                                int hours)

tomorrow

public static Date tomorrow()

yesterday

public static Date yesterday()