com.devexperts.util

Class TimePeriodInfo

java.lang.Object

com.devexperts.util.TimePeriodInfo

public final class TimePeriodInfo
extends Object

Immutable value object representing a time period range with min and max values (in milliseconds).

Serialized as JSON: {"min":1.5,"max":2} (seconds with decimals).

UNKNOWN (min < 0 && max < 0) means "not set / unknown" (no info available). Serializes as {"min":-1,"max":-1}.

EMPTY (min == 0 && max == 0) means "known to be zero" (e.g. zero duration / instant). Serializes as {"min":0,"max":0}.

Wire format for UNKNOWN

The wire sentinel for UNKNOWN is {"min":-1,"max":-1}. On parsing, any negative values in the JSON are treated as UNKNOWN (see valueOf(String)). Non-Java consumers that receive -1 seconds should interpret it as "no information available" rather than as a literal negative time period.

Field Summary

Fields

Modifier and Type	Field and Description
static TimePeriodInfo	EMPTY Sentinel value meaning "known to be zero".
static TimePeriodInfo	UNKNOWN Sentinel value meaning "not set / unknown".

Method Summary

Modifier and Type	Method and Description
TimePeriodInfo	add(long period) Convenience overload that aggregates a single-period value.
TimePeriodInfo	add(TimePeriodInfo other) Returns a new TimePeriodInfo that is the aggregate of this and the given info.
boolean	equals(Object o)
long	getMax() Returns the maximum period in milliseconds.
long	getMin() Returns the minimum period in milliseconds.
int	hashCode()
boolean	isUnknown() Returns true if this is the UNKNOWN sentinel value.
String	toString() Returns JSON format: {"min":1.5,"max":2.0} (seconds with decimals).
static TimePeriodInfo	valueOf(long min, long max) Returns a TimePeriodInfo for the given bounds, reusing the shared EMPTY sentinel for (0, 0).
static TimePeriodInfo	valueOf(String value) Parses from JSON format: {"min":1.5,"max":2.0} (seconds with decimals).

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

UNKNOWN

public static final TimePeriodInfo UNKNOWN

Sentinel value meaning "not set / unknown". Has negative min and max.

EMPTY

public static final TimePeriodInfo EMPTY

Sentinel value meaning "known to be zero". Has min == 0 and max == 0.

Method Detail

valueOf

public static TimePeriodInfo valueOf(long min,
                                     long max)

Returns a TimePeriodInfo for the given bounds, reusing the shared EMPTY sentinel for (0, 0).

Parameters:

min - minimum period in milliseconds (non-negative)

max - maximum period in milliseconds (non-negative, >= min)

Returns:

cached or newly allocated info

Throws:

IllegalArgumentException - if min or max is negative or min > max

valueOf

public static TimePeriodInfo valueOf(String value)

Parses from JSON format: {"min":1.5,"max":2.0} (seconds with decimals). Wire parsing is lenient: any malformed or semantically invalid input — null, empty, unparseable, negative bounds, or min > max — is mapped to UNKNOWN rather than thrown. This keeps the sentinel {"min":-1,"max":-1} round-tripping correctly and protects consumers from peer-side bugs in wire data.

Parameters:

value - JSON string to parse

Returns:

parsed info, or UNKNOWN if the string is null, empty, or invalid

getMin

public long getMin()

Returns the minimum period in milliseconds. For UNKNOWN, returns a negative sentinel value. Use isUnknown() to check before using this value arithmetically.

getMax

public long getMax()

Returns the maximum period in milliseconds. For UNKNOWN, returns a negative sentinel value. Use isUnknown() to check before using this value arithmetically.

isUnknown

public boolean isUnknown()

Returns true if this is the UNKNOWN sentinel value.

add

public TimePeriodInfo add(TimePeriodInfo other)

Returns a new TimePeriodInfo that is the aggregate of this and the given info. The result has the minimum of both mins and the maximum of both maxes. UNKNOWN is the identity element: UNKNOWN.add(x) returns x, x.add(UNKNOWN) returns x, UNKNOWN.add(UNKNOWN) returns UNKNOWN.

Parameters:

other - the info to aggregate with

Returns:

aggregated info

add

public TimePeriodInfo add(long period)

Convenience overload that aggregates a single-period value.

Parameters:

period - period in milliseconds (must be non-negative)

Returns:

aggregated info

Throws:

IllegalArgumentException - if the period is negative

toString

public String toString()

Returns JSON format: {"min":1.5,"max":2.0} (seconds with decimals). UNKNOWN serializes as {"min":-1,"max":-1} — any negative values on the wire are treated as UNKNOWN by valueOf(String). All instances return valid JSON.

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object