Package 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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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​(String startPeriodAsString, String endPeriodAsString, String unitAsString)
      Same as above but now returning a list of TimePeriod objects, rather than the corresponding period names.
      List<CalendarUtil.TimePeriod> getTimePeriods​(Date startDate, Date endDate, CalendarUtil.TimeUnit unit)  
      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.