Class RegularTimePeriod

  • All Implemented Interfaces:
    java.lang.Comparable, MonthConstants, TimePeriod
    Direct Known Subclasses:
    Day, FixedMillisecond, Hour, Millisecond, Minute, Month, Quarter, Second, Week, Year

    public abstract class RegularTimePeriod
    extends java.lang.Object
    implements TimePeriod, java.lang.Comparable, MonthConstants
    An abstract class representing a unit of time. Convenient methods are provided for calculating the next and previous time periods. Conversion methods are defined that return the first and last milliseconds of the time period. The results from these methods are timezone dependent.

    This class is immutable, and all subclasses should be immutable also.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      static RegularTimePeriod createInstance​(java.lang.Class c, java.util.Date millisecond, java.util.TimeZone zone, java.util.Locale locale)
      Creates a time period that includes the specified millisecond, assuming the given time zone.
      static java.lang.Class downsize​(java.lang.Class c)
      Returns a subclass of RegularTimePeriod that is smaller than the specified class.
      protected static java.util.Calendar getCalendarInstance()
      Creates or returns a thread-local Calendar instance.
      java.util.Date getEnd()
      Returns the date/time that marks the end of the time period.
      abstract long getFirstMillisecond()
      Returns the first millisecond of the time period.
      abstract long getFirstMillisecond​(java.util.Calendar calendar)
      Returns the first millisecond of the time period, evaluated using the supplied calendar (which incorporates a timezone).
      abstract long getLastMillisecond()
      Returns the last millisecond of the time period.
      abstract long getLastMillisecond​(java.util.Calendar calendar)
      Returns the last millisecond of the time period, evaluated using the supplied calendar (which incorporates a timezone).
      long getMiddleMillisecond()
      Returns the millisecond closest to the middle of the time period.
      long getMiddleMillisecond​(java.util.Calendar calendar)
      Returns the millisecond closest to the middle of the time period, evaluated using the supplied calendar (which incorporates a timezone).
      long getMillisecond​(TimePeriodAnchor anchor, java.util.Calendar calendar)
      Returns the millisecond (relative to the epoch) corresponding to the specified anchor using the supplied calendar (which incorporates a time zone).
      abstract long getSerialIndex()
      Returns a serial index number for the time unit.
      java.util.Date getStart()
      Returns the date/time that marks the start of the time period.
      abstract RegularTimePeriod next()
      Returns the time period following this one, or null if some limit has been reached.
      abstract void peg​(java.util.Calendar calendar)
      Recalculates the start date/time and end date/time for this time period relative to the supplied calendar (which incorporates a time zone).
      abstract RegularTimePeriod previous()
      Returns the time period preceding this one, or null if some lower limit has been reached.
      static void setCalendarInstancePrototype​(java.util.Calendar calendar)
      Sets a global calendar prototype for time calculations.
      static void setThreadLocalCalendarInstance​(java.util.Calendar calendar)
      Sets the thread-local calendar instance for time calculations.
      java.lang.String toString()
      Returns a string representation of the time period.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.lang.Comparable

        compareTo
    • Field Detail

      • calendarPrototype

        private static final java.util.concurrent.atomic.AtomicReference<java.util.Calendar> calendarPrototype
      • threadLocalCalendar

        private static final java.lang.ThreadLocal<java.util.Calendar> threadLocalCalendar
    • Constructor Detail

      • RegularTimePeriod

        public RegularTimePeriod()
    • Method Detail

      • createInstance

        public static RegularTimePeriod createInstance​(java.lang.Class c,
                                                       java.util.Date millisecond,
                                                       java.util.TimeZone zone,
                                                       java.util.Locale locale)
        Creates a time period that includes the specified millisecond, assuming the given time zone.
        Parameters:
        c - the time period class.
        millisecond - the time.
        zone - the time zone.
        locale - the locale.
        Returns:
        The time period.
      • downsize

        public static java.lang.Class downsize​(java.lang.Class c)
        Returns a subclass of RegularTimePeriod that is smaller than the specified class.
        Parameters:
        c - a subclass of RegularTimePeriod.
        Returns:
        A class.
      • getCalendarInstance

        protected static java.util.Calendar getCalendarInstance()
        Creates or returns a thread-local Calendar instance. This function is used by the various subclasses to obtain a calendar for date-time to/from ms-since-epoch conversions (and to determine the first day of the week, in case of Week).

        If a thread-local calendar was set with setThreadLocalCalendarInstance(Calendar), then it is simply returned.

        Otherwise, If a global calendar prototype was set with setCalendarInstancePrototype(Calendar), then it is cloned and set as the thread-local calendar instance for future use, as if it was set with setThreadLocalCalendarInstance(Calendar).

        Otherwise, if neither is set, a new instance will be created every time with Calendar.getInstance(), resorting to JFreeChart 1.5.0 behavior (leading to huge load on GC and high memory consumption if many instances are created).

        Returns:
        a thread-local Calendar instance
      • setThreadLocalCalendarInstance

        public static void setThreadLocalCalendarInstance​(java.util.Calendar calendar)
        Sets the thread-local calendar instance for time calculations.

        RegularTimePeriod instances sometimes need a Calendar to perform time calculations (date-time from/to milliseconds-since-epoch). In JFreeChart 1.5.0, they created a new Calendar instance every time they needed one. This created a huge load on GC and lead to high memory consumption. To avoid this, a thread-local Calendar instance can be set, which will then be used for time calculations every time, unless the caller passes a specific Calendar instance in places where the API allows it.

        If the specified calendar is null, or if this method was never called, then the next time a calendar instance is needed, a new one will be created by cloning the global prototype set with setCalendarInstancePrototype(Calendar). If none was set either, then a new instance will be created every time with Calendar.getInstance(), resorting to JFreeChart 1.5.0 behavior.

        Parameters:
        calendar - the new thread-local calendar instance
      • setCalendarInstancePrototype

        public static void setCalendarInstancePrototype​(java.util.Calendar calendar)
        Sets a global calendar prototype for time calculations.

        RegularTimePeriod instances sometimes need a Calendar to perform time calculations (date-time from/to milliseconds-since-epoch). In JFreeChart 1.5.0, they created a new Calendar instance every time they needed one. This created a huge load on GC and lead to high memory consumption. To avoid this, a prototype Calendar can be set, which will be then cloned by every thread that needs a Calendar instance. The prototype is not cloned right away, and stored instead for later cloning, therefore the caller must not alter the prototype after it has been passed to this method.

        If the prototype is null, then thread-local calendars set with setThreadLocalCalendarInstance(Calendar) will be used instead. If none was set for some thread, then a new instance will be created with Calendar.getInstance() every time one is needed. However, if the prototype was already cloned by some thread, then setting it to null has no effect, and that thread must explicitly set its own instance to null or something else to get rid of the cloned calendar.

        Calling setCalendarInstancePrototype(Calendar.getInstance()) somewhere early in an application will effectively mimic JFreeChart 1.5.0 behavior (using the default calendar everywhere unless explicitly specified), while preventing the many-allocations problem. There is one important caveat, however: once a prototype is cloned by some thread, calling TimeZone.setDefault(TimeZone) or Locale.setDefault(Locale)} will have no effect on future calculations. To avoid this problem, simply set the default time zone and locale before setting the prototype.

        Parameters:
        calendar - the new thread-local calendar instance
      • previous

        public abstract RegularTimePeriod previous()
        Returns the time period preceding this one, or null if some lower limit has been reached.
        Returns:
        The previous time period (possibly null).
      • next

        public abstract RegularTimePeriod next()
        Returns the time period following this one, or null if some limit has been reached.
        Returns:
        The next time period (possibly null).
      • getSerialIndex

        public abstract long getSerialIndex()
        Returns a serial index number for the time unit.
        Returns:
        The serial index number.
      • peg

        public abstract void peg​(java.util.Calendar calendar)
        Recalculates the start date/time and end date/time for this time period relative to the supplied calendar (which incorporates a time zone).
        Parameters:
        calendar - the calendar (null not permitted).
      • getStart

        public java.util.Date getStart()
        Returns the date/time that marks the start of the time period. This method returns a new Date instance every time it is called.
        Specified by:
        getStart in interface TimePeriod
        Returns:
        The start date/time.
        See Also:
        getFirstMillisecond()
      • getEnd

        public java.util.Date getEnd()
        Returns the date/time that marks the end of the time period. This method returns a new Date instance every time it is called.
        Specified by:
        getEnd in interface TimePeriod
        Returns:
        The end date/time.
        See Also:
        getLastMillisecond()
      • getFirstMillisecond

        public abstract long getFirstMillisecond()
        Returns the first millisecond of the time period. This will be determined relative to the time zone specified in the constructor, or in the calendar instance passed in the most recent call to the peg(Calendar) method.
        Returns:
        The first millisecond of the time period.
        See Also:
        getLastMillisecond()
      • getFirstMillisecond

        public abstract long getFirstMillisecond​(java.util.Calendar calendar)
        Returns the first millisecond of the time period, evaluated using the supplied calendar (which incorporates a timezone).
        Parameters:
        calendar - the calendar (null not permitted).
        Returns:
        The first millisecond of the time period.
        Throws:
        java.lang.NullPointerException - if calendar is null.
        See Also:
        getLastMillisecond(Calendar)
      • getLastMillisecond

        public abstract long getLastMillisecond()
        Returns the last millisecond of the time period. This will be determined relative to the time zone specified in the constructor, or in the calendar instance passed in the most recent call to the peg(Calendar) method.
        Returns:
        The last millisecond of the time period.
        See Also:
        getFirstMillisecond()
      • getLastMillisecond

        public abstract long getLastMillisecond​(java.util.Calendar calendar)
        Returns the last millisecond of the time period, evaluated using the supplied calendar (which incorporates a timezone).
        Parameters:
        calendar - the calendar (null not permitted).
        Returns:
        The last millisecond of the time period.
        See Also:
        getFirstMillisecond(Calendar)
      • getMiddleMillisecond

        public long getMiddleMillisecond()
        Returns the millisecond closest to the middle of the time period.
        Returns:
        The middle millisecond.
      • getMiddleMillisecond

        public long getMiddleMillisecond​(java.util.Calendar calendar)
        Returns the millisecond closest to the middle of the time period, evaluated using the supplied calendar (which incorporates a timezone).
        Parameters:
        calendar - the calendar.
        Returns:
        The middle millisecond.
      • getMillisecond

        public long getMillisecond​(TimePeriodAnchor anchor,
                                   java.util.Calendar calendar)
        Returns the millisecond (relative to the epoch) corresponding to the specified anchor using the supplied calendar (which incorporates a time zone).
        Parameters:
        anchor - the anchor (null not permitted).
        calendar - the calendar (null not permitted).
        Returns:
        Milliseconds since the epoch.
      • toString

        public java.lang.String toString()
        Returns a string representation of the time period.
        Overrides:
        toString in class java.lang.Object
        Returns:
        The string.