org.rrd4j.core.timespec

Class TimeSpec

java.lang.Object

org.rrd4j.core.timespec.TimeSpec

public class TimeSpec
extends 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 and Description
(package private) TimeSpec	context
(package private) String	dateString
(package private) int	day
(package private) int	dday
(package private) int	dhour
(package private) int	dmin
(package private) int	dmonth
(package private) int	dsec
(package private) int	dyear
(package private) int	hour
(package private) int	min
(package private) int	month
(package private) int	sec
(package private) int	type
(package private) static int	TYPE_ABSOLUTE
(package private) static int	TYPE_END
(package private) static int	TYPE_START
(package private) int	wday
(package private) int	year

Constructor Summary

Constructors

Constructor and Description
TimeSpec(String dateString)

Method Summary

Modifier and Type	Method and Description
(package private) String	dump() Returns a debug string representation of this TimeSpec.
(package private) GregorianCalendar	getTime()
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 java.lang.Object

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

Field Detail

context

TimeSpec context

dateString

final String dateString

day

int day

dday

int dday

dhour

int dhour

dmin

int dmin

dmonth

int dmonth

dsec

int dsec

dyear

int dyear

hour

int hour

min

int min

month

int month

sec

int sec

type

int type

TYPE_ABSOLUTE

static final int TYPE_ABSOLUTE

See Also:

Constant Field Values

TYPE_END

static final int TYPE_END

See Also:

Constant Field Values

TYPE_START

static final int TYPE_START

See Also:

Constant Field Values

wday

int wday

year

int year

Constructor Detail

TimeSpec

TimeSpec(String dateString)

Method Detail

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

getTime

GregorianCalendar getTime()

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

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)

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)

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