Class SqlInterval
Equality compares these fields exactly: one calendar day differs from 24 elapsed hours, and one month
differs from 30 days. Database interval equality can use different rules. This type has no natural ordering
and does not implement TemporalAmount: applying calendar fields to a zoned timestamp requires an
explicit application policy, which can differ from the database's daylight-saving resolution.
Binding and reading depend on the configured database's interval families, precision and range. Column qualifiers, rounding and other SQL coercions can change the stored fields.
Oracle and generic drivers need target-family metadata to bind ZERO, because the value does not
remember which factory created it. Computed values such as SqlInterval.of(Duration.between(a, a))
are also ZERO. Oracle exposes that metadata for direct assignment/comparison with an interval column
and supported explicit interval casts, such as CAST(:value AS INTERVAL DAY TO SECOND). Uncast
expressions, MERGE, PL/SQL blocks and INSERT ... SELECT can lack identifying metadata;
ZERO then fails even though nonzero values bind. A cast must select the schema's actual interval
family and is not a universal workaround; PL/SQL can still lack metadata. A CustomParameterBinder
that handles only ZERO and returns fallback() otherwise can choose the family explicitly.
- Since:
- 4.9.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final @NonNull SqlIntervalThe zero interval, without a YEAR-MONTH or DAY-SECOND family preference. -
Method Summary
Modifier and TypeMethodDescriptionbooleangetDays()Returns calendar days, independent of elapsed hours.Returns total calendar months, with years already folded in.getTime()Returns elapsed time, independent of calendar months and days.inthashCode()static @NonNull SqlIntervalCreates an interval without normalizing its three fields.static @NonNull SqlIntervalCreates an elapsed-only interval.static @NonNull SqlIntervalCreates a calendar-only interval, folding years into total months while retaining calendar days.static @NonNull SqlIntervalCreates an interval from calendar and elapsed components without combining days and hours.Returns the elapsed component only when there are no calendar components.toPeriod()Returns a normalized calendar period only when the elapsed component is zero.toString()Returns an ISO-style field representation with independent component signs, for exampleP14M-3DT4H5M6.789S.
-
Field Details
-
ZERO
The zero interval, without a YEAR-MONTH or DAY-SECOND family preference.
-
-
Method Details
-
of
Creates an elapsed-only interval.Duration.ofDays(1)remains 24 elapsed hours, not a calendar day.- Parameters:
time- elapsed time- Returns:
- an interval with no calendar components
-
of
Creates a calendar-only interval, folding years into total months while retaining calendar days. The period's year/month decomposition is not retained.- Parameters:
period- calendar period- Returns:
- a calendar interval
- Throws:
DateTimeException- if total months do not fit a signed 32-bit integer
-
of
Creates an interval from calendar and elapsed components without combining days and hours.- Parameters:
period- calendar period, with years folded into total monthstime- elapsed time- Returns:
- an interval retaining the independent components
- Throws:
DateTimeException- if total months do not fit a signed 32-bit integer
-
of
public static @NonNull SqlInterval of(@NonNull Integer months, @NonNull Integer days, @NonNull Duration time) Creates an interval without normalizing its three fields. Precision and database-specific range checks happen when binding; a value may retain nanoseconds even when a particular database supports only microseconds.- Parameters:
months- total calendar monthsdays- calendar daystime- elapsed time- Returns:
- an interval retaining all three fields
-
getMonths
-
getDays
-
getTime
-
toDuration
Returns the elapsed component only when there are no calendar components. Calendar days are deliberately not assumed to be 24 hours; useDuration.between(java.time.temporal.Temporal, java.time.temporal.Temporal)on original instant-compatible timestamps to calculate elapsed time.- Returns:
- elapsed time
- Throws:
DateTimeException- if months or days are nonzero
-
toPeriod
Returns a normalized calendar period only when the elapsed component is zero. Normalization splits total months into years and months, retaining the day component unchanged.- Returns:
- calendar period
- Throws:
DateTimeException- if elapsed time is nonzero
-
equals
-
hashCode
-
toString
Returns an ISO-style field representation with independent component signs, for exampleP14M-3DT4H5M6.789S. This is a value display, not portable SQL literal syntax. No public parser or text-storage convention is implied.
-