java.lang.Object
org.rrd4j.core.timespec.TimeSpec
public class TimeSpecextends Object
Represents time specifications parsed from at-style date strings.

This class stores the result of parsing time specifications in the format used by RRDTool and described in detail on the rrdfetch man page. It supports both absolute timestamps and relative time adjustments.

Time specification types:
- Absolute time: Specific date and time (e.g., "Jan 1 2023 12:00")
- Relative time: Offsets from reference time (e.g., "now-2hours")
- Start/End markers: Relative to another time spec (e.g., "start+1day")

Common usage patterns:

// Absolute time examples
TimeParser p1 = new TimeParser("Jan 1 2023");
TimeParser p2 = new TimeParser("12:30");
TimeParser p3 = new TimeParser("2023/01/01 12:30:45");

// Relative time examples
TimeParser p4 = new TimeParser("now-1day");      // Yesterday
TimeParser p5 = new TimeParser("now+2hours30min"); // 2.5 hours from now
TimeParser p6 = new TimeParser("tomorrow");       // Tomorrow at midnight
TimeParser p7 = new TimeParser("noon");           // Today at 12:00

// Range examples
TimeParser p8 = new TimeParser("start");           // Start of range
TimeParser p9 = new TimeParser("end+1week");      // End of range + 1 week

See TimeParser for complete syntax reference and parsing details.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) TimeSpec
    context
    Absolute spec this one resolves against, wired up by getTimes(TimeSpec, TimeSpec).
    (package private) final String
    dateString
    The at-style text this spec was parsed from, echoed in resolution error messages.
    (package private) int
    day
    Broken-down date and wall-clock time of the instant this spec resolves to, following GregorianCalendar conventions: month counts from 0 for January, and sec holds whole seconds with no sub-second part.
    (package private) int
    dday
    Offset from the context's instant, in the same units as the components above: dmonth is a whole number of months, the rest whole years, days, hours, minutes and seconds.
    (package private) int
    dhour
    Offset from the context's instant, in the same units as the components above: dmonth is a whole number of months, the rest whole years, days, hours, minutes and seconds.
    (package private) int
    dmin
    Offset from the context's instant, in the same units as the components above: dmonth is a whole number of months, the rest whole years, days, hours, minutes and seconds.
    (package private) int
    dmonth
    Offset from the context's instant, in the same units as the components above: dmonth is a whole number of months, the rest whole years, days, hours, minutes and seconds.
    (package private) int
    dsec
    Offset from the context's instant, in the same units as the components above: dmonth is a whole number of months, the rest whole years, days, hours, minutes and seconds.
    (package private) int
    dyear
    Offset from the context's instant, in the same units as the components above: dmonth is a whole number of months, the rest whole years, days, hours, minutes and seconds.
    (package private) int
    hour
    Broken-down date and wall-clock time of the instant this spec resolves to, following GregorianCalendar conventions: month counts from 0 for January, and sec holds whole seconds with no sub-second part.
    (package private) int
    min
    Broken-down date and wall-clock time of the instant this spec resolves to, following GregorianCalendar conventions: month counts from 0 for January, and sec holds whole seconds with no sub-second part.
    (package private) int
    month
    Broken-down date and wall-clock time of the instant this spec resolves to, following GregorianCalendar conventions: month counts from 0 for January, and sec holds whole seconds with no sub-second part.
    (package private) int
    sec
    Broken-down date and wall-clock time of the instant this spec resolves to, following GregorianCalendar conventions: month counts from 0 for January, and sec holds whole seconds with no sub-second part.
    (package private) int
    type
    Which of the three forms above this spec takes; an absolute date/time unless a parser says otherwise.
    (package private) static final int
    TYPE_ABSOLUTE
    Time specification represents an absolute date/time.
    (package private) static final int
    TYPE_END
    Time specification is relative to the end of the time range.
    (package private) static final int
    TYPE_START
    Time specification is relative to the start of the time range.
    (package private) int
    wday
    Day of week, 0 for Sunday through 6 for Saturday, used to resolve weekday names.
    (package private) int
    year
    Broken-down date and wall-clock time of the instant this spec resolves to, following GregorianCalendar conventions: month counts from 0 for January, and sec holds whole seconds with no sub-second part.

  • Constructor Summary

    Constructors
    Constructor
    Description
    TimeSpec(String dateString)
    Creates an empty spec bound to the text it will be parsed from; TimeParser fills in the time components afterwards.

  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) String
    dump()
    Returns a debug string representation of this TimeSpec.
    (package private) GregorianCalendar
    getTime()
    Resolves this spec against its context, applying the relative offsets.
    static Calendar[]
    getTimes(TimeSpec spec1, TimeSpec spec2)
    Use this static method to resolve relative time references and obtain the corresponding Calendar objects.
    long
    getTimestamp()
    Returns the corresponding timestamp (seconds since Epoch).
    static long[]
    getTimestamps(TimeSpec spec1, TimeSpec spec2)
    Use this static method to resolve relative time references and obtain the corresponding timestamps (seconds since epoch).
    (package private) void
    localtime(long timestamp)
    Initializes this TimeSpec with local time components from a timestamp.

    Methods inherited from class Object

    clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • TYPE_ABSOLUTE

      static final int TYPE_ABSOLUTE
      Time specification represents an absolute date/time.
      See Also:

    • TYPE_START

      static final int TYPE_START
      Time specification is relative to the start of the time range.
      See Also:

    • TYPE_END

      static final int TYPE_END
      Time specification is relative to the end of the time range.
      See Also:

    • type

      int type
      Which of the three forms above this spec takes; an absolute date/time unless a parser says otherwise.

    • year

      int year
      Broken-down date and wall-clock time of the instant this spec resolves to, following GregorianCalendar conventions: month counts from 0 for January, and sec holds whole seconds with no sub-second part.

    • month

      int month
      Broken-down date and wall-clock time of the instant this spec resolves to, following GregorianCalendar conventions: month counts from 0 for January, and sec holds whole seconds with no sub-second part.

    • day

      int day
      Broken-down date and wall-clock time of the instant this spec resolves to, following GregorianCalendar conventions: month counts from 0 for January, and sec holds whole seconds with no sub-second part.

    • hour

      int hour
      Broken-down date and wall-clock time of the instant this spec resolves to, following GregorianCalendar conventions: month counts from 0 for January, and sec holds whole seconds with no sub-second part.

    • min

      int min
      Broken-down date and wall-clock time of the instant this spec resolves to, following GregorianCalendar conventions: month counts from 0 for January, and sec holds whole seconds with no sub-second part.

    • sec

      int sec
      Broken-down date and wall-clock time of the instant this spec resolves to, following GregorianCalendar conventions: month counts from 0 for January, and sec holds whole seconds with no sub-second part.

    • wday

      int wday
      Day of week, 0 for Sunday through 6 for Saturday, used to resolve weekday names.

    • dyear

      int dyear
      Offset from the context's instant, in the same units as the components above: dmonth is a whole number of months, the rest whole years, days, hours, minutes and seconds.

    • dmonth

      int dmonth
      Offset from the context's instant, in the same units as the components above: dmonth is a whole number of months, the rest whole years, days, hours, minutes and seconds.

    • dday

      int dday
      Offset from the context's instant, in the same units as the components above: dmonth is a whole number of months, the rest whole years, days, hours, minutes and seconds.

    • dhour

      int dhour
      Offset from the context's instant, in the same units as the components above: dmonth is a whole number of months, the rest whole years, days, hours, minutes and seconds.

    • dmin

      int dmin
      Offset from the context's instant, in the same units as the components above: dmonth is a whole number of months, the rest whole years, days, hours, minutes and seconds.

    • dsec

      int dsec
      Offset from the context's instant, in the same units as the components above: dmonth is a whole number of months, the rest whole years, days, hours, minutes and seconds.

    • dateString

      final String dateString
      The at-style text this spec was parsed from, echoed in resolution error messages.

    • context

      TimeSpec context
      Absolute spec this one resolves against, wired up by getTimes(TimeSpec, TimeSpec).

  • Constructor Details

    • TimeSpec

      TimeSpec(String dateString)
      Creates an empty spec bound to the text it will be parsed from; TimeParser fills in the time components afterwards.
      Parameters:
      dateString - at-style time specification, echoed in resolution error messages

  • Method Details

    • localtime

      void localtime(long timestamp)
      Initializes this TimeSpec with local time components from a timestamp.

      This helper method converts a Unix timestamp (seconds since epoch) into individual time components (year, month, day, hour, minute, second) and day of week. This is used to establish a baseline time for relative time calculations.

      Parameters:
      timestamp - Unix timestamp in seconds since epoch

    • getTime

      GregorianCalendar getTime()
      Resolves this spec against its context, applying the relative offsets.
      Returns:
      the resolved instant, with the offsets applied
      Throws:
      IllegalStateException - if a relative spec has no absolute context to resolve against

    • getTimestamp

      public long getTimestamp()
      Returns the corresponding timestamp (seconds since Epoch). Example:
      TimeParser p = new TimeParser("now-1day");
TimeSpec ts = p.parse();
System.out.println("Timestamp was: " + ts.getTimestamp();
      Returns:
      Timestamp (in seconds, no milliseconds)

    • dump

      String dump()
      Returns a debug string representation of this TimeSpec.

      This method formats the TimeSpec for debugging purposes, showing both the absolute time components and the relative delta components in a compact format.

      Returns:
      debug string showing type and all time components

    • getTimes

      public static Calendar[] getTimes(TimeSpec spec1, TimeSpec spec2)
      Use this static method to resolve relative time references and obtain the corresponding Calendar objects. Example:
      TimeParser pStart = new TimeParser("now-1month"); // starting time
TimeParser pEnd = new TimeParser("start+1week");  // ending time
TimeSpec specStart = pStart.parse();
TimeSpec specEnd = pEnd.parse();
GregorianCalendar[] gc = TimeSpec.getTimes(specStart, specEnd);
      Parameters:
      spec1 - Starting time specification
      spec2 - Ending time specification
      Returns:
      Two element array containing Calendar objects

    • getTimestamps

      public static long[] getTimestamps(TimeSpec spec1, TimeSpec spec2)
      Use this static method to resolve relative time references and obtain the corresponding timestamps (seconds since epoch). Example:
      TimeParser pStart = new TimeParser("now-1month"); // starting time
TimeParser pEnd = new TimeParser("start+1week");  // ending time
TimeSpec specStart = pStart.parse();
TimeSpec specEnd = pEnd.parse();
long[] ts = TimeSpec.getTimestamps(specStart, specEnd);
      Parameters:
      spec1 - Starting time specification
      spec2 - Ending time specification
      Returns:
      array containing two timestamps (in seconds since epoch)