org.jfree.data.time

## Class RegularTimePeriod

- java.lang.Object
- - org.jfree.data.time.RegularTimePeriod

- All Implemented Interfaces:
    java.lang.Comparable, TimePeriod, MonthConstants
  Direct Known Subclasses:
    Day, Hour, Millisecond, Minute, Month, Quarter, Second, 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.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.util.TimeZone` | `DEFAULT_TIME_ZONE` Deprecated. As of 1.0.11, we discourage the use of this field - use `TimeZone.getDefault()` instead.
    `static java.util.Calendar` | `WORKING_CALENDAR` Deprecated. This was a bad idea, don't use it!

    - ### Fields inherited from interface org.jfree.date.MonthConstants

      `APRIL, AUGUST, DECEMBER, FEBRUARY, JANUARY, JULY, JUNE, MARCH, MAY, NOVEMBER, OCTOBER, SEPTEMBER`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RegularTimePeriod()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static RegularTimePeriod` | `createInstance(java.lang.Class c, java.util.Date millisecond, java.util.TimeZone zone)` 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.
    `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).
    `long` | `getFirstMillisecond(java.util.TimeZone zone)` Deprecated. As of 1.0.3, you should avoid using this method (it creates a new Calendar instance every time it is called). You are advised to call `getFirstMillisecond(Calendar)` instead.
    `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` | `getLastMillisecond(java.util.TimeZone zone)` Deprecated. As of 1.0.3, you should avoid using this method (it creates a new Calendar instance every time it is called). You are advised to call `getLastMillisecond(Calendar)` instead.
    `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` | `getMiddleMillisecond(java.util.TimeZone zone)` Deprecated. As of 1.0.3, you should avoid using this method (it creates a new Calendar instance every time it is called). You are advised to call `getMiddleMillisecond(Calendar)` instead.
    `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.
    `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

    - #### DEFAULT_TIME_ZONE

          public static final java.util.TimeZone DEFAULT_TIME_ZONE

      Deprecated. As of 1.0.11, we discourage the use of this field - use `TimeZone.getDefault()` instead.
      The default time zone.

    - #### WORKING_CALENDAR

          public static final java.util.Calendar WORKING_CALENDAR

      Deprecated. This was a bad idea, don't use it!
      A working calendar (recycle to avoid unnecessary object creation).

  - ### Constructor Detail

    - #### RegularTimePeriod

          public RegularTimePeriod()

  - ### Method Detail

    - #### createInstance

          public static RegularTimePeriod createInstance(java.lang.Class c,
                                                         java.util.Date millisecond,
                                                         java.util.TimeZone zone)

      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.
      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.

    - #### 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).
      Since:
        1.0.3

    - #### 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 long getFirstMillisecond(java.util.TimeZone zone)

      Deprecated. As of 1.0.3, you should avoid using this method (it creates a new Calendar instance every time it is called). You are advised to call `getFirstMillisecond(Calendar)` instead.
      Returns the first millisecond of the time period, evaluated within a specific time zone.
      Parameters:
        `zone` - the time zone (`null` not permitted).
      Returns:
        The first millisecond of the time period.
      See Also:
        `getLastMillisecond(TimeZone)`

    - #### 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 long getLastMillisecond(java.util.TimeZone zone)

      Deprecated. As of 1.0.3, you should avoid using this method (it creates a new Calendar instance every time it is called). You are advised to call `getLastMillisecond(Calendar)` instead.
      Returns the last millisecond of the time period, evaluated within a specific time zone.
      Parameters:
        `zone` - the time zone (`null` not permitted).
      Returns:
        The last millisecond of the time period.
      See Also:
        `getFirstMillisecond(TimeZone)`

    - #### 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.TimeZone zone)

      Deprecated. As of 1.0.3, you should avoid using this method (it creates a new Calendar instance every time it is called). You are advised to call `getMiddleMillisecond(Calendar)` instead.
      Returns the millisecond closest to the middle of the time period, evaluated within a specific time zone.
      Parameters:
        `zone` - the time zone (`null` not permitted).
      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.
      Since:
        1.0.18

    - #### toString

          public java.lang.String toString()

      Returns a string representation of the time period.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        The string.