com.pega.pegarules.pub.util

Interface DateTimeUtils

public interface DateTimeUtils

Provides date and time utility methods allowing safe & efficient use of expensive Calendar and Date resources. To get access to DateTimeUtils use the PRThread.getDateTimeUtils() method which returns a reference to this class. Dates that can be parsed by this class are limited to the ones we use: The java.util.Date formatting patterns used look like these: Long Datetime: "MMM dd',' yyyy '-' HH:mm:ss z" Short Datetime: "MM/dd/yy KK:mm a" - Server's default timezone Long Date: "MMM dd',' yyyy" Short Date: "MM/dd/yy" Short Time 1: "HH:mm:ss z" Short Time 2: "KK:mm:ss a" - Server's default timezone Timestamp: "HHmmss" - always considered to be in GMT The 'Standard Pega ISO Date', Pega TimeStamp or datetimestamp is referred to here and elsewhere and is the format used for internal storage of dates and times within PegaRULES. The java.util.Date formatting pattern looks like this: "yyyyMMdd'T'HHmmss.SSS 'GMT'" Legend for all these time format strings: yyyy is the string containing 4 digit year. MM is the string containing a 2 digit month, valid values are 01..12 dd is the string containing a 2 digit day, valid values are 01..31 (with the usual constraints.) HH is the string containing a 2 digit hour, valid values are 00..23. KK is the string containing a 2 digit hour, valid values are 00..11 (has am/pm). mm is the string containing a 2 digit minute, valid values are 00..59 ss is the string containing a 2 digit second, valid values are 00..59 sss is the string containing a 3 digit millisecond, valid values are 000..999 a is the placeholder for the AM/PM indicator - hour always coded with KK. GMT is constant and indicates that the timestamp is always stored as a Greenwich Mean Time.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	COPYRIGHT
static java.lang.String	VERSION

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.String	addMonthsToSameDay(java.lang.String theDate, int numOfMonths) This function will return a date numOfMonths from the specified date, where the day of the week and week of the month are the same.
java.lang.String	addToDate(java.lang.String theDate, java.lang.String days, java.lang.String hours, java.lang.String minutes, java.lang.String seconds) This function will add days, hours,minutes,seconds to the time passed in and will return an ISO time to the caller.
java.lang.String	currentDate(java.lang.String strDateFormat, java.lang.String strTimeZone) Return Today's Date - Keep track of system starts
long	currentTimeUnique() return a long that is unique within this PegaRULES jvm/instance by incrementing a counter while currentTimeMillis remains constant
double	dateTimeDifference(java.lang.String strBeginTime, java.lang.String strEndTime, java.lang.String strPrecision) Computes the difference between two Pega standard internal (ISO) format dates with the result being corrected for the specified precision.
java.lang.String	dateTimeDuration(java.lang.String strBeginTime, java.lang.String strEndTime, java.lang.String strPrecision) compute the difference between two dates (passed as strings)
java.lang.String	formatDateStamp(java.util.Date aDate) Format the specified date as a PegaRULES date stamp (yyyyMMdd)
java.lang.String	formatDateTime(java.lang.String strDateTime, java.lang.String strPattern, java.lang.String strTimeZone, java.lang.String strLocale) (re)format a date/time string using the specified parameters
java.lang.String	formatDateTime(java.lang.String strDateTime, java.lang.String strPattern, java.lang.String strTimeZone, java.lang.String strLocale, boolean boolSupport24hr) (re)format a date/time string using the specified parameters
java.lang.String	formatDateTimeStamp(java.util.Date aDateTime) Format the specified time as a PegaRULES time stamp (ISO format, GMT zone)
java.lang.String	formatTimeOnlyStamp(java.util.Date aTime) Format the specified Time as a PegaRULES Time stamp (HHmmss [assumed GMT])
java.lang.String	formatTimeStamp(java.util.Date aTime) Format the specified Time as a PegaRULES Date Time stamp (ISO format, GMT zone) Note that this method returns a date/time, not a time, for backward compatibility purposes.
java.lang.String	getCurrentTimeStamp() Returns the current date and time as a PegaRULES time stamp (ISO format, GMT zone)
java.util.Date	getDate(java.lang.String strZeusDateTime) Coverts an internal date time stamp into a Java Date object.
long	parseDateString(java.lang.String strDate) Attempts to interpret the string s as a representation of a date and time.
java.util.Date	parseDateTimeStamp(java.lang.String strDateTime) Converts string form of datetimestamp to a Date object.
java.util.Date	parseDateTimeString(java.lang.String strDateTime) Converts string containing various formats of date & datetime into a Date object.
java.util.Date	parseTimeOfDayString(java.lang.String aTime) Converts string form of timestamp to a Date object.
java.lang.String	timeDifference(java.lang.String strStart, int nDays, int nHours, int nMinutes, int nSeconds) adds an interval to the specified time, using "business day" logic see TimeDifferenceBusinessDays uses the server's default calendar and GMT time zone
java.lang.String	timeDifferenceBusinessDays(java.util.Calendar aCalendar, java.lang.String strStart, int nDays, int nHours, int nMinutes, int nSeconds) adds an interval to the specified time, using "business day" logic assumes US business day rules (Saturday/Sunday closed), ignores possibility of holidays (constant 5 day weeks).
java.lang.String	timeDifferenceFirstBusinessDay(java.util.Calendar aCalendar, java.lang.String strStart) returns the first business day after the specified date, using "business day" logic assumes US business day rules (Saturday/Sunday closed), ignores possibility of holidays (constant 5 day weeks).

Field Detail

VERSION

static final java.lang.String VERSION

COPYRIGHT

static final java.lang.String COPYRIGHT

See Also:

Constant Field Values

Method Detail

addToDate

java.lang.String addToDate(java.lang.String theDate,
                         java.lang.String days,
                         java.lang.String hours,
                         java.lang.String minutes,
                         java.lang.String seconds)

This function will add days, hours,minutes,seconds to the time passed in and will return an ISO time to the caller.

Parameters:

theDate - base date to start with

days - to add to base date

hours - to add to base date

minutes - to add to base date

seconds - to add to base date

Returns:

Computed value returned as an internal datetime stamp

currentDate

java.lang.String currentDate(java.lang.String strDateFormat,
                           java.lang.String strTimeZone)

Return Today's Date - Keep track of system starts

Parameters:

strDateFormat - format string to use for creating the date

strTimeZone - Time Zone name

Returns:

date/time string formatted as requested

currentTimeUnique

long currentTimeUnique()

return a long that is unique within this PegaRULES jvm/instance by incrementing a counter while currentTimeMillis remains constant

Returns:

long value, effectively milliseconds * 1000.

dateTimeDifference

double dateTimeDifference(java.lang.String strBeginTime,
                        java.lang.String strEndTime,
                        java.lang.String strPrecision)

Computes the difference between two Pega standard internal (ISO) format dates with the result being corrected for the specified precision.

Parameters:

strBeginTime - Start date formatted in standard internal form.

strEndTime - Ending date formatted in standard internal form.

strPrecision - Units the result is to be interpreted with:

• C - Centuries
• Y - Years
• M - Months
• D - Days
• h - Hours
• m - Minutes
• s - Seconds (Default)
• S - Milliseconds

Returns:

difference in the units specified in the strPrecision parameter

parseTimeOfDayString

java.util.Date parseTimeOfDayString(java.lang.String aTime)

Converts string form of timestamp to a Date object.

Parameters:

aTime - PegaRULES standard timestamp string (HHmmss)

Returns:

Date object, null if date could not be parsed.

getDate

java.util.Date getDate(java.lang.String strZeusDateTime)

Coverts an internal date time stamp into a Java Date object.

Parameters:

strZeusDateTime -

Returns:

the date

getCurrentTimeStamp

java.lang.String getCurrentTimeStamp()

Returns the current date and time as a PegaRULES time stamp (ISO format, GMT zone)

Returns:

PegaRULES standard date/time string

addMonthsToSameDay

java.lang.String addMonthsToSameDay(java.lang.String theDate,
                                  int numOfMonths)

This function will return a date numOfMonths from the specified date, where the day of the week and week of the month are the same.

For example, the gregorian date May 1, 2004 is the first Saturday of the month. Adding 1 month to that will return June 5, 2004, which is also the first Saturday of the month.

Parameters:

theDate - base date to start with

numOfMonths - number of months to add to that date

Returns:

Computed value returned as an internal datetime stamp

dateTimeDuration

java.lang.String dateTimeDuration(java.lang.String strBeginTime,
                                java.lang.String strEndTime,
                                java.lang.String strPrecision)

compute the difference between two dates (passed as strings)

Parameters:

strBeginTime - starting time

strEndTime - ending time

strPrecision - desired precision, one of "CYMDhmsS" to specify century, year, month, hour, minute, second, or millisecond respectively

Returns:

String difference to specified precision, as a string showing from and to range (ISO duration format), null if parameters invalid

parseDateString

long parseDateString(java.lang.String strDate)

Attempts to interpret the string s as a representation of a date and time. If the attempt is successful, the time indicated is returned represented as the distance, measured in milliseconds, of that time from the epoch (00:00:00 GMT on January 1, 1970). If the attempt fails, an IllegalArgumentException is thrown.

It accepts many syntaxes; in particular, it recognizes the IETF standard date syntax: "Sat, 12 Aug 1995 13:30:00 GMT". It also understands the continental U.S. time-zone abbreviations, but for general use, a time-zone offset should be used: "Sat, 12 Aug 1995 13:30:00 GMT+0430" (4 hours, 30 minutes west of the Greenwich meridian). If no time zone is specified, the local time zone is assumed. GMT and UTC are considered equivalent.

The string s is processed from left to right, looking for data of interest. Any material in s that is within the ASCII parenthesis characters ( and ) is ignored. Parentheses may be nested. Otherwise, the only characters permitted within s are these ASCII characters:

 abcdefghijklmnopqrstuvwxyz
 ABCDEFGHIJKLMNOPQRSTUVWXYZ
 0123456789,+-:/

and whitespace characters.

A consecutive sequence of decimal digits is treated as a decimal number:

• If a number is preceded by + or - and a year has already been recognized, then the number is a time-zone offset. If the number is less than 24, it is an offset measured in hours. Otherwise, it is regarded as an offset in minutes, expressed in 24-hour time format without punctuation. A preceding - means a westward offset. Time zone offsets are always relative to UTC (Greenwich). Thus, for example, -5 occurring in the string would mean "five hours west of Greenwich" and +0430 would mean "four hours and thirty minutes east of Greenwich." It is permitted for the string to specify GMT, UT, or UTC redundantly-for example, GMT-5 or utc+0430.
• The number is regarded as a year number if one of the following conditions is true:
  • The number is equal to or greater than 70 and followed by a space, comma, slash, or end of string
  • The number is less than 70, and both a month and a day of the month have already been recognized
  If the recognized year number is less than 100, it is interpreted as an abbreviated year relative to a century of which dates are within 80 years before and 19 years after the time when the Date class is initialized. After adjusting the year number, 1900 is subtracted from it. For example, if the current year is 1999 then years in the range 19 to 99 are assumed to mean 1919 to 1999, while years from 0 to 18 are assumed to mean 2000 to 2018. Note that this is slightly different from the interpretation of years less than 100 that is used in SimpleDateFormat.
• If the number is followed by a colon, it is regarded as an hour, unless an hour has already been recognized, in which case it is regarded as a minute.
• If the number is followed by a slash, it is regarded as a month (it is decreased by 1 to produce a number in the range 0 to 11), unless a month has already been recognized, in which case it is regarded as a day of the month.
• If the number is followed by whitespace, a comma, a hyphen, or end of string, then if an hour has been recognized but not a minute, it is regarded as a minute; otherwise, if a minute has been recognized but not a second, it is regarded as a second; otherwise, it is regarded as a day of the month.

A consecutive sequence of letters is regarded as a word and treated as follows:

• A word that matches AM, ignoring case, is ignored (but the parse fails if an hour has not been recognized or is less than 1 or greater than 12).
• A word that matches PM, ignoring case, adds 12 to the hour (but the parse fails if an hour has not been recognized or is less than 1 or greater than 12).
• Any word that matches any prefix of SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, or SATURDAY, ignoring case, is ignored. For example, sat, Friday, TUE, and Thurs are ignored.
• Otherwise, any word that matches any prefix of JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, or DECEMBER, ignoring case, and considering them in the order given here, is recognized as specifying a month and is converted to a number (0 to 11). For example, aug, Sept, april, and NOV are recognized as months. So is Ma, which is recognized as MARCH, not MAY.
• Any word that matches GMT, UT, or UTC, ignoring case, is treated as referring to UTC.
• Any word that matches EST, CST, MST, or PST, ignoring case, is recognized as referring to the time zone in North America that is five, six, seven, or eight hours west of Greenwich, respectively. Any word that matches EDT, CDT, MDT, or PDT, ignoring case, is recognized as referring to the same time zone, respectively, during daylight saving time.

Once the entire string s has been scanned, it is converted to a time result in one of two ways. If a time zone or time-zone offset has been recognized, then the year, month, day of month, hour, minute, and second are interpreted in UTC and then the time-zone offset is applied. Otherwise, the year, month, day of month, hour, minute, and second are interpreted in the local time zone.

Parameters:

strDate - a string to be parsed as a date.

Returns:

the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by the string argument.

See Also:

officially deprecated As of JDK version 1.1, replaced by DateFormat.parse(String s).

parseDateTimeStamp

java.util.Date parseDateTimeStamp(java.lang.String strDateTime)

Converts string form of datetimestamp to a Date object.

Parameters:

strDateTime - PegaRULES standard date/time string

Returns:

Date object, null if date could not be parsed.

parseDateTimeString

java.util.Date parseDateTimeString(java.lang.String strDateTime)

Converts string containing various formats of date & datetime into a Date object.

Parameters:

strDateTime - The various supported input date formats.

Returns:

Date object, null if date could not be parsed.

formatDateTime

java.lang.String formatDateTime(java.lang.String strDateTime,
                              java.lang.String strPattern,
                              java.lang.String strTimeZone,
                              java.lang.String strLocale)

(re)format a date/time string using the specified parameters

Parameters:

strDateTime - input time string

strPattern - (unused)

strTimeZone - timezone for output string, if null, the server's default is used

strLocale - locale to use for formatting, if null, the server's default is used

Returns:

String formatted for specified locale, null if strDateTime is null

formatDateTime

java.lang.String formatDateTime(java.lang.String strDateTime,
                              java.lang.String strPattern,
                              java.lang.String strTimeZone,
                              java.lang.String strLocale,
                              boolean boolSupport24hr)

(re)format a date/time string using the specified parameters

Parameters:

strDateTime - input time string

strPattern - (unused)

strTimeZone - timezone for output string, if null, the server's default is used

strLocale - locale to use for formatting, if null, the server's default is used

boolSupport24hr -

Returns:

String formatted for specified locale, null if strDateTime is null

formatDateTimeStamp

java.lang.String formatDateTimeStamp(java.util.Date aDateTime)

Format the specified time as a PegaRULES time stamp (ISO format, GMT zone)

Parameters:

aDateTime - Date object

Returns:

PegaRULES standard date/time string; empty string if aDateTime is null

formatDateStamp

java.lang.String formatDateStamp(java.util.Date aDate)

Format the specified date as a PegaRULES date stamp (yyyyMMdd)

Parameters:

aDate - Date object

Returns:

PegaRULES standard date string; empty string if aDate is null

formatTimeStamp

java.lang.String formatTimeStamp(java.util.Date aTime)

Format the specified Time as a PegaRULES Date Time stamp (ISO format, GMT zone) Note that this method returns a date/time, not a time, for backward compatibility purposes.

Parameters:

aTime - object

Returns:

PegaRULES standard date time string; empty string if aTime is null

formatTimeOnlyStamp

java.lang.String formatTimeOnlyStamp(java.util.Date aTime)

Format the specified Time as a PegaRULES Time stamp (HHmmss [assumed GMT])

Parameters:

aTime - object

Returns:

PegaRULES standard time string; empty string if aTime is null

timeDifference

java.lang.String timeDifference(java.lang.String strStart,
                              int nDays,
                              int nHours,
                              int nMinutes,
                              int nSeconds)

adds an interval to the specified time, using "business day" logic see TimeDifferenceBusinessDays uses the server's default calendar and GMT time zone

Parameters:

strStart - base date/time, if null or zero length, uses the current date and time

nDays - number of days to add

nHours - number of hours to add

nMinutes - number of minutes to add

nSeconds - number of seconds to add

Returns:

String using SimpleDateFormat("E' 'yyyy'/'MM'/'dd' 'HH':'mm':'ss z") and the server's default time zone

timeDifferenceBusinessDays

java.lang.String timeDifferenceBusinessDays(java.util.Calendar aCalendar,
                                          java.lang.String strStart,
                                          int nDays,
                                          int nHours,
                                          int nMinutes,
                                          int nSeconds)

adds an interval to the specified time, using "business day" logic assumes US business day rules (Saturday/Sunday closed), ignores possibility of holidays (constant 5 day weeks).

Parameters:

aCalendar - calendar to be used for computation, if null, uses the server's default calendar and local time zone

strStart - base date/time, if null or zero length, uses the current date and time

nDays - number of days to add

nHours - number of hours to add

nMinutes - number of minutes to add

nSeconds - number of seconds to add

Returns:

String using SimpleDateFormat("E' 'yyyy'/'MM'/'dd' 'HH':'mm':'ss z") and the server's default time zone

timeDifferenceFirstBusinessDay

java.lang.String timeDifferenceFirstBusinessDay(java.util.Calendar aCalendar,
                                              java.lang.String strStart)

returns the first business day after the specified date, using "business day" logic assumes US business day rules (Saturday/Sunday closed), ignores possibility of holidays (constant 5 day weeks).

Parameters:

aCalendar - calendar to be used for computation, if null, uses the server's default calendar and GMT time zone

strStart - base date/time, if null or zero length, uses the current date and time

Returns:

String using SimpleDateFormat("E' 'yyyy'/'MM'/'dd' 'HH':'mm':'ss z") and the server's default time zone