com.technia.tvc.core.db

Class DateUtils

java.lang.Object

com.technia.tvc.core.db.DateUtils

public final class DateUtils
extends java.lang.Object

Contains utility methods for parsing and formatting dates that have been retrieved from or shall be inserted into a Matrix database.

Method Summary

Modifier and Type	Method and Description
static java.util.Date	clone(java.util.Date date) Clone of date safely without the need for null-checks.
static java.text.DateFormat	createDisplayFormatInstance(java.util.Locale locale, java.lang.String format, java.lang.Boolean displayTime) Returns a DateFormat instance that can be used to format dates for display in the user interface.
static java.lang.String	format(java.util.Date date) Format a java.util.Date instance to a format that is accepted by Matrix when editing a datetime property.
static java.lang.String	format(java.text.DateFormat format, java.util.TimeZone tz, java.util.Date date) Formats a particular date with a date format.
static java.lang.String	format(java.text.DateFormat format, java.util.TimeZone tz, long date)
static java.lang.String	format(java.util.Date date, java.util.TimeZone tz, java.util.Locale locale)
static java.lang.String	formatForDisplay(java.util.Date date, java.util.Locale locale) Format a java.util.Date instance to a display-friendly format for the specified locale.
static java.lang.String	formatForDisplay(java.lang.String date, java.util.Locale locale) Format a date value retrieved from Matrix into the display format for the specified locale.
static java.lang.String	formatISO8601Date(java.util.Date date) Formats the date according to yyyy-MM-dd.
static java.lang.String	formatISO8601Date(java.util.Date date, java.util.TimeZone tz) Returns the ISO-8601 formatted date string using the specified time zone
static java.lang.String	formatISO8601Date(long date) Formats the date according to yyyy-MM-dd.
static java.lang.String	formatISO8601Date(long date, java.util.TimeZone tz) Returns the ISO-8601 formatted date string using the specified time zone
static java.lang.String	formatISO8601DateTime(java.util.Date date) Formats the date according to yyyy-MM-dd'T'HH:mm:ss.
static java.lang.String	formatISO8601DateTime(java.util.Date date, java.util.TimeZone tz) Returns the ISO-8601 formatted date+time string using the specified time zone.
static java.lang.String	formatISO8601DateTime(long date) Formats the date according to yyyy-MM-dd'T'HH:mm:ss.
static java.lang.String	formatISO8601DateTime(long date, java.util.TimeZone tz) Returns the ISO-8601 formatted date+time string using the specified time zone.
static java.lang.String	formatISO8601Time(java.util.Date date) Formats the date according to HH:mm:ss.
static java.lang.String	formatISO8601Time(long date) Formats the date according to HH:mm:ss.
static java.text.DateFormat	getDateDisplayFormatInstance(java.util.Locale locale) Returns a date format instance that can be used to format dates for display in the user interface.
static java.text.DateFormat	getDateFormatInstance() Returns a java.text.DateFormat instance that can be used to parse datetime values retrieved from Matrix to java.util.Date instances.
static java.text.DateFormat	getDateTimeDisplayFormatInstance(java.util.Locale locale) Returns a date format instance that can be used to format dates for display in the user interface.
static java.text.DateFormat	getDisplayFormatInstance() Returns a DateFormat instance that can be used to format dates for display in the user interface.
static java.text.DateFormat	getDisplayFormatInstance(java.util.Locale locale) Returns the default DateFormat instance that can be used to format dates for display in the user interface.
static java.lang.String	getDurationString(java.util.Locale locale, long time)
static java.lang.String	getDurationString(java.util.Locale locale, long start, long end) Returns the duration between two times in a more user friendly format
static java.util.Calendar	getGregorianCalendar() Returns a Gregorian Calendar instance.
static java.text.DateFormat	getInputDateFormatInstance() Returns a java.text.DateFormat instance that can be used to convert java.util.Date instances to a format accepted by Matrix when editing a datetime property.
static java.util.TimeZone	getUserTimeZone() Reads the preference "preference_TimeZone" on the Person admin object, and returns a corresponding TimeZone instance.
static java.util.Date	parse(java.lang.String dateTimeValue) Parse a datetime value retrieved from Matrix to a java.util.Date instance.
static java.util.Date	parse(java.lang.String dateTimeValue, boolean noErrorLog) Parse a datetime value retrieved from Matrix to a java.util.Date based on boolean.
static java.util.Date	parse(java.lang.String dateTimeValue, java.util.TimeZone tz) Parse a date time value retrieved from Matrix to a java.util.Date based on time zone
static java.util.Date	parseISO8601Date(java.lang.String s) Parse a date from the string.
static java.util.Date	parseISO8601Date(java.lang.String s, java.util.TimeZone tz) Parse a date from the string based on timezone.
static java.util.Date	parseISO8601DateTime(java.lang.String s) Parse a date from the string.
static java.util.Date	parseISO8601DateTime(java.lang.String s, java.util.TimeZone tz) Parse a date from the string based on time zone.
static long	toMilliSeconds(java.lang.String s) Parses a string containing a time definition into milliseconds.
static long	toMilliSeconds(java.lang.String s, boolean timeUnits) See toMilliSeconds(String) for details.
static java.util.TimeZone	utc() Returns the UTC time zone instance.

Methods inherited from class java.lang.Object

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

Method Detail

clone

public static java.util.Date clone(java.util.Date date)

Clone of date safely without the need for null-checks.

Parameters:

date - The date to clone.

Returns:

The cloned date or null if the date argument was null.

Since:

2014.1.0

utc

public static java.util.TimeZone utc()

Returns the UTC time zone instance.

Returns:

The UTC time zone

Since:

2010.3.0

formatISO8601Date

public static java.lang.String formatISO8601Date(java.util.Date date,
                                                 java.util.TimeZone tz)

Returns the ISO-8601 formatted date string using the specified time zone

Parameters:

date - The date to format

tz - The time zone instance

Returns:

The ISO-8601 formatted date string

Since:

2010.3.0

See Also:

format(DateFormat, TimeZone, Date)

formatISO8601Date

public static java.lang.String formatISO8601Date(long date,
                                                 java.util.TimeZone tz)

Returns the ISO-8601 formatted date string using the specified time zone

Parameters:

date - The date to format

tz - The time zone instance

Returns:

The ISO-8601 formatted date string

Since:

2010.3.0

See Also:

format(DateFormat, TimeZone, long)

formatISO8601DateTime

public static java.lang.String formatISO8601DateTime(java.util.Date date,
                                                     java.util.TimeZone tz)

Returns the ISO-8601 formatted date+time string using the specified time zone.

Parameters:

date - The date to format

tz - The time zone instance

Returns:

The ISO-8601 formatted date and time string

Since:

2010.3.0

See Also:

format(DateFormat, TimeZone, Date)

formatISO8601DateTime

public static java.lang.String formatISO8601DateTime(long date,
                                                     java.util.TimeZone tz)

Returns the ISO-8601 formatted date+time string using the specified time zone.

Parameters:

date - The date to format

tz - The time zone instance

Returns:

The ISO-8601 formatted date and time string

Since:

2010.3.0

See Also:

format(DateFormat, TimeZone, long)

format

public static java.lang.String format(java.text.DateFormat format,
                                      java.util.TimeZone tz,
                                      long date)

Parameters:

format - The date format instance

tz - The time zone instance

date - The date to format

Returns:

The formatted value

Since:

2010.3.0

See Also:

format(DateFormat, TimeZone, Date)

format

public static java.lang.String format(java.text.DateFormat format,
                                      java.util.TimeZone tz,
                                      java.util.Date date)

Formats a particular date with a date format.

The time is converted to the provided time zone. If the tz argument is null, the default time zone is used ( TimeZone.getDefault()).

Parameters:

format - The DateFormat

tz - The time zone instance

date - The date to format

Returns:

The formatted value

Since:

2010.3.0

format

public static java.lang.String format(java.util.Date date,
                                      java.util.TimeZone tz,
                                      java.util.Locale locale)

Parameters:

date - The date to format

tz - The time zone instance

locale - The locale instance

Returns:

The formatted value

Since:

2010.3.0

getUserTimeZone

public static java.util.TimeZone getUserTimeZone()
                                          throws TVCException

Reads the preference "preference_TimeZone" on the Person admin object, and returns a corresponding TimeZone instance.

Returns:

The User Time Zone (read from the preferences on the user)

Throws:

TVCException

Since:

2010.3.0

getDurationString

public static java.lang.String getDurationString(java.util.Locale locale,
                                                 long time)

getDurationString

public static java.lang.String getDurationString(java.util.Locale locale,
                                                 long start,
                                                 long end)

Returns the duration between two times in a more user friendly format

Parameters:

locale - The locale (null implies English locale)

start - The start time

end - The end time (if less than 0; the current time will be used)

Returns:

The duration represented in a string

Since:

2010.3.0

parse

public static java.util.Date parse(java.lang.String dateTimeValue)

Parse a datetime value retrieved from Matrix to a java.util.Date instance.

parse

public static java.util.Date parse(java.lang.String dateTimeValue,
                                   boolean noErrorLog)

Parse a datetime value retrieved from Matrix to a java.util.Date based on boolean.

parse

public static java.util.Date parse(java.lang.String dateTimeValue,
                                   java.util.TimeZone tz)

Parse a date time value retrieved from Matrix to a java.util.Date based on time zone

Parameters:

dateTimeValue - A string representing the date.

tz - Time zone

Returns:

java.util.Date

Since:

2018.6.0

format

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

Format a java.util.Date instance to a format that is accepted by Matrix when editing a datetime property.

formatForDisplay

public static java.lang.String formatForDisplay(java.util.Date date,
                                                java.util.Locale locale)

Format a java.util.Date instance to a display-friendly format for the specified locale.

formatForDisplay

public static java.lang.String formatForDisplay(java.lang.String date,
                                                java.util.Locale locale)

Format a date value retrieved from Matrix into the display format for the specified locale.

Since:

4.0

getDateFormatInstance

public static java.text.DateFormat getDateFormatInstance()

Returns a java.text.DateFormat instance that can be used to parse datetime values retrieved from Matrix to java.util.Date instances.

getInputDateFormatInstance

public static java.text.DateFormat getInputDateFormatInstance()

Returns a java.text.DateFormat instance that can be used to convert java.util.Date instances to a format accepted by Matrix when editing a datetime property.

getGregorianCalendar

public static java.util.Calendar getGregorianCalendar()

Returns a Gregorian Calendar instance. Note: The instance is thread safe, however - it will be reused SO do not try to keep references to the calendar itself. Use it to manipulate Date instances only.

Since:

5.2.1

getDisplayFormatInstance

public static java.text.DateFormat getDisplayFormatInstance()

Returns a DateFormat instance that can be used to format dates for display in the user interface. The returned DateFormat will use the default locale for TVC, use getDisplayFormatInstance(Locale) to get an instance that is localized for a specified user.

Since:

3.0.1

getDisplayFormatInstance

public static java.text.DateFormat getDisplayFormatInstance(java.util.Locale locale)

Returns the default DateFormat instance that can be used to format dates for display in the user interface.

Note that the created DateFormat instance will be configured according to settings made inside the emxSystem.properties file. E.g.

• emxFramework.DateTime.DisplayFormat
• emxFramework.DateTime.DisplayTime

Parameters:

locale - The current locale. Null value forces the server default locale to be used.

Returns:

A DateFormat instance

getDateDisplayFormatInstance

public static java.text.DateFormat getDateDisplayFormatInstance(java.util.Locale locale)

Returns a date format instance that can be used to format dates for display in the user interface. Note that the returned instance will never display the time, only dates. However, the date displayed can be configured inside the emxSystem.properties file. e.g.

• emxFramework.DateTime.DisplayFormat

Parameters:

locale - The current locale. Null value forces the server default locale to be used.

Returns:

A DateFormat instance

Since:

2011.3.0

getDateTimeDisplayFormatInstance

public static java.text.DateFormat getDateTimeDisplayFormatInstance(java.util.Locale locale)

Returns a date format instance that can be used to format dates for display in the user interface. Note that the returned instance will always display the date AND time. However, the date displayed can be configured inside the emxSystem.properties file. e.g.

• emxFramework.DateTime.DisplayFormat

Parameters:

locale - The current locale. Null value forces the server default locale to be used.

Returns:

A DateFormat instance

Since:

2011.3.0

createDisplayFormatInstance

public static java.text.DateFormat createDisplayFormatInstance(java.util.Locale locale,
                                                               java.lang.String format,
                                                               java.lang.Boolean displayTime)

Returns a DateFormat instance that can be used to format dates for display in the user interface. In addition to the getDisplayFormatInstance(Locale) method, this method allows you to override the default values for format and displayTime. Therefore, this method will always create a new instance that will be returned.

Parameters:

locale - The locale of the displayed date. If null, the system wide default value will be used.

format - The format. Should equal to either SHORT, MEDIUM, LONG or FULL. If null, the system wide default value will be used.

displayTime - Whether to display time. If null, the system wide default value will be used.

Returns:

Returns a new DateFormat instance.

Since:

6.0.1

formatISO8601Date

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

Formats the date according to yyyy-MM-dd.

Parameters:

date - The date to format.

Returns:

A date string in the format yyyy-MM-dd.

Since:

5.0.0

formatISO8601Date

public static java.lang.String formatISO8601Date(long date)

Formats the date according to yyyy-MM-dd.

Parameters:

date - The date to format expressed in milliseconds.

Returns:

A date string in the format yyyy-MM-dd.

Since:

5.0.0

formatISO8601Time

public static java.lang.String formatISO8601Time(long date)

Formats the date according to HH:mm:ss.

Parameters:

date - The date to format expressed in milliseconds.

Returns:

A date string in the format HH:mm:ss.

Since:

2010.3.1

formatISO8601Time

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

Formats the date according to HH:mm:ss.

Parameters:

date - The date to format.

Returns:

A date string in the format HH:mm:ss.

Since:

2010.3.1

parseISO8601Date

public static java.util.Date parseISO8601Date(java.lang.String s)
                                       throws java.text.ParseException

Parse a date from the string. The string must be formatted as yyyy-MM-dd.

Parameters:

s - A string representing the date.

Returns:

The date that was parsed from the string.

Throws:

java.text.ParseException - If unable to parse the specified string.

Since:

5.0.0

parseISO8601Date

public static java.util.Date parseISO8601Date(java.lang.String s,
                                              java.util.TimeZone tz)
                                       throws java.text.ParseException

Parse a date from the string based on timezone. The string must be formatted as yyyy-MM-dd.

Parameters:

s - A string representing the date.

tz - Time zone

Returns:

The date that was parsed from the string.

Throws:

java.text.ParseException - If unable to parse the specified string.

Since:

2018.6.0

formatISO8601DateTime

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

Formats the date according to yyyy-MM-dd'T'HH:mm:ss.

Parameters:

date - The date to format.

Returns:

A date string in the format yyyy-MM-dd'T'HH:mm:ss.

Since:

5.0.0

formatISO8601DateTime

public static java.lang.String formatISO8601DateTime(long date)

Formats the date according to yyyy-MM-dd'T'HH:mm:ss.

Parameters:

date - The date to format expressed in milliseconds.

Returns:

A date string in the format yyyy-MM-dd'T'HH:mm:ss.

Since:

5.0.0

parseISO8601DateTime

public static java.util.Date parseISO8601DateTime(java.lang.String s)
                                           throws java.text.ParseException

Parse a date from the string. The string must be formatted as yyyy-MM-dd'T'HH:mm:ss.

Parameters:

s - A string representing the date.

Returns:

The date that was parsed from the string.

Throws:

java.text.ParseException - If unable to parse the specified string.

Since:

5.0.0

parseISO8601DateTime

public static java.util.Date parseISO8601DateTime(java.lang.String s,
                                                  java.util.TimeZone tz)

Parse a date from the string based on time zone. The string must be formatted as yyyy-MM-dd'T'HH:mm:ss.

Parameters:

s - A string representing the date.

tz - Time zone

Returns:

The date that was parsed from the string.

Throws:

java.text.ParseException - If unable to parse the specified string.

Since:

2018.6.0

toMilliSeconds

public static long toMilliSeconds(java.lang.String s)

Parses a string containing a time definition into milliseconds.

Below is a table showing some examples of different arguments and how it will be interpreted:

Specification	Parsed Into
10s	10000 ms
1m	60000 ms
1m 10s	70000 ms
1h 55m 10s	6910000 ms

The string must follow this specification:

 spec :== <part>(<sep><part>)*
 part :== [0-9]*[WwHhMmSs]
 sep  :== anything (space, comma, character etc.)
 

Some notes:

w or W is representing a week (7 days)

d or D is representing one day (24 hours)

m or M is representing one minute (60 seconds)

Parameters:

s - The string to parse

Returns:

The time in milliseconds, which the string represents

Since:

2011.1.0

toMilliSeconds

public static long toMilliSeconds(java.lang.String s,
                                  boolean timeUnits)

See toMilliSeconds(String) for details.

The difference is that if the argument timeUnits is set to false, then the hour, minute and second fields are ignored. The 'm' or 'M' character is treated as month.

Parameters:

s - The string to parse

timeUnits - True if to treat 'm' or 'M' as minute and 's' or 'S' as seconds. If false, 's' or 'S' is ignored and 'm' or 'M' are treated as months.

Returns:

The time in milliseconds, which the string represents

Since:

2012.2.0