net.pricefx.formulaengine

Interface DatamartContext.Calendar

Enclosing interface:

DatamartContext

public static interface DatamartContext.Calendar

Helper class mainly, but not solely, for working with dates and time periods as used in the PA module. In PA, for each Date and DateTime field defined as dimension, the application generates derived fields to denote the calendar 'Week', 'Month', 'Quarter' and 'Year'. For example a PricingDate = '2015-01-02' has corresponding - PricingDateWeek = '2015-W01' - PricingDateMonth = '2015-M01' - PricingDateQuarter = '2015-Q1' - PricingDateYear = '2015' A DateTime fields gets an additional 'Day' field. DM queries can specify filter on those calendar field, and more importantly, roll up data along them. The calendar field values are further abstracted in a TimePeriod. A TimePeriod has a start period and an end period (singular TimePeriods have start = end), and a TimeUnit. A TimePeriod also has a start date and an end date, which defines its alignment with the commonly known Calendar. A TimeUnit can be - DAY, named 'Day' - WEEK, named 'Week' - MONTH, named 'Month' - QUARTER, named 'Quarter' - YEAR, named 'Year' (the name can be used in various helper methods accepting a string argument rather than the enumeration value).

Method Summary

Modifier and Type	Method and Description
String	add(String periodAsString, int numberOfUnits, String unitAsString) Parses the a period string and offsets the start date of the resulting TimePeriod with a number of TimeUnits.
long	getDaysDiff(String endPeriod, String startPeriod) Calculates the number of days between the start date of period1 and end date of period2 (both inclusive).
Date	getEndDate(String period) Returns the end date of given TimePeriod.
Date	getStartDate(String period) Returns the start date of given TimePeriod.
CalendarUtil.TimePeriod	getTimePeriod(String periodAsString) Returns the TimePeriod object matching its string representation.
CalendarUtil.TimePeriod	getTimePeriodByDate(String dateAsString, String unitAsString) Parses a date, as well as a named TimeUnit, resulting in a TimePeriod with that unit that encompasses the given date.
List<String>	getTimePeriodNames(String startPeriodAsString, String endPeriodAsString, String unitAsString) Useful for constructing Options lists (user entry/input parameters).
List<CalendarUtil.TimePeriod>	getTimePeriods(Date startDate, Date endDate, CalendarUtil.TimeUnit unit)
List<CalendarUtil.TimePeriod>	getTimePeriods(String startPeriodAsString, String endPeriodAsString, String unitAsString) Same as above but now returning a list of TimePeriod objects, rather than the corresponding period names.
Date	parseDate(String dateAsString) Not so much a PA specific helper method: best attempt at converting a string representation (not necessarily in the 'yyyy-MM-dd' format) to a Date.
DateTime	parseDateTime(String datetimeAsString) Not so much a PA specific helper method: best attempt at converting a string representation (not necessarily in the 'yyyy-MM-dd'T'HHmmss' format) to a DateTime.
Filter	timePeriodAsFilter(CalendarUtil.TimePeriod timePeriod, String dateDimFieldName) Helper method to build a filter representing dateDimFieldName in [timePeriod.startPeriod, timePeriod.endPeriod] Note the inclusion on both ends; this is to accommodate the most frequent use case where the TimePeriod is a single period, for example InvoiceDate in [2015,2015].

Method Detail

timePeriodAsFilter

Filter timePeriodAsFilter(CalendarUtil.TimePeriod timePeriod,
                          String dateDimFieldName)

Helper method to build a filter representing dateDimFieldName in [timePeriod.startPeriod, timePeriod.endPeriod] Note the inclusion on both ends; this is to accommodate the most frequent use case where the TimePeriod is a single period, for example InvoiceDate in [2015,2015]. An example of a non-singular period filter is [2015-Q1, 2015-Q2]; see TimePerdiod for more details.

Parameters:

timePeriod - The CalendarUtil.TimePeriod that the dateDimFieldName field needs to match.

dateDimFieldName - The Datamart field of type 'Date' to filter on

Returns:

A Filter limiting the given date field to the given time period.

getTimePeriod

CalendarUtil.TimePeriod getTimePeriod(String periodAsString)

Returns the TimePeriod object matching its string representation. For example: '2015-Q1' represents a TimePeriod with start date 2015-01-01 and end date 2015-03-31 and TimeUnit 'Quarter'. The start and end period in this example are both equal to '2015-Q1'. The same time span could be represented by different TimePeriods, such as [2015-M01, 2015-M3], though the latter would have a TimeUnit equal to 'Month', and start and end periods of 2015-M01 and 2015-M03. Different representations are chosen to fit different use cases. TimePeriods are typically used in the build up to a Filter or DatamartContext.DataSlice definition.

Parameters:

periodAsString - Textual representation of a TimePeriod, such as '2015', '2015-Q1' etc.

Returns:

The Corresponding TimePeriod object, to be used as argument in other calendar dependent API calls.

getTimePeriodByDate

CalendarUtil.TimePeriod getTimePeriodByDate(String dateAsString,
                                            String unitAsString)

Parses a date, as well as a named TimeUnit, resulting in a TimePeriod with that unit that encompasses the given date. Example: getTimePeriodByDate("2015-01-02", "Month") results in the [2015-M01] TimePeriod.

Parameters:

dateAsString - A 'yyyy-MM-dd' string representation of Date.

unitAsString - String representation of a TimeUnit.

Returns:

The matching TimePeriod object.

getTimePeriodNames

List<String> getTimePeriodNames(String startPeriodAsString,
                                String endPeriodAsString,
                                String unitAsString)

Useful for constructing Options lists (user entry/input parameters). Returns a chronologically ordered list of TimePeriod names starting with the given start and end period, with each TimePeriod expressed in the given TimeUnit. For example: getTimePeriodNames("2015-Q01", "2015-Q3", "Month") results in ["2015-M01", "2015-M02", ..., "2015-M09"].

Parameters:

startPeriodAsString - String representation of the start TimePeriod.

endPeriodAsString - String representation of the end TimePeriod.

unitAsString - String representation of a TimeUnit.

Returns:

getTimePeriods

List<CalendarUtil.TimePeriod> getTimePeriods(String startPeriodAsString,
                                             String endPeriodAsString,
                                             String unitAsString)

Same as above but now returning a list of TimePeriod objects, rather than the corresponding period names.

Parameters:

startPeriodAsString -

endPeriodAsString -

unitAsString -

Returns:

getTimePeriods

List<CalendarUtil.TimePeriod> getTimePeriods(Date startDate,
                                             Date endDate,
                                             CalendarUtil.TimeUnit unit)

getStartDate

Date getStartDate(String period)

Returns the start date of given TimePeriod.

Parameters:

period - String representation of a TimePeriod.

Returns:

The period's start Date.

getEndDate

Date getEndDate(String period)

Returns the end date of given TimePeriod.

Parameters:

period - String representation of a TimePeriod.

Returns:

The period's end Date.

add

String add(String periodAsString,
           int numberOfUnits,
           String unitAsString)

Parses the a period string and offsets the start date of the resulting TimePeriod with a number of TimeUnits. Examples:

• add("2015", 3, "Month") = "2015"
• add("2015", -3, "Month") = "2014"
• add("2015-M01", 12, "Month") = "2014-M01"

Parameters:

periodAsString - String representation of the end TimePeriod.

numberOfUnits - The Number of TimeUnit to use as the offset.

unitAsString - String representation of a TimeUnit.

Returns:

The resulting offset TimePeriod in the same TimeUnit as the input period.

getDaysDiff

long getDaysDiff(String endPeriod,
                 String startPeriod)

Calculates the number of days between the start date of period1 and end date of period2 (both inclusive). Example: getDaysDiff("2015-M04", "2015-M05") = 61, since there are 30 days in April and 31 days in May.

Parameters:

endPeriod - String representation of the end TimePeriod.

startPeriod - String representation of the start TimePeriod.

Returns:

The number of days covering [startPeriod.startDate, endPeriod.endDate]

parseDate

Date parseDate(String dateAsString)

Not so much a PA specific helper method: best attempt at converting a string representation (not necessarily in the 'yyyy-MM-dd' format) to a Date.

Parameters:

dateAsString - String representation of a Date.

Returns:

The matching Date or null if no match.

parseDateTime

DateTime parseDateTime(String datetimeAsString)

Not so much a PA specific helper method: best attempt at converting a string representation (not necessarily in the 'yyyy-MM-dd'T'HHmmss' format) to a DateTime.

Parameters:

dateAsString - String representation of a DateTime.

Returns:

The matching DateTime or null if no match.