Interface DatamartContext.Calendar
- All Known Implementing Classes:
DMCalendar
- Enclosing interface:
DatamartContext
Helper class mainly for working with dates and time periods as used in the PriceAnalyzer module. In PA, for each Date and DateTime field defined as a dimension, the application generates derived fields to denote the calendar 'Week', 'Month', 'Quarter' and 'Year'. For example, a PricingDate = '2015-01-02' has a corresponding:
- PricingDateWeek = '2015-W01'
- PricingDateMonth = '2015-M01'
- PricingDateQuarter = '2015-Q1'
- PricingDateYear = '2015'
DM queries can specify a filter on these calendar fields 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 define 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'
-
Method Summary
Modifier and TypeMethodDescriptionParses 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).getEndDate
(String period) Returns the end date of a given TimePeriod.getStartDate
(String period) Returns the start date of a given TimePeriod.getTimePeriod
(String periodAsString) Returns the TimePeriod object matching its string representation.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.getTimePeriodNames
(String startPeriodAsString, String endPeriodAsString, String unitAsString) Useful for constructing Options lists (user entry / input parameters).getTimePeriods
(String startPeriodAsString, String endPeriodAsString, String unitAsString) The same asgetTimePeriodNames(String, String, String)
but it returns a list of TimePeriod objects, rather than the corresponding period names.getTimePeriods
(Date startDate, Date endDate, CalendarUtil.TimeUnit unit) 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.timePeriodAsFilter
(CalendarUtil.TimePeriod timePeriod, String dateDimFieldName) Helper method to build a filter representingdateDimFieldName
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 Details
-
timePeriodAsFilter
Helper method to build a filter representingdateDimFieldName
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]; seeCalendarUtil.TimePeriod
for more details.- Parameters:
timePeriod
-CalendarUtil.TimePeriod
that thedateDimFieldName
field needs to match.dateDimFieldName
- Datamart field of the type 'Date' to filter on.- Returns:
Filter
limiting the given date field to the given time period.
-
getTimePeriod
Returns the TimePeriod object matching its string representation. For example, '2015-Q1' represents a TimePeriod with the start date 2015-01-01 and end date 2015-03-31 and TimeUnit 'Quarter'. The start and end periods 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 aFilter
orDatamartContext.DataSlice
definition.- Parameters:
periodAsString
- Textual representation of a TimePeriod, such as '2015', '2015-Q1' etc.- Returns:
- The Corresponding TimePeriod object to be used as an argument in other calendar dependent API calls.
-
getTimePeriodByDate
Parses a date, as well as a named TimeUnit, resulting in a TimePeriod with that unit that encompasses the given date. For example, getTimePeriodByDate("2015-01-02", "Month") results in the [2015-M01] TimePeriod.- Parameters:
dateAsString
- 'yyyy-MM-dd' string representation ofDate
.unitAsString
- String representation of a TimeUnit.- Returns:
- 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 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) The same asgetTimePeriodNames(String, String, String)
but it returns 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
Returns the start date of a given TimePeriod.- Parameters:
period
- String representation of a TimePeriod.- Returns:
- Period's start Date.
-
getEndDate
Returns the end date of a given TimePeriod.- Parameters:
period
- String representation of a TimePeriod.- Returns:
- Period's end Date.
-
add
Parses 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
- Number of TimeUnits to use as the offset.unitAsString
- String representation of a TimeUnit.- Returns:
- Resulting offset TimePeriod in the same TimeUnit as the input period.
-
getDaysDiff
Calculates the number of days between the start date of period1 and end date of period2 (both inclusive). For 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:
- Number of days covering [startPeriod.startDate, endPeriod.endDate].
-
parseDate
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:
- Matching Date or
null
if no match.
-
parseDateTime
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:
datetimeAsString
- String representation of a DateTime.- Returns:
- Matching
DateTime
ornull
if no match.
-