DateTimeUtils (PegaRULES Java Engine v6.3)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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
`static java.lang.String`	`COPYRIGHT`
`static java.lang.String`	`VERSION`

Method Summary
`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`	`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

COPYRIGHT

static final java.lang.String COPYRIGHT

See Also:: Constant Field Values

VERSION

static final java.lang.String VERSION

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

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