Package net.pricefx.formulaengine

Interface DatamartContext.Calendar

All Known Implementing Classes:
DMCalendar
Enclosing interface:
DatamartContext
public static interface DatamartContext.Calendar

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'
A DateTime field gets an additional 'Day' field.

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'
The name can be used in various helper methods accepting a string argument rather than the enumeration value.

  • Method Details

    • 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 CalendarUtil.TimePeriod for more details.
      Parameters:
      timePeriod - CalendarUtil.TimePeriod that the dateDimFieldName 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

      CalendarUtil.TimePeriod getTimePeriod(String periodAsString)
      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 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 an 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. For example, getTimePeriodByDate("2015-01-02", "Month") results in the [2015-M01] TimePeriod.
      Parameters:
      dateAsString - 'yyyy-MM-dd' string representation of Date.
      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 as getTimePeriodNames(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

      Date getStartDate(String period)
      Returns the start date of a given TimePeriod.
      Parameters:
      period - String representation of a TimePeriod.
      Returns:
      Period's start Date.

    • getEndDate

      Date getEndDate(String period)
      Returns the end date of a given TimePeriod.
      Parameters:
      period - String representation of a TimePeriod.
      Returns:
      Period's end Date.

    • add

      String add(String periodAsString, int numberOfUnits, String unitAsString)
      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

      long getDaysDiff(String endPeriod, String startPeriod)
      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

      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:
      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:
      datetimeAsString - String representation of a DateTime.
      Returns:
      Matching DateTime or null if no match.