Class Frequency

  • All Implemented Interfaces:
    java.io.Serializable, java.time.temporal.TemporalAmount

    public final class Frequency
    extends java.lang.Object
    implements java.time.temporal.TemporalAmount, java.io.Serializable
    A periodic frequency used by financial products that have a specific event every so often.

    Frequency is primarily intended to be used to subdivide events within a year.

    A frequency is allowed to be any non-negative period of days, weeks, month or years. This class provides constants for common frequencies which are best used by static import.

    A special value, 'Term', is provided for when there are no subdivisions of the entire term. This is also know as 'zero-coupon' or 'once'. It is represented using the period 10,000 years, which allows addition/subtraction to work, producing a date after the end of the term.

    Each frequency is based on a Period. The months and years of the period are not normalized, thus it is possible to have a frequency of 12 months and a different one of 1 year. When used, standard date addition rules apply, thus there is no difference between them. Call normalized() to apply normalization.

    The periodic frequency is often expressed as a number of events per year. The eventsPerYear() method can be used to obtain this for common frequencies.

    Usage

    Frequency implements TemporalAmount allowing it to be directly added to a date:
      LocalDate later = baseDate.plus(frequency);
     
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static Frequency P12M
      A periodic frequency of 12 months (1 year).
      static Frequency P13W
      A periodic frequency of 13 weeks (91 days).
      static Frequency P1D
      A periodic frequency of one day.
      static Frequency P1M
      A periodic frequency of 1 month.
      static Frequency P1W
      A periodic frequency of 1 week (7 days).
      static Frequency P26W
      A periodic frequency of 26 weeks (182 days).
      static Frequency P2M
      A periodic frequency of 2 months.
      static Frequency P2W
      A periodic frequency of 2 weeks (14 days).
      static Frequency P3M
      A periodic frequency of 3 months.
      static Frequency P4M
      A periodic frequency of 4 months.
      static Frequency P4W
      A periodic frequency of 4 weeks (28 days).
      static Frequency P52W
      A periodic frequency of 52 weeks (364 days).
      static Frequency P6M
      A periodic frequency of 6 months.
      static Frequency TERM
      A periodic frequency matching the term.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.time.temporal.Temporal addTo​(java.time.temporal.Temporal temporal)
      Adds the period of this frequency to the specified date.
      boolean equals​(java.lang.Object obj)
      Checks if this periodic frequency equals another periodic frequency.
      int eventsPerYear()
      Calculates the number of events that occur in a year.
      double eventsPerYearEstimate()
      Estimates the number of events that occur in a year.
      int exactDivide​(Frequency other)
      Exactly divides this frequency by another.
      long get​(java.time.temporal.TemporalUnit unit)
      Gets the value of the specified unit.
      java.time.Period getPeriod()
      Gets the underlying period of the frequency.
      java.util.List<java.time.temporal.TemporalUnit> getUnits()
      Gets the unit of this periodic frequency.
      int hashCode()
      Returns a suitable hash code for the periodic frequency.
      boolean isAnnual()
      Checks if the periodic frequency is annual.
      boolean isMonthBased()
      Checks if the periodic frequency is month-based.
      boolean isTerm()
      Checks if the periodic frequency is the 'Term' instance.
      boolean isWeekBased()
      Checks if the periodic frequency is week-based.
      Frequency normalized()
      Normalizes the months and years of this tenor.
      static Frequency of​(java.time.Period period)
      Obtains an instance from a Period.
      static Frequency ofDays​(int days)
      Obtains an instance backed by a period of days.
      static Frequency ofMonths​(int months)
      Obtains an instance backed by a period of months.
      static Frequency ofWeeks​(int weeks)
      Obtains an instance backed by a period of weeks.
      static Frequency ofYears​(int years)
      Obtains an instance backed by a period of years.
      static Frequency parse​(java.lang.String toParse)
      Parses a formatted string representing the frequency.
      java.time.temporal.Temporal subtractFrom​(java.time.temporal.Temporal temporal)
      Subtracts the period of this frequency from the specified date.
      java.lang.String toString()
      Returns a formatted string representing the periodic frequency.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • P1D

        public static final Frequency P1D
        A periodic frequency of one day. Also known as daily. There are considered to be 364 events per year with this frequency.
      • P1W

        public static final Frequency P1W
        A periodic frequency of 1 week (7 days). Also known as weekly. There are considered to be 52 events per year with this frequency.
      • P2W

        public static final Frequency P2W
        A periodic frequency of 2 weeks (14 days). Also known as bi-weekly. There are considered to be 26 events per year with this frequency.
      • P4W

        public static final Frequency P4W
        A periodic frequency of 4 weeks (28 days). Also known as lunar. There are considered to be 13 events per year with this frequency.
      • P13W

        public static final Frequency P13W
        A periodic frequency of 13 weeks (91 days). There are considered to be 4 events per year with this frequency.
      • P26W

        public static final Frequency P26W
        A periodic frequency of 26 weeks (182 days). There are considered to be 2 events per year with this frequency.
      • P52W

        public static final Frequency P52W
        A periodic frequency of 52 weeks (364 days). There is considered to be 1 event per year with this frequency.
      • P1M

        public static final Frequency P1M
        A periodic frequency of 1 month. Also known as monthly. There are 12 events per year with this frequency.
      • P2M

        public static final Frequency P2M
        A periodic frequency of 2 months. Also known as bi-monthly. There are 6 events per year with this frequency.
      • P3M

        public static final Frequency P3M
        A periodic frequency of 3 months. Also known as quarterly. There are 4 events per year with this frequency.
      • P4M

        public static final Frequency P4M
        A periodic frequency of 4 months. There are 3 events per year with this frequency.
      • P6M

        public static final Frequency P6M
        A periodic frequency of 6 months. Also known as semi-annual. There are 2 events per year with this frequency.
      • P12M

        public static final Frequency P12M
        A periodic frequency of 12 months (1 year). Also known as annual. There is 1 event per year with this frequency.
      • TERM

        public static final Frequency TERM
        A periodic frequency matching the term. Also known as zero-coupon. This is represented using the period 10,000 years. There are no events per year with this frequency.
    • Method Detail

      • of

        public static Frequency of​(java.time.Period period)
        Obtains an instance from a Period.

        The period normally consists of either days and weeks, or months and years. It must also be positive and non-zero.

        If the number of days is an exact multiple of 7 it will be converted to weeks. Months are not normalized into years.

        The maximum tenor length is 1,000 years.

        Parameters:
        period - the period to convert to a periodic frequency
        Returns:
        the periodic frequency
        Throws:
        java.lang.IllegalArgumentException - if the period is negative, zero or too large
      • ofDays

        public static Frequency ofDays​(int days)
        Obtains an instance backed by a period of days.

        If the number of days is an exact multiple of 7 it will be converted to weeks.

        Parameters:
        days - the number of days
        Returns:
        the periodic frequency
        Throws:
        java.lang.IllegalArgumentException - if days is negative or zero
      • ofWeeks

        public static Frequency ofWeeks​(int weeks)
        Obtains an instance backed by a period of weeks.
        Parameters:
        weeks - the number of weeks
        Returns:
        the periodic frequency
        Throws:
        java.lang.IllegalArgumentException - if weeks is negative or zero
      • ofMonths

        public static Frequency ofMonths​(int months)
        Obtains an instance backed by a period of months.

        Months are not normalized into years.

        Parameters:
        months - the number of months
        Returns:
        the periodic frequency
        Throws:
        java.lang.IllegalArgumentException - if months is negative, zero or over 12,000
      • ofYears

        public static Frequency ofYears​(int years)
        Obtains an instance backed by a period of years.
        Parameters:
        years - the number of years
        Returns:
        the periodic frequency
        Throws:
        java.lang.IllegalArgumentException - if years is negative, zero or over 1,000
      • parse

        public static Frequency parse​(java.lang.String toParse)
        Parses a formatted string representing the frequency.

        The format can either be based on ISO-8601, such as 'P3M' or without the 'P' prefix e.g. '2W'.

        The period must be positive and non-zero.

        Parameters:
        toParse - the string representing the frequency
        Returns:
        the frequency
        Throws:
        java.lang.IllegalArgumentException - if the frequency cannot be parsed
      • getPeriod

        public java.time.Period getPeriod()
        Gets the underlying period of the frequency.
        Returns:
        the period
      • isTerm

        public boolean isTerm()
        Checks if the periodic frequency is the 'Term' instance.

        The term instance corresponds to there being no subdivisions of the entire term.

        Returns:
        true if this is the 'Term' instance
      • normalized

        public Frequency normalized()
        Normalizes the months and years of this tenor.

        This method returns a tenor of an equivalent length but with any number of months greater than 12 normalized into a combination of months and years.

        Returns:
        the normalized tenor
      • isWeekBased

        public boolean isWeekBased()
        Checks if the periodic frequency is week-based.

        A week-based frequency consists of an integral number of weeks. There must be no day, month or year element.

        Returns:
        true if this is week-based
      • isMonthBased

        public boolean isMonthBased()
        Checks if the periodic frequency is month-based.

        A month-based frequency consists of an integral number of months. Any year-based frequency is also counted as month-based. There must be no day or week element.

        Returns:
        true if this is month-based
      • isAnnual

        public boolean isAnnual()
        Checks if the periodic frequency is annual.

        An annual frequency consists of 12 months. There must be no day or week element.

        Returns:
        true if this is annual
      • eventsPerYear

        public int eventsPerYear()
        Calculates the number of events that occur in a year.

        The number of events per year is the number of times that the period occurs per year. Not all periodic frequency instances can be converted to an integer events per year. All constants declared on this class will return a result.

        Month-based and year-based periodic frequencies are converted by dividing 12 by the number of months. Only the following periodic frequencies return a value - P1M, P2M, P3M, P4M, P6M, P1Y.

        Day-based and week-based periodic frequencies are converted by dividing 364 by the number of days. Only the following periodic frequencies return a value - P1D, P2D, P4D, P1W, P2W, P4W, P13W, P26W, P52W.

        The 'Term' periodic frequency returns zero.

        Returns:
        the number of events per year
        Throws:
        java.lang.IllegalArgumentException - if unable to calculate the number of events per year
      • eventsPerYearEstimate

        public double eventsPerYearEstimate()
        Estimates the number of events that occur in a year.

        The number of events per year is the number of times that the period occurs per year. This method returns an estimate without throwing an exception. The exact number of events is returned by eventsPerYear().

        The 'Term' periodic frequency returns zero. Month-based and year-based periodic frequencies return 12 divided by the number of months. Day-based and week-based periodic frequencies return 364 divided by the number of days. Other frequencies are calculated using estimated durations, dividing the year by the period.

        Returns:
        the estimated number of events per year
      • exactDivide

        public int exactDivide​(Frequency other)
        Exactly divides this frequency by another.

        This calculates the integer division of this frequency by the specified frequency. If the result is not an integer, an exception is thrown.

        Month-based and year-based periodic frequencies are calculated by dividing the total number of months. For example, P6M divided by P3M results in 2, and P2Y divided by P6M returns 4.

        Day-based and week-based periodic frequencies are calculated by dividing the total number of days. For example, P26W divided by P13W results in 2, and P2W divided by P1D returns 14.

        The 'Term' frequency throws an exception.

        Parameters:
        other - the other frequency to divide into this one
        Returns:
        this frequency divided by the other frequency
        Throws:
        java.lang.IllegalArgumentException - if the frequency does not exactly divide into this one
      • get

        public long get​(java.time.temporal.TemporalUnit unit)
        Gets the value of the specified unit.

        This will return a value for the years, months and days units. Note that weeks are not included. All other units throw an exception.

        The 'Term' period is returned as a period of 10,000 years.

        This method implements TemporalAmount. It is not intended to be called directly.

        Specified by:
        get in interface java.time.temporal.TemporalAmount
        Parameters:
        unit - the unit to query
        Returns:
        the value of the unit
        Throws:
        java.time.temporal.UnsupportedTemporalTypeException - if the unit is not supported
      • getUnits

        public java.util.List<java.time.temporal.TemporalUnit> getUnits()
        Gets the unit of this periodic frequency.

        This returns a list containing years, months and days. Note that weeks are not included.

        The 'Term' period is returned as a period of 10,000 years.

        This method implements TemporalAmount. It is not intended to be called directly.

        Specified by:
        getUnits in interface java.time.temporal.TemporalAmount
        Returns:
        a list containing the years, months and days units
      • addTo

        public java.time.temporal.Temporal addTo​(java.time.temporal.Temporal temporal)
        Adds the period of this frequency to the specified date.

        This method implements TemporalAmount. It is not intended to be called directly. Use LocalDate.plus(TemporalAmount) instead.

        Specified by:
        addTo in interface java.time.temporal.TemporalAmount
        Parameters:
        temporal - the temporal object to add to
        Returns:
        the result with this frequency added
        Throws:
        java.time.DateTimeException - if unable to add
        java.lang.ArithmeticException - if numeric overflow occurs
      • subtractFrom

        public java.time.temporal.Temporal subtractFrom​(java.time.temporal.Temporal temporal)
        Subtracts the period of this frequency from the specified date.

        This method implements TemporalAmount. It is not intended to be called directly. Use LocalDate.minus(TemporalAmount) instead.

        Specified by:
        subtractFrom in interface java.time.temporal.TemporalAmount
        Parameters:
        temporal - the temporal object to subtract from
        Returns:
        the result with this frequency subtracted
        Throws:
        java.time.DateTimeException - if unable to subtract
        java.lang.ArithmeticException - if numeric overflow occurs
      • equals

        public boolean equals​(java.lang.Object obj)
        Checks if this periodic frequency equals another periodic frequency.

        The comparison checks the frequency period.

        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - the other frequency, null returns false
        Returns:
        true if equal
      • hashCode

        public int hashCode()
        Returns a suitable hash code for the periodic frequency.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hash code
      • toString

        public java.lang.String toString()
        Returns a formatted string representing the periodic frequency.

        The format is a combination of the quantity and unit, such as P1D, P2W, P3M, P4Y. The 'Term' amount is returned as 'Term'.

        Overrides:
        toString in class java.lang.Object
        Returns:
        the formatted frequency